Prose bankruptcy, slice A (extdeps/std/src/docs): commentary rows become §4c annotations; docs tightened

LICENSING.md

@@ -1,8 +1,8 @@
 # Licensing — plain language
 
 gunbc is released under the [Business Source License 1.1](LICENSE) with an
-Additional Use Grant. This page explains what that means; the [LICENSE](LICENSE)
-file is the actual agreement and controls wherever the two differ.
+Additional Use Grant. This page is a plain-language summary; the [LICENSE](LICENSE)
+file is the agreement and controls wherever the two differ.
 
 ## The short version
 
@@ -26,19 +26,17 @@ clause, no royalty on output, and no obligation to contribute anything back.
 
 ## Is this open source?
 
-Not yet, and we would rather say so than blur it. While a release is inside its
-two-year window it is **source-available**: you can read it, modify it,
-redistribute it, and use it under the terms above, but the Open Source
-Initiative would not call it open source. Two years after a release ships, that
-release is plain MIT — genuinely open source, forever.
+Not yet. Inside its two-year window a release is **source-available**: you can
+read, modify, redistribute and use it under the terms above, but the Open Source
+Initiative would not call it open source. Two years after it ships, that release
+is plain MIT — open source, forever.
 
 ## Why this shape
 
 The paid boundary is the distance between the current frontier and the free
-trailing edge, and that distance exists only while the project is actively
-developed. If development stops, the trailing edge catches up and the
-commercial boundary disappears on its own — no adjudication, no argument about
-whether the maintainers still deserve it. The clock decides.
+trailing edge, which exists only while the project is actively developed. If
+development stops, the trailing edge catches up and the commercial boundary
+disappears on its own — no adjudication. The clock decides.
 
 ## Do I owe anything?
 
@@ -53,15 +51,14 @@ Work through it in order:
 4. Otherwise → production use needs a commercial license. Get in touch.
 
 "Corporate group" means the entities consolidated in your group's own financial
-statements — we use the accounting definition your auditor already applies
-rather than inventing one. If a contractor runs gunbc on your behalf, that is
-your use. If you merely consume someone else's product or output that happened
-to be built with gunbc, that is not your use at all.
+statements — the accounting definition your auditor already applies. A
+contractor running gunbc on your behalf is your use. Consuming someone else's
+product or output built with gunbc is not your use at all.
 
 ## History
 
 Releases made before this transition remain under the MIT license they shipped
-under; that grant is irrevocable and nothing here withdraws it.
+under; that grant is irrevocable.
 
 ## Contact
 

dag/examples/weather/README.md

@@ -1,8 +1,7 @@
 # Weather forecast (hero demo)
 
-A self-contained daglang program: domain types, pattern matching on a sum
-type, pure functions, and a list pipeline. It compiles to Rust with no
-hand-written glue.
+A self-contained daglang program — domain types, sum-type pattern matching, pure functions,
+a list pipeline — compiled to Rust with no hand-written glue.
 
 ## What it shows
 
@@ -44,5 +43,4 @@ All logic lives in [`weather.dag`](weather.dag). The compiler pulls in
 ## Tests in this repo
 
 `src/v1/tests` includes structural checks over the emitted Rust (L4
-bootstrap). That path is heavier than the gate above; the gate is the
-fast public smoke test.
+bootstrap) — heavier than the gate above, which is the fast public smoke test.

dag/extdeps/access/posix.dag

@@ -1,6 +1,5 @@
 module extdeps.access.posix
 
-
 import extdeps.external_authority { ExternalAuthority }
 import extdeps.uri { Uri, Https }
 import std.types { Bool, Int, NonEmptyStr, String }
@@ -92,14 +91,21 @@ type PosixUser {
   shell: PosixLoginShell
 }
 
-
 data posix_root_uid: Int = 0
 
 fn posix_user_is_root(user: PosixUser) -> Bool {
   user.uid == posix_root_uid
 }
 
