@githolon/dsl 0.74.0 → 0.75.0

package/src/codegen_dart_client.ts

@@ -142,6 +142,17 @@ export interface DartBridgeClientOptions {
    * omitted. Only meaningful when {@link emitActivity} is set.
    */
   readonly activityImportUri?: string;
+  /**
+   * CROSS-DOMAIN REF TRAVERSAL (dart_codegen_parity.md §2a follow-on): every aggregate id in the
+   * PACKAGE → the domain module that owns it (`domain` for the client class name, `name` for the
+   * relative `<name>.client.dart` import). A same-workspace `t.ref` whose target lives in ANOTHER
+   * domain of this package emits a resolver taking THAT domain's generated client (the shared barrel
+   * makes the class + read model reachable; the client file imports the sibling client with `show`).
+   * Same-domain refs (target in THIS module) resolve via this client and never consult the map.
+   * Omit (or supply only self-owned aggregates) ⇒ NO cross-domain accessors are emitted — a package
+   * whose refs are all same-domain / foreign is byte-identical to before this existed.
+   */
+  readonly packageAggregateDomains?: Readonly<Record<string, { domain: string; name: string }>>;
 }
 
 /** Generate the `<name>.client.dart` async bridge client for one domain module. */
@@ -489,32 +500,54 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     );
   }
 
-  // ── REF-TRAVERSAL ACCESSORS (dart_codegen_parity.md P2 — ref ergonomics) ──
-  // For every SAME-WORKSPACE `t.ref(Target)` field whose target aggregate is ALSO in THIS domain module
-  // (so its by-id accessor is right here on this SAME client class), emit a companion extension method
-  // that resolves the stored ref id to the actual target row — reusing the EXISTING `<target>ById`
-  // by-id accessor above (no second read path, no new bridge op). SCOPE (deliberately narrow):
-  //   - `t.foreignRef` fields are NOT covered — a foreign ref crosses workspaces (its own locator +
-  //     attested-read trust plumbing, a different lane entirely; `ForeignRef<T>` stays as-is).
-  //   - a same-workspace ref field whose target aggregate is a CROSS-DOMAIN reference (not present in
-  //     `mod.aggregates`) is skipped too — its by-id accessor lives on a DIFFERENT domain's generated
-  //     client, unreachable from an extension scoped to this file.
-  // A domain with no resolvable ref field emits none of this (byte-identical to before this existed).
+  // ── REF-TRAVERSAL ACCESSORS (dart_codegen_parity.md P2 + §2a follow-on — ref ergonomics) ──
+  // For every reference field on a read model, emit a companion extension method that resolves the
+  // stored locator to the actual target row, composed ONLY from surface that already exists (no new
+  // read path, no new bridge op). THREE kinds, one grammar (`<Model>Refs on <Model>`):
+  //   1. SAME-DOMAIN `t.ref(Target)` (target in THIS module) — resolver takes THIS client, dispatches
+  //      to its own `<target>ById` accessor. (The #72 original.)
+  //   2. CROSS-DOMAIN same-workspace `t.ref(Target)` (target in ANOTHER domain of the package) — the
+  //      target's by-id accessor lives on the OTHER domain's client, so the resolver takes THAT client
+  //      (`asset.listing(CatalogueClient c)`); the shared package barrel makes the class + read model
+  //      reachable and the client file imports the sibling client with `show` (§2a follow-on).
+  //   3. CROSS-WORKSPACE `t.foreignRef` — the read model already surfaces the field as a typed
+  //      `ForeignRef<Target>`; the resolver is thin sugar over the ESTABLISHED foreign-read semantic
+  //      (`ref.resolve(engine.foreignReader())` — follow+read on the session-bound multi-workspace
+  //      plane, no clone), NOT the law-grade attested-read lane (that is `ref.attest`, opt-in via
+  //      `trustSource` + `.readsFrom`). Returns the typed concrete target row or null.
+  // A read model with no reference field emits nothing; a package with only same-domain / foreign refs
+  // (no cross-domain resolvable target) is byte-identical to before the §2a follow-on existed.
+  const pkgDomains = opts.packageAggregateDomains ?? {};
+  const thisDomainName = mod.name;
   const refExtensions: string[] = [];
