@githolon/dsl 0.100.6 → 0.101.0

package/src/directive.ts

@@ -20,7 +20,6 @@ import type { AggregateHandle, ReadModelRow } from "./aggregate.js";
 import type { Field } from "./fields.js";
 import type { PlannedOp } from "./ops.js";
 import type { Ports } from "./ctx.js";
-import type { CertifiedReadDecl } from "./certified_read.js";
 import type { RelationDecl } from "./relation.js";
 import type { QueryDecl } from "./query.js";
 import { normalizeActivity, type ActivityInput, type ActivityDescriptor } from "./activity.js";
@@ -117,12 +116,14 @@ export interface Directive<P = unknown> {
    */
   readonly description?: string;
   /**
-   * OPT-IN user-facing ACTIVITY metadata (`architecture/activity_descriptors.md`) — the kind/title/message
+   * Optional user-facing ACTIVITY polish (`architecture/activity_descriptors.md`) — the kind/title/message
    * template, refs, params, category/icon/severity a client uses to render a typed activity row from this
    * directive's intents (no string-enricher). Set by `.activity({...})`; NON-LAW, additive (same class as
    * `description` — a directive that never declares activity is byte-identical). Normalized + validated at
-   * author time. `undefined` ⇒ this directive contributes no activity row. (The setter is `.activity({...})`;
-   * this stored field is `activityDescriptor` to avoid a method/field name clash on `RequirableDirective`.)
+   * author time. `undefined` ⇒ codegen supplies the framework-owned baseline row from this directive's
+   * business name, declared effects and verified author/time; the change never disappears from the story.
+   * (The setter is `.activity({...})`; this stored field is `activityDescriptor` to avoid a method/field
+   * name clash on `RequirableDirective`.)
    */
   readonly activityDescriptor?: ActivityDescriptor;
   /**
@@ -258,19 +259,6 @@ export interface Directive<P = unknown> {
    * (declares no emits). Gate-side enforcement (emitted ⊆ declared) is a later step.
    */
   readonly declaredEmits: Record<string, { max?: number }>;
-  /**
-   * The directive's DECLARED CertifiedReads (survival Constraint 5; `certified_read.md`
-   * §"Tenant authoring"): the profiled, named write-path reads its `decide()` consults — the
-   * `reads:{ name: q.someProfiledRead(args) }` shape, keyed by the LOCAL binding name. Each
-   * value is a profile-conforming {@link CertifiedReadDecl} (compiled through SQL-profile-v0 at
-   * `certifiedRead(...).sql(...)`, so an under-specified read is refused at COMPILE). The
-   * declared `query_id`s LAND IN THE CERTIFIED MANIFEST (`manifest.ts`), so the ONE write-path
-   * gate (`executor::admit` step 5.6) DERIVES the expected declared-read set and REFUSES any
-   * admit where a declared read produced no witness (the vacuous-pass close). Defaults to `{}`
-   * (declares no write-path reads) — OMITTED ENTIRELY from the manifest when empty, so a
-   * read-free directive's canonical manifest is byte-identical to before this existed.
-   */
-  readonly declaredCertifiedReads: Record<string, CertifiedReadDecl>;
   /**
    * The directive's DECLARED cross-workspace relations (`cross_workspace.md` §2): the relations
    * a cross-workspace PR proposing THIS directive is adjudicated against. The TARGET domain
@@ -480,19 +468,6 @@ export interface RequirableDirective<P> extends Directive<P> {
    * var / missing payload field refuse). Non-law, additive; a directive that never calls it is byte-identical.
    */
   activity(input: ActivityInput): RequirableDirective<P>;
-  /**
-   * Declare the directive's CertifiedReads (survival Constraint 5; `certified_read.md`
-   * §"Tenant authoring") — the profiled, named write-path reads its `decide()` consults, the
-   * `reads:{ name: q.someProfiledRead(args) }` shape. Each value is a {@link CertifiedReadDecl}
-   * (built via `certifiedRead("id").sql("…", {multiRow,uniqueTieBreakers})`, which refuses an
-   * under-specified read at COMPILE through SQL-profile-v0). The declared `query_id`s LAND IN
-   * THE CERTIFIED MANIFEST, so the ONE write-path gate DERIVES the required-read set and refuses
-   * any admit where a declared read produced no witness (the vacuous-pass close). Callable
-   * multiple times to accumulate (a repeated local name's later decl wins). Purely additive +
-   * non-destructive — a directive that never calls this declares no write-path reads (`{}`) and
-   * is byte-identical in the manifest to before this existed. Returns a NEW requirable directive.
-   */
-  readsCertified(reads: Record<string, CertifiedReadDecl>): RequirableDirective<P>;
   /**
    * Declare a cross-workspace relation (`cross_workspace.md` §2) this directive (the TARGET of a
    * cross-workspace PR's `proposes`) is adjudicated against — built via
@@ -697,7 +672,6 @@ class DirectivePlanStep<Id extends string, P> {
       declaredReads: [],
       declaredQueryReads: [],
       declaredEmits: {},
-      declaredCertifiedReads: {},
       declaredRelations: [],
       declaredHostCapabilities: [],
       // `.withId(...)` — record the caller-supplied-id extractor (codegen/authoring hint). The `absent`
@@ -935,13 +909,6 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       ];
       return makeRequirable({ ...base, activityDescriptor: normalizeActivity(base.id, input, base.payloadSchema, createdIds) });
     },
-    readsCertified(reads: Record<string, CertifiedReadDecl>): RequirableDirective<P> {
-      // Accumulate onto any prior declared CertifiedReads (a repeated local name's later decl
-      // wins) — additive, non-destructive. The local binding NAME (the key) is what `decide`
-      // reads via `reads.<name>`; the decl's `queryId` is the manifest-landed identity.
-      const merged: Record<string, CertifiedReadDecl> = { ...base.declaredCertifiedReads, ...reads };
-      return makeRequirable({ ...base, declaredCertifiedReads: merged });
-    },
     declaresRelation(rel: RelationDecl): RequirableDirective<P> {
       // Accumulate onto any prior relations — additive, non-destructive. A relation lands in
       // the manifest keyed by its `proposes` directive (cross_workspace.md §3.2.1).

package/src/drivers.ts

@@ -23,6 +23,7 @@ import type { WireDriver } from "./wire.js";
  */
 export type KernelDriverKind =
   | "Lww"
+  | "FirstWriterWins"
   // ── EXPLICIT TIME-AUTHORITY Lww drivers (the "whose clock?" axis) ──
   // Nomos has no servers, so "do we trust the clock?" is the WRONG question — the real
   // one is WHOSE clock orders THIS field, and a dev assigns it per field. `Lww` trusts
@@ -57,6 +58,9 @@ export interface Driver {
 }
 
 export const Lww: Driver = { kind: "Lww" };
+/** Nomos's ordinary scalar conflict policy: an informed later edit replaces the
+ * value; concurrent edits converge on the earliest writer. */
+export const FirstWriterWins: Driver = { kind: "FirstWriterWins" };
 export const AddWins: Driver = { kind: "AddWins" };
 export const Conflict: Driver = { kind: "Conflict" };
 export const MapOf = (inner: Driver): Driver => ({ kind: "MapOf", inner });
@@ -97,9 +101,10 @@ export const LastPosition: Driver = { kind: "LastPosition" };
 export const RemoveWins: Driver = { kind: "RemoveWins" };
 export const Counter: Driver = { kind: "Counter" };
 
-/** The Lww-class inner drivers `Surfaced` may wrap in v1 (wholesale-replace scalars —
- *  the pending set holds competing SCALAR values a human picks between). */
+/** The scalar inner drivers `Surfaced` may wrap in v1. The pending set preserves competing
+ *  business versions until a resolver produces one merged result. */
 const SURFACED_INNER_KINDS: ReadonlySet<DriverKind> = new Set<DriverKind>([
+  "FirstWriterWins",
   "Lww",
   "LwwCausal",
   "LwwBy",
@@ -114,7 +119,8 @@ const SURFACED_INNER_KINDS: ReadonlySet<DriverKind> = new Set<DriverKind>([
  * competing values as a bounded pending-observation set (cap 8, deterministically
  * pruned) that a read surfaces as `{"__surfaced":{"pending":[{value, author,
  * occurredAt}, ...]}}` — ALWAYS 2+ competing observations (a single-observation
- * set read-collapses to the plain scalar) — so an app can show a "pick one" UI.
+ * set read-collapses to the plain scalar) — so an app can explain the competing versions
+ * and produce a merged business result.
  * Linear writes and
  * fast-forwards behave EXACTLY as the inner driver (`Surfaced(LwwBy(p))` keeps
  * `p`'s write filter); pending sets form ONLY under real concurrency.
@@ -139,7 +145,7 @@ export const Surfaced = (inner: Driver): Driver => {
   if (!SURFACED_INNER_KINDS.has(inner.kind)) {
     throw new Error(
       `Surfaced(${inner.kind}) is not supported — Surfaced wraps an Lww-class SCALAR inner driver only ` +
-        `(Lww, LwwCausal, LwwBy) in v1. A pending set holds competing scalar values a human picks between; ` +
+        `(FirstWriterWins, Lww, LwwCausal, LwwBy) in v1. A pending set holds competing scalar versions until the business merges them; ` +
         `'${inner.kind}' ${
           inner.kind === "Surfaced"
             ? "is already Surfaced — nesting adds nothing"
@@ -160,6 +166,8 @@ const PALETTE_ONLY: ReadonlySet<DriverKind> = new Set<DriverKind>([]);
 /** Encode one Driver to its kernel wire shape, or throw if not yet in the kernel. */
 export function encodeDriver(d: Driver): WireDriver {
   switch (d.kind) {
+    case "FirstWriterWins":
+      return "FirstWriterWins";
     case "Lww":
       return "Lww";
     // ── EXPLICIT TIME-AUTHORITY Lww drivers (kernel `merge_field` arms) ──

package/src/engine_entry.ts

@@ -81,6 +81,8 @@ import type { InvariantBody, InvariantEvidence, InvariantVerdict } from "./relat
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import type { QueryRow } from "./report.js";
 import { expandBusinessBirthExports } from "./business_birth.js";
+import { withOwnedCustodyExports } from "./framework/owned_custody.js";
+import { withBusinessCorrectionExports } from "./framework/business_corrections.js";
 
 /** One bundled domain module: a bag of named exports the entry scans by SHAPE. */
 export type DomainModuleExports = Record<string, unknown>;
@@ -249,6 +251,8 @@ function mergeModules(mods: readonly DomainModuleExports[], domain: string): Dom
   let merged: DomainModuleExports = {};
   for (const m of mods) merged = { ...merged, ...m };
   merged = expandBusinessBirthExports(merged, domain);
+  merged = withOwnedCustodyExports(merged);
+  merged = withBusinessCorrectionExports(merged);
   // `capability()` bundles expand into discoverable entries here — the engine
   // plane's ONE merge point, so the registry sees the task aggregate + quartet
   // without per-piece re-exports (capability_exports.ts).

package/src/evolve_preview.ts

@@ -7,19 +7,21 @@
  * THE EVOLVE PREVIEW — `githolon check --against <prior>` (architecture/author_time_gate.md,
  * the `--against` row of check slice 3). The evolve gate is the kernel's #58 diff-by-stable-id
  * (executor/src/law58.rs::evolve_violation): a RENAME (same sid, new label) admits silently; a
- * true REMOVAL / RETYPE refuses TYPED unless the deploy JSON carries a `dispositions`
- * ({retired:[sid], retyped:{sid:why}, rebinds:{newSid:oldSid}}) acknowledging it in-history.
+ * true REMOVAL / merge-driver change refuses TYPED unless the deploy JSON carries a
+ * `dispositions` acknowledgement. A changed BUSINESS VALUE CONTRACT is stricter: it needs
+ * deterministic `.evolvesFrom(...)` coverage and cannot be waived by an acknowledgement.
  *
  * This module is the AUTHOR-TIME TWIN of that gate: given the PRIOR law and the CURRENT build,
  * it diffs them BY STABLE ID and pre-fires the gate's verdicts — with the EXACT generated
- * dispositions fragment (pre-filled with the real sids) inside the refusal's `fix`, so the dev
- * pastes it into their deploy JSON and the real deploy admits. It classifies:
+ * repair inside the refusal's `fix`, matching what the real gate will accept. It classifies:
  *
  *   RENAME   (note)   — same sid, new label; admits silently, old rows read the new label.
  *   ADDITIVE (note)   — a new aggregate/field/directive (incl. an additive optional VO field);
  *                       the evolve gate admits it silently (vo_first_class.md slice 6).
  *   REMOVAL  (refuse) — a sid disappeared; the gate REFUSES without dispositions.retired:[sid].
- *   RETYPE   (refuse) — same sid, changed read-kind or merge-driver; needs dispositions.retyped.
+ *   CONTRACT (refuse) — same sid, changed value language without a deterministic projection;
+ *                       needs `.evolvesFrom(...)`, never a disposition.
+ *   DRIVER   (refuse) — same sid, changed merge driver; needs dispositions.retyped.
  *   PAYLOAD  (warn)   — a directive's payload shape changed; clients compiled against the old
  *                       law get typed 422s until regenerated (directives are not sid-tracked).
  *
@@ -44,7 +46,15 @@ export interface EvolveAggregate {
   readonly label: string;
   /** keyed by FIELD SID. `driver` is the merge-law JSON (from the lockfile/usda schemas)
    *  when known — it lets the retype arm catch a driver-only change (same read kind). */
-  readonly fields: Record<string, { sid: string; label: string; kind: string; driver?: string }>;
+  readonly fields: Record<string, {
+    sid: string;
+    label: string;
+    kind: string;
+    driver?: string;
+    contract?: string;
+    schema?: string;
+    evolutions?: readonly { from: string; to: string }[];
+  }>;
 }
 
 /** One domain's evolve surface: aggregates (sid-keyed) + directive payload shapes (name-keyed). */
@@ -87,6 +97,11 @@ function aggregatesFromStableIds(
         label: fLabel,
         kind: f.kind ?? "",
         ...(driver !== undefined ? { driver: JSON.stringify(driver) } : {}),
+        ...(f.contract !== undefined ? { contract: f.contract } : {}),
+        ...(f.schema !== undefined ? { schema: f.schema } : {}),
+        ...(f.evolutions !== undefined ? {
+          evolutions: f.evolutions.map((rule) => ({ from: rule.from, to: rule.to })),
+        } : {}),
       };
     }
     out[a.sid] = { sid: a.sid, label: aggLabel, fields };
@@ -188,11 +203,23 @@ export function evolveLawFromDeployJson(deploy: DeployJson): EvolveLaw {
     const usdDom = fromUsd[key];
     if (usdDom !== undefined) {
       for (const agg of Object.values(dom.aggregates)) {
-        const schema = usdDom.schemas[agg.label];
-        if (schema === undefined) continue;
+        const stableAggregate = Object.values(usdDom.stableIds.aggregates)
+          .find((candidate) => candidate.sid === agg.sid);
+        const stableFields = new Map(
+          Object.values(stableAggregate?.fields ?? {})
+            .map((field) => [field.sid, field] as const),
+        );
+        const schema = usdDom.schemas[agg.label]
+          ?? Object.entries(usdDom.schemas).find(([type]) => type.endsWith(`.${agg.label}`))?.[1];
         for (const f of Object.values(agg.fields)) {
-          const driver = schema[f.label];
+          const driver = schema?.[f.label];
           if (driver !== undefined) (f as { driver?: string }).driver = JSON.stringify(driver);
+          const stable = stableFields.get(f.sid);
+          if (stable?.contract !== undefined) f.contract = stable.contract;
+          if (stable?.schema !== undefined) f.schema = stable.schema;
+          if (stable?.evolutions !== undefined) {
+            f.evolutions = stable.evolutions.map((rule) => ({ from: rule.from, to: rule.to }));
+          }
         }
       }
     }
@@ -274,6 +301,28 @@ function ensureDisp(map: Record<string, EvolveDispositionsJson>, domain: string)
   return (map[domain] ??= {});
 }
 
+/** Mirror executor::law58::evolution_reaches: one deterministic route per source,
+ *  accumulated across supported releases, must terminate at the current schema. */
+function evolutionReaches(
+  field: EvolveAggregate["fields"][string],
+  source: string | undefined,
+  target: string | undefined,
+): boolean {
+  if (source === undefined || target === undefined) return false;
+  if (source === target) return true;
+  const bySource = new Map((field.evolutions ?? []).map((rule) => [rule.from, rule.to]));
+  const seen = new Set<string>();
+  let cursor = source;
+  while (cursor !== target) {
+    if (seen.has(cursor)) return false;
+    seen.add(cursor);
+    const next = bySource.get(cursor);
+    if (next === undefined) return false;
+    cursor = next;
+  }
+  return true;
+}
+
 /** Diff one domain's aggregates/fields/directives BY STABLE ID and append findings + dispositions. */
 function diffDomain(
   domain: string,
@@ -332,10 +381,22 @@ function diffDomain(
       const kindChanged = oldF.kind !== "" && newF.kind !== "" && oldF.kind !== newF.kind;
       const driverChanged =
         oldF.driver !== undefined && newF.driver !== undefined && oldF.driver !== newF.driver;
-      if (kindChanged || driverChanged) {
+      const contractChanged =
+        oldF.contract !== undefined && newF.contract !== undefined && oldF.contract !== newF.contract;
+      const contractCovered = contractChanged && evolutionReaches(newF, oldF.schema, newF.schema);
+      if (contractChanged && !contractCovered) {
+        findings.push({
+          domain,
+          level: "refuse",
+          what: `field '${oldAgg.label}.${oldF.label}' (stable id ${fSid}) changes its business value contract without deterministic evolution coverage`,
+          fix: `declare .evolvesFrom(oldField) for a compatible widening or .evolvesFrom(oldField, value => nextValue) for an exhaustive finite business mapping; dispositions.retyped cannot waive this`,
+        });
+        continue;
+      }
+      if ((kindChanged && !contractCovered) || driverChanged) {
         const d = ensureDisp(disp, domain);
         (d.retyped ??= {})[fSid] = "<why goes here>";
-        const how = kindChanged
+        const how = kindChanged && !contractCovered
           ? `read kind ${oldF.kind} → ${newF.kind}`
           : `merge driver ${oldF.driver} → ${newF.driver}`;
         findings.push({