-data file_mode_octal_note: String = "The octal spelling is a SERIALIZATION of FileMode, not a second representation of it — the same relation hex has to an sRGB triple. chmod's numeric mode is four octal digits, most significant first: setuid/setgid/sticky, then the owner, group, and other classes, each digit the sum read=4 + write=2 + execute=1 (Open Group sys/stat.h, the authority this module is anchored to). All four digits are rendered rather than the three this repo's callers happen to need today, because a serializer that silently dropped the special-bits digit would emit a mode that means something else the moment setgid is set — the leading digit is 0 here by computation, never by assumption. This exists because FilePermissions had no way to reach a host argv, which is a large part of why it sat modeled and unconsumed."
+// The octal spelling is a SERIALIZATION of FileMode, not a second representation of it — the same
+// relation hex has to an sRGB triple. chmod's numeric mode is four octal digits, most significant
+// first: setuid/setgid/sticky, then the owner, group, and other classes, each digit the sum read=4
+// + write=2 + execute=1 (Open Group sys/stat.h, the authority this module is anchored to). All four
+// digits are rendered rather than the three this repo's callers happen to need today, because a
+// serializer that silently dropped the special-bits digit would emit a mode that means something
+// else the moment setgid is set — the leading digit is 0 here by computation, never by assumption.
+// This exists because FilePermissions had no way to reach a host argv, which is a large part of why
+// it sat modeled and unconsumed.
 
 fn permission_bits_octal_digit(bits: PermissionBits) -> Int {
   let r = if bits.read { 4 } else { 0 }

dag/extdeps/access/posix_effective_principal_read_op.dag

@@ -14,7 +14,10 @@ data extdeps_external_authority_anchor: ExternalAuthority = ExternalAuthority {
   }
 }
 
-data posix_effective_principal_read_op_note: String = "Typed argv transport for access.PosixEffectivePrincipal.Read — program+args dispatch at the realization edge without shell.Exec.Run (Wave C5 / bash-emit #5828 slice). Hermetic realization refuses this external identity observation; its mock response is a failed read and cannot become principal evidence."
+// Typed argv transport for access.PosixEffectivePrincipal.Read — program+args dispatch at the
+// realization edge without shell.Exec.Run (Wave C5 / bash-emit #5828 slice). Hermetic realization
+// refuses this external identity observation; its mock response is a failed read and cannot become
+// principal evidence.
 
 fn posix_effective_principal_read_argv() -> List<String> {
   ["whoami"]

dag/extdeps/accessibility/wcag_contrast.dag

@@ -12,7 +12,23 @@ data extdeps_external_authority_anchor: ExternalAuthority = ExternalAuthority {
   }
 }
 