+  // importUri → the set of sibling names the ref resolvers reference (imported `show`-limited): a
+  // cross-domain `t.ref` needs the sibling CLIENT class + its read model (from `<name>.client.dart`); a
+  // cross-domain `t.foreignRef` needs the target's concrete class (from the sibling TYPES `<name>.dart`).
+  const crossDomainImports = new Map<string, Set<string>>();
+  const addImport = (uri: string, name: string): void => {
+    if (!crossDomainImports.has(uri)) crossDomainImports.set(uri, new Set());
+    crossDomainImports.get(uri)!.add(name);
+  };
   for (const agg of mod.aggregates) {
     const model = readModelClassName(agg.id);
-    const refFields = Object.entries(agg.fields).filter(([, f]) => {
-      const field = f as Field;
-      return field.kind === "ref" && field.foreignRef === undefined && field.refAggregateId !== undefined;
-    }) as [string, Field][];
-    const targetableFields = refFields.filter(([, f]) => aggById.has(f.refAggregateId!));
-    if (targetableFields.length === 0) continue;
+    const entries = Object.entries(agg.fields) as [string, Field][];
+    const sameDomainRefs = entries.filter(
+      ([, f]) => f.kind === "ref" && f.foreignRef === undefined && f.refAggregateId !== undefined && aggById.has(f.refAggregateId!),
+    );
+    const crossDomainRefs = entries.filter(([, f]) => {
+      if (!(f.kind === "ref" && f.foreignRef === undefined && f.refAggregateId !== undefined)) return false;
+      if (aggById.has(f.refAggregateId!)) return false; // same-domain — handled above
+      const owner = pkgDomains[f.refAggregateId!];
+      return owner !== undefined && owner.domain !== domain; // resolvable on a SIBLING domain's client
+    });
+    const foreignRefs = entries.filter(([, f]) => f.kind === "ref" && f.foreignRef !== undefined);
+    if (sameDomainRefs.length === 0 && crossDomainRefs.length === 0 && foreignRefs.length === 0) continue;
     const lines: string[] = [
       `/// Ref-traversal accessors for [${model}] (dart_codegen_parity.md P2) — resolve a stored ref id`,
       `/// to the actual target row via the SAME by-id read lane already exposed above.`,
       `extension ${model}Refs on ${model} {`,
     ];
-    for (const [fieldName, f] of targetableFields) {
+    for (const [fieldName, f] of sameDomainRefs) {
       const targetType = f.refAggregateId!;
       const targetModel = readModelClassName(targetType);
       const targetConcrete = concreteClassName(targetType);
@@ -546,6 +579,76 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
         ``,
       );
     }
+    for (const [fieldName, f] of crossDomainRefs) {
+      const targetType = f.refAggregateId!;
+      const owner = pkgDomains[targetType]!;
+      const targetModel = readModelClassName(targetType);
+      const targetConcrete = concreteClassName(targetType);
+      const targetLc = lcFirst(camel(targetConcrete));
+      const byIdMethod = safeMethod(`${targetLc}ById`);
+      const targetClient = dartClientClassName(owner.domain);
+      // The sibling CLIENT file exposes both the client class AND (via its `export '<name>.dart'`) the
+      // read model — pull BOTH `show`-limited so this file references neither an unimported type.
+      const importUri = `${owner.name}.client.dart`;
+      addImport(importUri, targetClient);
+      addImport(importUri, targetModel);
+      const member = dartMemberName(fieldName);
+      const methodStem = member.length > 2 && member.endsWith("Id") ? member.slice(0, -2) : `${member}Ref`;
+      const method = safeMethod(methodStem);
+      const memberNullable = f.isFromBirth !== true;
+      lines.push(
+        `  /// Resolve \`${fieldName}\` (${agg.id}.${fieldName} -> ${targetType}, a CROSS-DOMAIN ref) by`,
+        `  /// dispatching to [${targetClient}.${byIdMethod}] on the target domain's client — same by-id`,
+        `  /// read lane, never a second one. The shared package barrel makes [${targetClient}] +`,
+        `  /// [${targetModel}] reachable; pass that domain's bound client.`,
+        `  Future<${targetModel}?> ${method}(${targetClient} client) async {`,
+        ...(memberNullable
+          ? [
+              `    final id = ${member};`,
+              `    if (id == null) return null;`,
+              `    final rows = await client.${byIdMethod}(id.value);`,
+            ]
+          : [`    final rows = await client.${byIdMethod}(${member}.value);`]),
+        `    return rows.isEmpty ? null : rows.first;`,
+        `  }`,
+        ``,
+      );
+    }
+    for (const [fieldName, f] of foreignRefs) {
+      const fr = f.foreignRef!;
+      const targetType = fr.targetAggregateId;
+      // The resolver returns the target's CONCRETE class (what `ForeignRef<T>.resolve` decodes to). We can
+      // only reference it when it is reachable from this file: SAME-domain (already in the imported types),
+      // or a CROSS-DOMAIN concrete target in the package (import its sibling `<name>.dart` `show`-limited).
+      // A contract target (its DTO lives in the shared contracts file) or an unmapped target is left as the
+      // raw `ForeignRef<T>` field — no resolver, no dangling type reference.
+      if (fr.targetIsContract === true) continue;
+      const owner = pkgDomains[targetType];
+      const targetInThisDomain = aggById.has(targetType) || owner?.name === thisDomainName;
+      if (!targetInThisDomain) {
+        if (owner === undefined) continue; // target not in this package — unreachable, skip the resolver
+        addImport(`${owner.name}.dart`, concreteClassName(targetType));
+      }
+      const targetConcrete = concreteClassName(targetType);
+      const member = dartMemberName(fieldName);
+      // The stored locator member is a typed `ForeignRef<Target>?` getter, so the resolver takes a
+      // `remote…` name to avoid colliding with it (and to read as "the far side of the reference").
+      const method = safeMethod(`remote${cap(camel(member))}`);
+      lines.push(
+        `  /// Resolve \`${fieldName}\` (${agg.id}.${fieldName} -> ${targetType} @ another workspace, a`,
+        `  /// \`t.foreignRef\` locator) over the session-bound multi-workspace plane —`,
+        `  /// \`${member}.resolve(engine.foreignReader())\`, which opens the foreign workspace ON DEMAND`,
+        `  /// (no clone). This is the informational follow+read lane, NOT the law-grade attested-read one`,
+        `  /// (use \`${member}!.attest(engine.foreignReader())\` when your law depends on the foreign fact).`,
+        `  /// Null locator (absent / empty id or workspace) ⇒ null.`,
+        `  Future<${targetConcrete}?> ${method}(NomosEngine engine, {String? cloud}) {`,
+        `    final ref = ${member};`,
+        `    if (ref == null) return Future<${targetConcrete}?>.value(null);`,
+        `    return ref.resolve(engine.foreignReader(cloud: cloud));`,
+        `  }`,
+        ``,
+      );
+    }
     lines.push(`}`);
     refExtensions.push(lines.join("\n"));
   }
@@ -631,6 +734,14 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     // Framework-shared aggregate types (RelationTupleReadModel, …) live in the ONE shared file — import
     // them (the by-id accessors reference them) and re-export them (once per package, Dart de-dups).
     ...(opts.typesImportUri === undefined && opts.frameworkImportUri !== undefined ? [`import '${opts.frameworkImportUri}';`] : []),
+    // CROSS-DOMAIN REF TRAVERSAL (§2a follow-on): a cross-domain resolver references a SIBLING domain's
+    // generated client class + read model (from `<name>.client.dart`) or a foreignRef target's concrete
+    // class (from the sibling TYPES `<name>.dart`) — all co-located in the same generated dir (flat OR
+    // layered), so a same-dir relative import `show`-limited to exactly the referenced names. Empty for a
+    // domain with no cross-domain ref (byte-identical to before this existed).
+    ...[...crossDomainImports.entries()]
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([uri, names]) => `import '${uri}' show ${[...names].sort().join(", ")};`),
     `// Re-export the sibling types (read models + payloads + the bridge runtime) so ONE import of this`,
     `// client file gives an app the whole typed surface.`,
     ...(opts.typesImportUri !== undefined ? [`export '${opts.typesImportUri}';`] : [`export '${mod.name}.dart';`]),

package/src/codegen_ts.ts

@@ -1499,7 +1499,24 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `_stampRefsP(holon.workspace, ${foreignRefFields.length > 0 ? `_hydrateP(${expr})` : expr})`;
   const wrapRows = (expr: string): string =>
     `_stampRefs(holon.workspace, ${foreignRefFields.length > 0 ? `_hydrateRows(${expr})` : expr})`;