-data wcag_contrast_note: String = "Cited upstream: W3C WCAG 2.2, definitions of relative luminance and contrast ratio (retrieved 2026-07-21). Relative luminance L = 0.2126 R + 0.7152 G + 0.0722 B where each channel c (sRGB, 0..1) linearizes as: c <= 0.03928 -> c/12.92, else ((c+0.055)/1.055)^2.4 (the 0.03928 knee is WCAG's published constant). Contrast ratio = (L_lighter + 0.05) / (L_darker + 0.05); thresholds 4.5:1 (AA normal text), 3:1 (AA large text and non-text graphical objects, per SC 1.4.11), 7:1 (AAA). Arithmetic here is integer at scale 10000 (one unit = 0.0001). The single approximated kernel is the exponent 2.4, computed as x^2.4 = x^2 * (x^2)^(1/5) with the fifth root by integer Newton iteration at scale 1000 — deterministic, no floats, no lookup tables; wcag_pow24_pin_witnesses in the test claim pins it against hand-computable values of the cited formula. Threshold checks avoid the ratio division entirely: (L_hi + 0.05) >= t * (L_lo + 0.05) compared by integer cross-multiplication, so the pass/fail verdicts are exact up to channel-luminance precision (~2e-4). This module owns perceptual LAW only; the color-space representations it reads (Srgb8, RgbScaled, the HSL conversion) live in extdeps.color.srgb — accessibility consumes the color space, it does not own it (re-homed 2026-07-21, DESIGN sect 3). Entry points exist per authored representation (HSL for the site register's materials, Srgb8 for catalogued swatches) over ONE shared luminance kernel — one law, N representations, never a per-representation fork."
+// Cited upstream: W3C WCAG 2.2, definitions of relative luminance and contrast ratio (retrieved
+// 2026-07-21). Relative luminance L = 0.2126 R + 0.7152 G + 0.0722 B where each channel c (sRGB,
+// 0..1) linearizes as: c <= 0.03928 -> c/12.92, else ((c+0.055)/1.055)^2.4 (the 0.03928 knee is
+// WCAG's published constant). Contrast ratio = (L_lighter + 0.05) / (L_darker + 0.05); thresholds
+// 4.5:1 (AA normal text), 3:1 (AA large text and non-text graphical objects, per SC 1.4.11), 7:1
+// (AAA). Arithmetic here is integer at scale 10000 (one unit = 0.0001). The single approximated
+// kernel is the exponent 2.4, computed as x^2.4 = x^2 * (x^2)^(1/5) with the fifth root by integer
+// Newton iteration at scale 1000 — deterministic, no floats, no lookup tables;
+// wcag_pow24_pin_witnesses in the test claim pins it against hand-computable values of the cited
+// formula. Threshold checks avoid the ratio division entirely: (L_hi + 0.05) >= t * (L_lo + 0.05)
+// compared by integer cross-multiplication, so the pass/fail verdicts are exact up to
+// channel-luminance precision (~2e-4). This module owns perceptual LAW only; the color-space
+// representations it reads (Srgb8, RgbScaled, the HSL conversion) live in extdeps.color.srgb —
+// accessibility consumes the color space, it does not own it (re-homed 2026-07-21, DESIGN sect 3).
+// Entry points exist per authored representation (HSL for the site register's materials, Srgb8 for
+// catalogued swatches) over ONE shared luminance kernel — one law, N representations, never a
+// per-representation fork.
 
 fn imax(a: Int, b: Int) -> Int {
   if a > b { a } else { b }

dag/extdeps/advertising/google_ads.dag

@@ -19,9 +19,18 @@ data extdeps_external_authority_anchor: ExternalAuthority = ExternalAuthority {
 
 data google_ads_subject: Vendor<Securities> = alphabet
 
-data google_ads_subject_note: String = "Subject and source are orthogonal axes (operator ruling 2026-07-25, extdeps.pricing.gitlab_subscription precedent): the anchor above is the SOURCE (Google's own product help pages under support.google.com/google-ads), and the subject edge names the ENTITY -- the SEC issuer Alphabet Inc., the filing parent whose income statement reports Google advertising revenue. The consumer-facing product brand is Google Ads; no separate legal-entity row is minted for the operating subsidiary because no fact in this module is about corporate structure."
-
-data google_ads_provenance_note: String = "Interface facts live-fetched 2026-08-01 from two Google Ads Help pages: 'Determine a bid strategy based on your goals - Google Ads Help' (answer/2472725, the anchor) and 'Auction - Google Ads Help' (answer/142918). Neither page publishes any numeric price, minimum bid, or rate floor -- the pricing interface Google documents is a per-auction mechanism plus an advertiser-set budget cap, which is why the rate row below is AuctionDetermined rather than a money amount."
+// Subject and source are orthogonal axes (operator ruling 2026-07-25,
+// extdeps.pricing.gitlab_subscription precedent): the anchor above is the SOURCE (Google's own
+// product help pages under support.google.com/google-ads), and the subject edge names the ENTITY --
+// the SEC issuer Alphabet Inc., the filing parent whose income statement reports Google advertising
+// revenue. The consumer-facing product brand is Google Ads; no separate legal-entity row is minted
+// for the operating subsidiary because no fact in this module is about corporate structure.
+
+// Interface facts live-fetched 2026-08-01 from two Google Ads Help pages: 'Determine a bid strategy
+// based on your goals - Google Ads Help' (answer/2472725, the anchor) and 'Auction - Google Ads
+// Help' (answer/142918). Neither page publishes any numeric price, minimum bid, or rate floor --
+// the pricing interface Google documents is a per-auction mechanism plus an advertiser-set budget
+// cap, which is why the rate row below is AuctionDetermined rather than a money amount.
 
 type GoogleAdsBillableUnit
   = GoogleCostPerClick
@@ -69,7 +78,11 @@ fn google_ads_billable_unit_catalog() -> List<GoogleAdsBillableUnitRow> {
   ]
 }
 
-data google_ads_bid_strategy_roster_note: String = "Bid-strategy names transcribed verbatim from the anchor page 2026-08-01. Kept as a wire-label roster rather than a closed enum: this roster is product-versioned help prose, not a machine-facing API enum (the machine-facing contrast is extdeps.advertising.meta_ads, where billing_event and bid_strategy ARE published API enums). Strategies select what the auction optimizes; the billable unit stays one of the four rows above."
+// Bid-strategy names transcribed verbatim from the anchor page 2026-08-01. Kept as a wire-label
+// roster rather than a closed enum: this roster is product-versioned help prose, not a
+// machine-facing API enum (the machine-facing contrast is extdeps.advertising.meta_ads, where
+// billing_event and bid_strategy ARE published API enums). Strategies select what the auction
+// optimizes; the billable unit stays one of the four rows above.
 
 data google_ads_bid_strategy_wire_labels: List<NonEmptyStr> = [
   "Target cost per action (CPA)",
@@ -90,7 +103,10 @@ data google_ads_bid_strategy_wire_labels: List<NonEmptyStr> = [
 type GoogleAdsBudgetControl
   = | GoogleAverageDailyBudget
 
-data google_ads_budget_note: String = "The advertiser-side spend cap the page documents, quoted: 'All you have to do is set an average daily budget, and the Google Ads system automatically manages your bids to bring you the most clicks possible within your budget.' The budget is the advertiser's declared cap; the per-event price under it remains auction-determined."
+// The advertiser-side spend cap the page documents, quoted: 'All you have to do is set an average
+// daily budget, and the Google Ads system automatically manages your bids to bring you the most
+// clicks possible within your budget.' The budget is the advertiser's declared cap; the per-event
+// price under it remains auction-determined.
 
 type GoogleAdsAuctionTimeSignal
   = GoogleSignalDevice
@@ -99,9 +115,14 @@ type GoogleAdsAuctionTimeSignal
   | GoogleSignalLanguage
   | GoogleSignalOperatingSystem
 
+// The cited mechanism page ('Auction - Google Ads Help') describes selection and pricing by Ad
+// Rank, quoted: eligibility considers 'your bid, ad quality, the Ad Rank thresholds, the context of
+// the person's search, and the expected impact of extensions and other ad formats', and 'even if
+// your competition bids higher than you, you can still win a higher position -- at a lower price --
+// with highly relevant keywords and ads.' The page contains no numeric amounts, which is the fact
+// the AuctionDetermined arm carries.
+
 // Coarse-grain targeting dimensions exactly as the anchor page enumerates them, quoted: Smart Bidding 'factors in a wide range of auction-time signals such as device, location, time of day, language, and operating system to capture the unique context of every search.' The page says 'such as' -- this enum models the five signals the vendor names, and is deliberately NOT claimed closed over everything the auction reads.
 data google_ads_media_rate: AdPriceDetermination = AuctionDetermined {
   mechanism_citation: "support.google.com/google-ads/answer/142918",
 }
-
-data google_ads_auction_mechanism_note: String = "The cited mechanism page ('Auction - Google Ads Help') describes selection and pricing by Ad Rank, quoted: eligibility considers 'your bid, ad quality, the Ad Rank thresholds, the context of the person's search, and the expected impact of extensions and other ad formats', and 'even if your competition bids higher than you, you can still win a higher position -- at a lower price -- with highly relevant keywords and ads.' The page contains no numeric amounts, which is the fact the AuctionDetermined arm carries."

dag/extdeps/advertising/meta_ads.dag

@@ -19,7 +19,16 @@ data extdeps_external_authority_anchor: ExternalAuthority = ExternalAuthority {
 
 data meta_ads_subject: Vendor<Securities> = meta_platforms
 
-data meta_ads_provenance_note: String = "Interface facts live-fetched 2026-08-01 from the Meta Marketing API developer docs: the anchor page (which, per the API's legacy object naming, is the AD SET reference -- billing_event, bid_strategy, and optimization_goal are ad-set-level fields) and the bidding overview at developers.facebook.com/docs/marketing-api/bidding, which states the billing-event concept verbatim: the system 'defines events you want to pay for, including impressions, clicks, or various actions.' Two Business Help Center pages were attempted and are client-rendered (this fetch reads only their titles): 'About Ad Auctions | Meta Business Help Center' (facebook.com/business/help/430291176997542) and 'Best Practices for Minimum Budgets | Meta Business Help Center' (facebook.com/business/help/203183363050448) -- the latter is why the minimum-budget row below is RateUnavailable with that cause, never a remembered number."
+// Interface facts live-fetched 2026-08-01 from the Meta Marketing API developer docs: the anchor
+// page (which, per the API's legacy object naming, is the AD SET reference -- billing_event,
+// bid_strategy, and optimization_goal are ad-set-level fields) and the bidding overview at
+// developers.facebook.com/docs/marketing-api/bidding, which states the billing-event concept
+// verbatim: the system 'defines events you want to pay for, including impressions, clicks, or
+// various actions.' Two Business Help Center pages were attempted and are client-rendered (this
+// fetch reads only their titles): 'About Ad Auctions | Meta Business Help Center'
+// (facebook.com/business/help/430291176997542) and 'Best Practices for Minimum Budgets | Meta
+// Business Help Center' (facebook.com/business/help/203183363050448) -- the latter is why the
+// minimum-budget row below is RateUnavailable with that cause, never a remembered number.
 
 type MetaBillingEvent
   = MetaBillAppInstalls
@@ -168,7 +177,11 @@ fn meta_bid_strategy_catalog() -> List<MetaBidStrategyRow> {
   ]
 }
 
-data meta_optimization_goal_note: String = "optimization_goal wire values transcribed verbatim from the anchor reference 2026-08-01. Kept as a wire-value roster rather than a closed enum: this is the coarse-grain record that the axis EXISTS and is distinct from billing_event; per-goal modeling waits for a consumer that needs it (second-consumer discipline), and a 33-variant enum nobody eliminates over would be roster theater."
+// optimization_goal wire values transcribed verbatim from the anchor reference 2026-08-01. Kept as
+// a wire-value roster rather than a closed enum: this is the coarse-grain record that the axis
+// EXISTS and is distinct from billing_event; per-goal modeling waits for a consumer that needs it
+// (second-consumer discipline), and a 33-variant enum nobody eliminates over would be roster
+// theater.
 
 data meta_optimization_goal_wire_values: List<NonEmptyStr> = [
   "NONE",