+  // ATTRIBUTED READS (architecture/field_provenance.md): the shared provenance shape +
+  // per-aggregate accessors — emitted ONLY when the package declares ≥1 `.attributed()`
+  // field, so a provenance-free package's client is byte-identical (the era rule).
+  const anyAttributed = [...aggByType.values()].some(
+    (a) => ((a as { attributedFields?: readonly string[] }).attributedFields ?? []).length > 0,
+  );
+  if (anyAttributed) {
+    out.push(
+      `/** Per-field AUTHOR PROVENANCE (attributed reads — field_provenance.md): the verified`,
+      ` * author of the field's CURRENT value (null when unknown — an anonymous or`,
+      ` * pre-attribution-era write) + whether an auto-merge discarded a concurrent competing`,
+      ` * write since it landed (escalate the field to Surfaced(...) law to retain the values). */`,
+      `export interface FieldProvenance { author: string | null; wasContested: boolean }`,
+      ``,
+    );
+  }
   for (const [typeId, agg] of [...aggByType].sort(([a], [b]) => a.localeCompare(b))) {
+    const attributed = (agg as { attributedFields?: readonly string[] }).attributedFields ?? [];
     out.push(`export interface ${typeId}Data {`);
     for (const [name, field] of Object.entries(agg.fields)) {
       const required = (field as Field).isFromBirth === true;
@@ -1509,8 +1526,35 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       const fr = (field as { foreignRef?: { workspaceField: string; targetAggregateId: string } }).foreignRef;
       if (fr !== undefined) foreignRefFields.push({ agg: typeId, field: name, workspaceField: fr.workspaceField, target: fr.targetAggregateId });
     }
+    if (attributed.length > 0) {
+      out.push(
+        `  /** attributed-read provenance (the reserved per-row map; prefer the generated accessors) */`,
+        `  "__prov"?: { ${attributed.map((f) => `${f}?: FieldProvenance`).join("; ")} };`,
+      );
+    }
     for (const extra of extrasByType.get(typeId) ?? []) out.push(extra);
     out.push(`}`, ``);
+    if (attributed.length > 0) {
+      const ns = camel(typeId);
+      out.push(
+        `/** Attributed-read accessors for ${typeId} (\`.attributed()\` fields only): per-field`,
+        ` * provenance + the \`lastAuthors\` convenience (verified author per attributed field,`,
+        ` * unknown-author fields omitted). */`,
+        `export const ${ns}Provenance = {`,
+        ...attributed.map(
+          (f) => `  ${f}: (data: ${typeId}Data): FieldProvenance | undefined => data.__prov?.${f},`,
+        ),
+        `  lastAuthors: (data: ${typeId}Data): Record<string, string> => {`,
+        `    const out: Record<string, string> = {};`,
+        `    for (const [field, p] of Object.entries(data.__prov ?? {})) {`,
+        `      if (p !== undefined && p.author !== null) out[field] = p.author;`,
+        `    }`,
+        `    return out;`,
+        `  },`,
+        `} as const;`,
+        ``,
+      );
+    }
   }
   // MULTI-WORKSPACE LOCATOR FACTORY (t.foreignRef): per aggregate, a typed builder that turns a projection
   // row into a `ForeignRef<TargetData>` — reading the foreign id (the field) + the foreign workspace id (the

package/src/compile_package_main.ts

@@ -500,6 +500,24 @@ function collectPackageContracts(modules: readonly DomainModule[]): ContractHand
   return [...byId.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 }
 
+/**
+ * CROSS-DOMAIN REF TRAVERSAL map (dart_codegen_parity.md §2a follow-on): every aggregate id in the package
+ * → its owning domain (`domain` for the generated client class name; `name` for the sibling
+ * `<name>.client.dart` import). Handed to `generateDartBridgeClient` so a same-workspace `t.ref` whose
+ * target lives in ANOTHER domain of the package emits a resolver taking that domain's client. A same-domain
+ * ref never consults this (its target is in the local module); a foreign ref uses its own locator.
+ */
+function buildPackageAggregateDomains(
+  modules: readonly DomainModule[],
+): Record<string, { domain: string; name: string }> {
+  const map: Record<string, { domain: string; name: string }> = {};
+  for (const m of modules) {
+    const owner = { domain: m.domain ?? m.name, name: m.name };
+    for (const agg of (m.aggregates as { id: string }[])) map[agg.id] = owner;
+  }
+  return map;
+}
+
 /**
  * CIRCULAR-DEPENDENCY GUARD (domain_contracts.md). A `t.foreignRef` targeting a CONCRETE aggregate makes
  * the referencing domain's generated file import the target domain's file. Two domains that concretely
@@ -789,6 +807,11 @@ function emitDart(
   for (const m of modules) {
     for (const agg of (m.aggregates as { id: string }[])) aggIdToDartFile.set(agg.id, m.name);
   }
+  // CROSS-DOMAIN `t.ref` traversal (dart_codegen_parity.md §2a follow-on): the generated ref-traversal
+  // accessor for a same-workspace ref whose target lives in ANOTHER domain of THIS package takes that
+  // domain's client. Map every aggregate id → its owning domain (for the client class name) + file base
+  // (for the sibling `<name>.client.dart` import). Shared across both Dart-emit lanes.
+  const packageAggregateDomains = buildPackageAggregateDomains(modules);
   // CIRCULAR-DEP GUARD (domain_contracts.md): concrete-domain → concrete-domain import edges (from
   // concrete-aggregate-target foreignRefs). A 2-cycle A→B & B→A is the anti-pattern contracts exist to
   // break — fail with a clear diagnostic. Contract-mediated refs go through contracts.dart (no concrete edge).
@@ -845,6 +868,7 @@ function emitDart(
       supportImport,
       ...(domainFrameworkImport !== undefined ? { frameworkImportUri: domainFrameworkImport } : {}),
       ...(packageActivity.length > 0 ? { emitActivity: true, ...(activityImportUri !== undefined ? { activityImportUri } : {}) } : {}),
+      packageAggregateDomains,
     });
     const cp = path.join(genDir, `${mod.name}.client.dart`);
     writeFileSync(cp, clientSrc, "utf8");
@@ -904,7 +928,7 @@ const NOMOS_TYPES_DEP = "^0.3.0";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.50.0";
+const NOMOS_CLIENT_DEP = "^0.51.0";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in dsl/dart/pubspec.yaml
 // and dsl/dart_types/pubspec.yaml — a Dart release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).
@@ -1181,6 +1205,7 @@ function emitDartPackages(
       supportImport: "package",
       typesImportUri,
       ...(packageActivity.length > 0 ? { emitActivity: true } : {}),
+      packageAggregateDomains: buildPackageAggregateDomains(modules),
     });
     const cp = path.join(clientGen, `${mod.name}.client.dart`);
     writeFileSync(cp, clientSrc, "utf8");

package/src/drivers.ts

@@ -37,7 +37,8 @@ export type KernelDriverKind =
   | "RemoveWins"
   | "Counter"
   | "LastPosition"
-  | "Surfaced";
+  | "Surfaced"
+  | "Attributed";
 /**
  * Drivers in the design palette the kernel does not yet merge. Currently EMPTY —
  * every palette driver encodes. Kept as a (never-)union so a future palette
@@ -183,6 +184,13 @@ export function encodeDriver(d: Driver): WireDriver {
     case "MapOf":
       if (!d.inner) throw new Error("MapOf driver is missing its inner driver");
       return { MapOf: encodeDriver(d.inner) };
+    case "Attributed":
+      // serde newtype variant `Driver::Attributed(Box<Driver>)` → `{ "Attributed": <inner> }`
+      // (architecture/field_provenance.md — the wrapper aggregate() applies for
+      // `.attributed()` fields; a pre-provenance kernel's strict manifest serde refuses
+      // it, the clean era refusal).
+      if (!d.inner) throw new Error("Attributed driver is missing its inner driver");
+      return { Attributed: encodeDriver(d.inner) };
     case "Surfaced":
       // serde newtype variant `Driver::Surfaced(Box<Driver>)` → `{ "Surfaced": <inner> }`
       // (externally tagged, mirroring MapOf exactly).

package/src/fields.ts

@@ -361,6 +361,18 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    * the `encrypted()` METHOD sets it, mirroring `optional()`/`isOptional`.)
    */
   readonly isEncrypted?: true;
+  /**
+   * ATTRIBUTED READS (architecture/field_provenance.md): keep per-field AUTHOR PROVENANCE
+   * beside this field's folded value — `author` (the verified principal of the current
+   * value) + `wasContested` (did an auto-merge discard a concurrent competing write?).
+   * O(1) per field forever (one author + one boolean — the ledger stays the history;
+   * escalate to `.merge(Surfaced(...))` if you need the discarded VALUES). PRESENT only
+   * when declared; the wire driver becomes `{"Attributed": <inner>}` (a LAW change —
+   * old kernels refuse it cleanly, unattributed fields are byte-identical). VALID ONLY
+   * on Lww-class scalar fields; `aggregate()` enforces it. (Flag named `isAttributed` —
+   * the `attributed()` METHOD sets it, mirroring `encrypted()`/`isEncrypted`.)
+   */
+  readonly isAttributed?: true;
   /**
    * METADATA (secure-by-default rework — `secure_by_default_dsl.md`): on an `.owned()` aggregate the
    * default is that content fields are E2E (operator-blind); `.meta()` opts THIS field OUT to plaintext,
@@ -385,6 +397,9 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
   withFacet<Fa extends FieldFacet>(facet: Fa): Field<T, K> & { readonly facet: Fa };
   /** Mark this field's value ENCRYPTED (sets {@link Field.isEncrypted}). Chainable + non-destructive. */
   encrypted(): Field<T, K>;
+  /** Keep AUTHOR PROVENANCE beside this field's folded value (sets {@link Field.isAttributed}) —
+   *  `<field>Provenance` accessors are generated on the read models. Lww-class scalars only. */
+  attributed(): Field<T, K>;
   /** Mark this field plaintext METADATA (sets {@link Field.isMeta}) — the indexable opt-out on an owned aggregate. */
   meta(): Field<T, K>;
   /**
@@ -432,6 +447,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     valueObject?: ValueObjectFieldMeta;
     mapValueVo?: ValueObjectFieldMeta;
     encrypted?: true;
+    attributed?: true;
     meta?: true;
     facet?: FieldFacet;
     nullSemantic?: NullSemantic;
@@ -456,6 +472,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     ...(extra.valueObject !== undefined ? { valueObject: extra.valueObject } : {}),
     ...(extra.mapValueVo !== undefined ? { mapValueVo: extra.mapValueVo } : {}),
     ...(extra.encrypted ? { isEncrypted: true as const } : {}),
+    ...(extra.attributed ? { isAttributed: true as const } : {}),
     ...(extra.meta ? { isMeta: true as const } : {}),
     ...(extra.fromBirth ? { isFromBirth: true as const } : {}),
     ...(extra.nullSemantic !== undefined ? { nullSemantic: extra.nullSemantic } : {}),
@@ -513,6 +530,12 @@ function makeField<T, K extends FieldKind = FieldKind>(
       // `nomosEncryption` era key, built by aggregate()/manifest, is what carries the fact.
       return makeField<T, K>(kind, zod, driver, { ...extra, encrypted: true });
     },
+    attributed(): Field<T, K> {
+      // Carry the flag through merge/optional (extra is threaded), so `.merge(Lww).attributed()`
+      // and `.attributed().merge(Lww)` agree. aggregate() validates Lww-class eligibility and
+      // wraps the wire driver in `{"Attributed": <inner>}` (the law-era mechanism).
+      return makeField<T, K>(kind, zod, driver, { ...extra, attributed: true });
+    },
     meta(): Field<T, K> {
       // Plaintext-metadata opt-out (owned aggregates) — threaded through merge/optional like `encrypted`.
       // Driver/schema unchanged; the fact rides the aggregate's audience surface, not the wire kind.

package/src/manifest.ts

@@ -107,6 +107,14 @@ export interface CanonicalAggregate {
    * so adding/changing it MOVES the hash. The scope is the aggregate's `requiresRead`.
    */
   readonly encryptedFields?: string[];
+  /**
+   * ATTRIBUTED READS (architecture/field_provenance.md) — the STORED field names whose
+   * folded values keep author provenance (`.attributed()`), SORTED. PRESENT only when
+   * ≥1 field is attributed; OMITTED otherwise (an unattributed aggregate is
+   * byte-identical). The hash-bearing LAW is the wrapped `{"Attributed": <inner>}`
+   * driver in `schema`; this key is the self-describing mirror codegen/openapi read.
+   */
+  readonly attributedFields?: string[];
 }
 
 /** One captured directive contract — NO `plan`/`scopeFrom` behaviour. */
@@ -1057,6 +1065,9 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
       // E2E ENCRYPTION (slice 2) — the encrypted field names. Hash-bearing law;
       // omit-when-none so plaintext aggregates are byte-stable.
       ...(agg.encryptedFields !== undefined ? { encryptedFields: [...agg.encryptedFields] } : {}),
+      // ATTRIBUTED READS — the attributed field names (the driver wrap in `schema` is
+      // the hash-bearing law; this mirror is what codegen reads). Omit-when-none.
+      ...(agg.attributedFields !== undefined ? { attributedFields: [...agg.attributedFields] } : {}),
       };
     })
     .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));

package/src/usd.ts

@@ -238,6 +238,21 @@ export interface UsdLayer {
    * as `queries`/`references`. Hand-adding it to a foreign bundle only opts IN to
    * stricter checking; removing it makes new law, for that law's own chains (status quo).
    */
+  /**
+   * THE ATTRIBUTED-READS DECLARATION (architecture/field_provenance.md — "the law is the
+   * era"). Present IFF the layer declares ≥1 `.attributed()` field: the law's EXPLICIT
+   * opt-in to per-field author-provenance capture at the one gate/fold. The hash-bearing
+   * enforcement rides the aggregate schema's `{"Attributed": <inner>}` wire driver (a
+   * pre-provenance kernel's strict manifest serde REFUSES it — the clean era refusal);
+   * this key is the SELF-DESCRIBING surface (which aggregates/fields are attributed)
+   * hosts and tooling read without re-deriving it from drivers. OMITTED for
+   * unattributed law — byte-identical hash, the `nomosInvariantGate` discipline.
+   */
+  readonly nomosAttributedGate?: {
+    readonly v: 1;
+    /** aggregate TYPE → its attributed STORED field names, keys + fields sorted. */
+    readonly aggregates: Record<string, string[]>;
+  };
   readonly nomosInvariantGate?: {
     readonly v: 1;
     /** Aggregate types whose declared `invariant` bodies the gate executes, sorted. */
@@ -1332,8 +1347,14 @@ export function emitUsd(
       // (byte-determinism); omit-when-empty so an all-public layer is byte-identical.
       const visAggregates: Record<string, { requires: string }> = {};
       const encAggregates: Record<string, { scope: string; fields: string[]; delegatable: false }> = {};
+      // ATTRIBUTED READS (field_provenance.md): aggregate TYPE → its attributed field
+      // names — the self-describing nomosAttributedGate era key. Omit-when-empty.
+      const attrAggregates: Record<string, string[]> = {};
       for (const a of [...manifest.aggregates].sort((x, y) => (x.id < y.id ? -1 : x.id > y.id ? 1 : 0))) {
         if (a.requiresRead !== undefined) visAggregates[a.id] = { requires: a.requiresRead };
+        if (a.attributedFields !== undefined && a.attributedFields.length > 0) {
+          attrAggregates[a.id] = [...a.attributedFields];
+        }
         // THE ENCRYPTION GATE (slice 2): an aggregate with encrypted field(s) — its scope
         // is its read cap (aggregate()/the gate guarantee they coincide). delegatable:false.
         if (a.encryptedFields !== undefined && a.encryptedFields.length > 0 && a.requiresRead !== undefined) {
@@ -1486,6 +1507,9 @@ export function emitUsd(
         ...(Object.keys(encAggregates).length > 0
           ? { nomosEncryption: { v: 1 as const, aggregates: encAggregates } }
           : {}),
+        ...(Object.keys(attrAggregates).length > 0
+          ? { nomosAttributedGate: { v: 1 as const, aggregates: attrAggregates } }
+          : {}),
         ...(nomosCapabilities.length > 0
           ? { nomosCapabilities: { v: 1 as const, capabilities: nomosCapabilities } }
           : {}),

package/src/usd_layers.ts

@@ -111,6 +111,8 @@ export function driverToken(driver: WireDriver): string {
   if ("LwwBy" in driver) return `LwwBy(${driver.LwwBy})`;
   // `Surfaced(<inner>)` — the user-resolvable posture stays legible in the tree too.
   if ("Surfaced" in driver) return `Surfaced(${driverToken(driver.Surfaced)})`;
+  // `Attributed(<inner>)` — attributed reads (field_provenance.md), legible in the tree.
+  if ("Attributed" in driver) return `Attributed(${driverToken(driver.Attributed)})`;
   return `MapOf(${driverToken(driver.MapOf)})`;
 }
 
@@ -122,6 +124,9 @@ export function parseDriverToken(token: string): WireDriver {
   if (token.startsWith("Surfaced(") && token.endsWith(")")) {
     return { Surfaced: parseDriverToken(token.slice("Surfaced(".length, -1)) };
   }
+  if (token.startsWith("Attributed(") && token.endsWith(")")) {
+    return { Attributed: parseDriverToken(token.slice("Attributed(".length, -1)) };
+  }
   // `LwwBy(<principal>)` — the principal is an opaque non-empty string (uids carry
   // hyphens, so it is NOT the bare-identifier shape the unit-driver branch validates).
   if (token.startsWith("LwwBy(") && token.endsWith(")")) {
@@ -175,6 +180,9 @@ function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string):
     ...(layer.nomosEncryption !== undefined
       ? [`${indent}custom string nomos:encryptionHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosEncryption)))}`]
       : []),
+    ...(layer.nomosAttributedGate !== undefined
+      ? [`${indent}custom string nomos:attributedGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosAttributedGate)))}`]
+      : []),
     ...(layer.nomosRelations !== undefined
       ? [`${indent}custom string nomos:relationsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosRelations)))}`]
       : []),
@@ -767,6 +775,21 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         encryption = { v: 1, aggregates: aggregatesRec };
       }
     }
+    // THE ATTRIBUTED-READS GATE (field_provenance.md): per-aggregate attributed-field
+    // sets merged later-wins, SORTED keys (matching the composed emission). Omit-when-empty.
+    let attributedGate: UsdLayer["nomosAttributedGate"];
+    {
+      const a = new Map<string, string[]>();
+      for (const l of stack) {
+        if (l.nomosAttributedGate === undefined) continue;
+        for (const [type, fields] of Object.entries(l.nomosAttributedGate.aggregates)) a.set(type, fields);
+      }
+      if (a.size > 0) {
+        const aggregatesRec: Record<string, string[]> = {};
+        for (const k of [...a.keys()].sort()) aggregatesRec[k] = a.get(k)!;
+        attributedGate = { v: 1, aggregates: aggregatesRec };
+      }
+    }
     // THE RELATION SCHEMA (P1): per-type relation defs merged later-wins across the stack,
     // SORTED keys (matching the composed emission). Omit-when-empty (the nomosRelations era rule).
     let relations: UsdLayer["nomosRelations"];
@@ -1002,6 +1025,7 @@ return {
       ...(readGate !== undefined ? { nomosReadGate: readGate } : {}),
       ...(readVisibility !== undefined ? { nomosReadVisibility: readVisibility } : {}),
       ...(encryption !== undefined ? { nomosEncryption: encryption } : {}),
+      ...(attributedGate !== undefined ? { nomosAttributedGate: attributedGate } : {}),
       ...(relations !== undefined ? { nomosRelations: relations } : {}),
       ...(relationNamespace !== undefined ? { nomosRelationNamespace: relationNamespace } : {}),
       ...(readProjectionNamespace !== undefined ? { nomosReadProjectionNamespace: readProjectionNamespace } : {}),
@@ -1143,6 +1167,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const readGateByDomain = new Map<string, UsdLayer["nomosReadGate"]>();
   const readVisibilityByDomain = new Map<string, UsdLayer["nomosReadVisibility"]>();
   const encryptionByDomain = new Map<string, UsdLayer["nomosEncryption"]>();
+  const attributedGateByDomain = new Map<string, UsdLayer["nomosAttributedGate"]>();
   const relationsByDomain = new Map<string, UsdLayer["nomosRelations"]>();
   const relationGateByDomain = new Map<string, UsdLayer["nomosRelationGate"]>();
   const relationNamespaceByDomain = new Map<string, UsdLayer["nomosRelationNamespace"]>();
@@ -1193,6 +1218,11 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof encHex === "string") {
         encryptionByDomain.set(domain, JSON.parse(unhexUtf8(encHex)) as UsdLayer["nomosEncryption"]);
       }
+      // THE ATTRIBUTED-READS GATE (field_provenance.md): the hex-carried per-aggregate map.
+      const attrHex = p.attrs.get("nomos:attributedGateHex");
+      if (typeof attrHex === "string") {
+        attributedGateByDomain.set(domain, JSON.parse(unhexUtf8(attrHex)) as UsdLayer["nomosAttributedGate"]);
+      }
       // THE RELATION SCHEMA (P1): the hex-carried per-type relation rewrite map.
       const relHex = p.attrs.get("nomos:relationsHex");
       if (typeof relHex === "string") {
@@ -1359,6 +1389,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const rg = readGateByDomain.get(domain);
       const rv = readVisibilityByDomain.get(domain);
       const enc = encryptionByDomain.get(domain);
+      const attrGate = attributedGateByDomain.get(domain);
       const rel = relationsByDomain.get(domain);
       const relGate = relationGateByDomain.get(domain);
       const relNs = relationNamespaceByDomain.get(domain);
@@ -1386,6 +1417,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(rg !== undefined ? { nomosReadGate: rg } : {}),
         ...(rv !== undefined ? { nomosReadVisibility: rv } : {}),
         ...(enc !== undefined ? { nomosEncryption: enc } : {}),
+        ...(attrGate !== undefined ? { nomosAttributedGate: attrGate } : {}),
         ...(rel !== undefined ? { nomosRelations: rel } : {}),
         ...(relNs !== undefined ? { nomosRelationNamespace: relNs } : {}),
         ...(rpNs !== undefined ? { nomosReadProjectionNamespace: rpNs } : {}),

package/src/wire.ts

@@ -222,7 +222,11 @@ export type WireDriver =
   | { MapOf: WireDriver }
   // `Surfaced(Box<Driver>)` — the user-resolvable third merge posture
   // (architecture/surfaced_merge_conflict.md): `{ "Surfaced": <inner> }`.
-  | { Surfaced: WireDriver };
+  | { Surfaced: WireDriver }
+  // `Attributed(Box<Driver>)` — attributed reads (architecture/field_provenance.md):
+  // `{ "Attributed": <inner> }`. Value semantics = the inner driver's; the wrapper makes
+  // the fold capture per-field author provenance.
+  | { Attributed: WireDriver };
 
 /** `Schema = BTreeMap<FieldId, Driver>` — a plain object, field -> Driver. */
 export type WireSchema = Record<string, WireDriver>;