@githolon/dsl 0.103.12 → 0.103.14

package/src/fields.ts

@@ -15,6 +15,7 @@
  * the value type (via Zod) is preserved.
  */
 import { z } from "zod";
+import { isEnumType, type EnumType } from "./enum_type.js";
 import { Conflict, Counter, FirstWriterWins, LastPosition, type Driver } from "./drivers.js";
 import type { AggregateHandle } from "./aggregate.js";
 import type { ContractHandle } from "./contract.js";
@@ -292,7 +293,13 @@ export type ValueObjectFieldDescriptor =
    * was declared through `unit(...)` — the generated Dart extension-type wrapper's name. */
   | { readonly type: "number"; readonly int?: true; readonly unit?: string; readonly optional?: true }
   | { readonly type: "boolean"; readonly optional?: true }
-  | { readonly type: "enum"; readonly values: readonly string[]; readonly optional?: true }
+  | {
+      readonly type: "enum";
+      readonly values: readonly string[];
+      /** Stable authored scalar name from enumType(...), when this is shared vocabulary. */
+      readonly name?: string;
+      readonly optional?: true;
+    }
   /** A `z.literal(<string>)` — a CONSTANT discriminator-style member (generated as a getter). */
   | { readonly type: "literal"; readonly value: string; readonly optional?: true }
   | { readonly type: "array"; readonly items: ValueObjectFieldDescriptor; readonly optional?: true }
@@ -540,6 +547,11 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
   /** Business-declared source contracts this field can understand during a gradual rollout.
    * Compiler-owned metadata; generated clients and tenant runtime code never see contract ids. */
   readonly evolutions?: readonly FieldEvolutionDeclaration[];
+  /** TRUE for `t.timestamp()`: the physical wire remains an int, while the business value is an
+   * epoch-millisecond timestamp and may own compiler-generated temporal enum reads. */
+  readonly isTimestamp?: true;
+  /** Temporal enum projections declared directly on this timestamp. Present only on `t.timestamp()`. */
+  readonly temporalEnums?: readonly TemporalEnumFieldDeclaration[];
   /** Returns a copy with the chosen driver while preserving fluent law markers already applied. */
   merge(driver: Driver): this;
   /** Tag this field's facet, threaded through merge/optional (the canonical form is the
@@ -629,6 +641,8 @@ function makeField<T, K extends FieldKind = FieldKind>(
     clearRequires?: string;
     clearRequiresObject?: string;
     evolutions?: readonly FieldEvolutionDeclaration[];
+    timestamp?: true;
+    temporalEnums?: readonly TemporalEnumFieldDeclaration[];
   } = {},
 ): Field<T, K> {
   const isOptional = extra.isOptional ?? false;
@@ -661,6 +675,10 @@ function makeField<T, K extends FieldKind = FieldKind>(
     ...(extra.evolutions !== undefined && extra.evolutions.length > 0
       ? { evolutions: extra.evolutions }
       : {}),
+    ...(extra.timestamp ? { isTimestamp: true as const } : {}),
+    ...(extra.temporalEnums !== undefined && extra.temporalEnums.length > 0
+      ? { temporalEnums: extra.temporalEnums }
+      : {}),
     merge(d: Driver): typeof f {
       return makeField<T, K>(kind, zod, d, extra) as typeof f;
     },
@@ -775,6 +793,62 @@ function makeField<T, K extends FieldKind = FieldKind>(
       return makeField<T, K>(kind, zod, driver, { ...extra, facet }) as Field<T, K> & { readonly facet: Fa };
     },
   };
+  if (extra.timestamp) {
+    (f as Field<T, K> & {
+      temporalEnum(id: string, states: TemporalEnumStates<string>): Field<T, K>;
+    }).temporalEnum = (id, states) => {
+      if (!/^[A-Za-z][A-Za-z0-9_]{0,127}$/.test(id)) {
+        throw new Error(
+          `t.timestamp().temporalEnum(): read id must be an identifier (letter, then letters/digits/_); got ${JSON.stringify(id)}`,
+        );
+      }
+      if (typeof states.missing !== "string" || states.missing.length === 0 ||
+          typeof states.initial !== "string" || states.initial.length === 0) {
+        throw new Error(
+          `t.timestamp().temporalEnum('${id}'): missing and initial must be non-empty enum values`,
+        );
+      }
+      const transitions: TemporalEnumTransition[] = [];
+      let previous = 0;
+      let previousValue = states.initial;
+      const values = new Set<string>([states.missing, states.initial]);
+      for (const [afterMillis, value] of states.after) {
+        if (!Number.isSafeInteger(afterMillis) || afterMillis <= previous) {
+          throw new Error(
+            `t.timestamp().temporalEnum('${id}'): thresholds must be strictly increasing positive safe integer milliseconds; ` +
+              `got ${JSON.stringify(afterMillis)} after ${previous}`,
+          );
+        }
+        if (typeof value !== "string" || value.length === 0) {
+          throw new Error(`t.timestamp().temporalEnum('${id}'): every transition needs a non-empty enum value`);
+        }
+        if (value === previousValue) {
+          throw new Error(
+            `t.timestamp().temporalEnum('${id}'): transition at ${afterMillis}ms repeats ${JSON.stringify(value)}; remove the no-op threshold`,
+          );
+        }
+        if (values.has(value)) {
+          throw new Error(
+            `t.timestamp().temporalEnum('${id}'): enum value ${JSON.stringify(value)} is reused; age states must progress monotonically`,
+          );
+        }
+        values.add(value);
+        transitions.push({ afterMillis, value });
+        previous = afterMillis;
+        previousValue = value;
+      }
+      if ((extra.temporalEnums ?? []).some((candidate) => candidate.id === id)) {
+        throw new Error(`t.timestamp().temporalEnum('${id}'): this timestamp already declares that read id`);
+      }
+      return makeField<T, K>(kind, zod, driver, {
+        ...extra,
+        temporalEnums: [
+          ...(extra.temporalEnums ?? []),
+          { id, missing: states.missing, initial: states.initial, transitions },
+        ],
+      });
+    };
+  }
   // LAZY REF TARGET: when the target was given as a thunk (`t.ref(() => Agg)` / `t.hasMany(() => Agg)` — to
   // break a bidirectional declaration cycle), expose `refAggregateId` as a MEMOIZED getter that resolves the
   // thunk on first read (build time, after all module consts init). Consumers read `refAggregateId` as usual.
@@ -902,6 +976,46 @@ export interface IntRules {
   readonly maximum?: number;
 }
 
+/** One monotone age threshold in a temporal enum projection. `afterMillis` is measured from the
+ * stored timestamp; crossing it changes the read value without writing business state. */
+export interface TemporalEnumTransition {
+  readonly afterMillis: number;
+  readonly value: string;
+}
+
+/** Compiler-owned declaration attached to a timestamp field by `.temporalEnum(...)`. The aggregate
+ * composition seam turns this into a first-class read declaration automatically, so the author never
+ * has to export/register a second object. */
+export interface TemporalEnumFieldDeclaration {
+  readonly id: string;
+  readonly missing: string;
+  readonly initial: string;
+  readonly transitions: readonly TemporalEnumTransition[];
+}
+
+export interface TemporalEnumStates<E extends string> {
+  /** Value when the source timestamp has never been observed. Exhaustive by construction. */
+  readonly missing: E;
+  /** Value from the source timestamp until the first threshold. */
+  readonly initial: E;
+  /** Strictly increasing `[ageInMilliseconds, value]` transitions. */
+  readonly after: readonly (readonly [number, E])[];
+}
+
+/** An epoch-millisecond business timestamp. It keeps the kernel's efficient integer wire but exposes
+ * the safe temporal projection vocabulary directly through autocomplete. */
+export interface TimestampField<T = number> extends Field<T, "int"> {
+  readonly isTimestamp: true;
+  readonly temporalEnums?: readonly TemporalEnumFieldDeclaration[];
+  merge(driver: Driver): this;
+  optional(): TimestampField<T | undefined>;
+  fromBirth(): this & { readonly isFromBirth: true };
+  temporalEnum<const E extends string>(
+    id: string,
+    states: TemporalEnumStates<E>,
+  ): TimestampField<T>;
+}
+
 function naturalRule(value: number | undefined, name: string): void {
   if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
     throw new Error(`${name} must be a non-negative safe integer; got ${JSON.stringify(value)}`);
@@ -954,6 +1068,17 @@ export const t = {
     if (maximum !== undefined) schema = schema.max(maximum);
     return makeField("int", schema, FirstWriterWins);
   },
+  /** A UTC timestamp stored canonically as non-negative epoch milliseconds. Unlike a bare `t.int()`,
+   * this progressively exposes `.temporalEnum(...)`, making time-dependent categories a typed,
+   * kernel-owned read instead of an arbitrary callback or UI calculation. */
+  timestamp(): TimestampField<number> {
+    return makeField<number, "int">(
+      "int",
+      z.number().int().nonnegative(),
+      FirstWriterWins,
+      { timestamp: true },
+    ) as TimestampField<number>;
+  },
   /** A boolean flag (Lww). Stored as the kernel scalar `"true"`/`"false"` and decoded back to a real
    *  JSON boolean on read — so a flag is `t.bool()`, not a 2-value `t.enum`. Counts/filters key on the
    *  same string form. (Not encryptable — only Lww-class scalars are, and bool already is.) */
@@ -988,10 +1113,15 @@ export const t = {
     return z.array(el);
   },
   /** Enum via `as const` literal union — value typos squeal at compile time. */
-  enum<const E extends readonly [string, ...string[]]>(values: E): Field<E[number], "enum"> {
+  enum<const E extends readonly [string, ...string[]]>(
+    values: E | EnumType<E>,
+  ): Field<E[number], "enum"> {
+    const schema = isEnumType(values)
+      ? values.zod
+      : z.enum(values) as unknown as z.ZodType<E[number]>;
     return makeField<E[number], "enum">(
       "enum",
-      z.enum(values) as unknown as z.ZodType<E[number]>,
+      schema,
       FirstWriterWins,
     );
   },
@@ -1161,7 +1291,7 @@ export const t = {
       },
     });
   },
-  /** A version pin whose freshness is checked against one law-declared current pointer on a stable series.
+  /** A version pin whose version status is checked against one law-declared current pointer on a stable series.
    * The declaration fails immediately if `series.current` is not an atomic ref to `target`. */
   versionedForeignRef(opts: {
     target: AggregateHandle<string, Record<string, Field>> | ContractHandle;
@@ -1178,7 +1308,7 @@ export const t = {
     if (current.nomosRef?.targetAggregateId !== opts.target.id) {
       throw new Error(
         `t.versionedForeignRef: '${opts.series.id}.${opts.current}' must be ` +
-          `t.nomosRef(${opts.target.id}); it is the O(1) current pointer used for freshness`,
+          `t.nomosRef(${opts.target.id}); it is the O(1) current pointer used for version status`,
       );
     }
     const targetIsContract = (opts.target as { __isContract?: unknown }).__isContract === true;

package/src/flow_gate.ts

@@ -235,7 +235,8 @@ export function assertFlowGate(m: FlowLaw, mod?: FlowModule): void {
   }
 
   // ── RULE 5 — NO PRIVATE BYTES IN AN OUTBOUND OFFER (Send's external send) ────
-  // The outbox (refs/heads/outbox/<offer>) POSTs a capability's obligation to its endpoint —
+  // The kernel's due-offer read exposes typed bytes from the authenticated main frontier's outbox/
+  // tree for POSTing to a capability endpoint —
   // a DIFFERENT observer set (the external adapter). If the capability's task aggregate is
   // private (requires a read cap) or encrypted, those bytes cross the confidentiality boundary.
   // Refuse unless declassified. CURRENTLY VACUOUS BY CONSTRUCTION (capability task aggregates are

package/src/framework/workspaces.ts

@@ -471,6 +471,27 @@ export const CapabilityBinding = aggregate("CapabilityBinding", {
   status: t.enum(GRANT_STATUSES).merge(Lww),
 }).public();
 
+/**
+ * CapabilityAddress — the custodied destination for an addressed capability.
+ *
+ * An address is public routing configuration, not a credential. Keeping it in
+ * workspace state lets one compiled sovereign package serve production, dev and
+ * self-hosted workspaces without hard-coding one tenant's infrastructure into law.
+ * The kernel reads this fact only to address a sealed outbound offer; the host
+ * still receives opaque bytes and cannot choose or rewrite the destination.
+ */
+export const CapabilityAddress = aggregate("CapabilityAddress", {
+  capability: t.string().merge(Lww),
+  endpoint: t.string().merge(Lww),
+  configuredBy: t.string().merge(Lww),
+  configuredAt: t.int().merge(Lww),
+  status: t.enum(GRANT_STATUSES).merge(Lww),
+}).public();
+
+export function capabilityAddressId(capability: string): string {
+  return `capability-address:${capability}`;
+}
+
 // --- workspace directives ---------------------------------------------------------
 
 // ── THE ONE BIRTH RECORD (the `kind`-collapse — architecture/provisioning_as_obligations.md) ───────────
@@ -1524,6 +1545,53 @@ export const revokeCapability = directive("revokeCapability")
   })
   .requires("admin");
 
+const httpsEndpoint = z.string().url().refine(
+  (value) => value.startsWith("https://"),
+  "capability endpoint must use https",
+);
+
+/** Configure where this workspace offers one named capability. */
+export const configureCapabilityAddress = directive("configureCapabilityAddress")
+  .ensures(CapabilityAddress)
+  .payload(
+    z.object({
+      capability: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,63}$/),
+      endpoint: httpsEndpoint,
+      configuredBy: z.string().min(1),
+      configuredAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    ensure(CapabilityAddress, capabilityAddressId(p.capability))
+      .set("capability", p.capability)
+      .set("endpoint", p.endpoint)
+      .set("configuredBy", p.configuredBy)
+      .set("configuredAt", p.configuredAt)
+      .set("status", "active");
+    return [];
+  })
+  .requires("admin");
+
+/** Stop new outbound delivery without deleting the auditable address fact. */
+export const revokeCapabilityAddress = directive("revokeCapabilityAddress")
+  .mutates(CapabilityAddress)
+  .payload(
+    z.object({
+      addressId: idOf(CapabilityAddress),
+      revokedBy: z.string().min(1),
+      revokedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const address = instance(CapabilityAddress, p.addressId);
+    return [
+      set(address, "configuredBy", p.revokedBy),
+      set(address, "configuredAt", p.revokedAt),
+      set(address, "status", "revoked" as const),
+    ];
+  })
+  .requires("admin");
+
 /**
  * setCloudPolicy — set (or amend) THE QUOTA LAW. An Ensure on the law-state
  * singleton: the first author births it, later authors amend it in place —
@@ -1749,6 +1817,11 @@ export const capabilityBindingByKeyHash = query("capabilityBindingByKeyHash")
   .key("keyHash")
   .returns(CapabilityBinding);
 
+/** The current workspace-owned delivery address for a named capability. */
+export const capabilityAddressByName = query("capabilityAddressByName")
+  .key("capability")
+  .returns(CapabilityAddress);
+
 // ── THE ZANZIBAR SPINE comes to the CONTROL PLANE (governance → tuples) ──────────────────────────
 // The authority grants above ARE relation tuples in disguise (the same smell as the deleted
 // UserPermission): admin=`workspace:self#admin@key:<keyHash>`, creator=`…#creator@key:…`,

package/src/idof_lint.ts

@@ -140,7 +140,11 @@ export function assertIdOfLintForDirective(dir: Directive<unknown>, where: strin
       // this guard a model can compile `entryId: z.string()`, after which every generated caller can mix
       // unrelated record ids and is encouraged to reconstruct identity as application state.
       const effectiveMarker = op.marker ?? (op.aggregateType === dir.aggregateId ? dir.marker : "mutates");
-      if (op.aggregateType !== undefined && (effectiveMarker === "mutates" || effectiveMarker === "archives")) {
+      if (
+        op.aggregateType !== undefined &&
+        (effectiveMarker === "mutates" ||
+          effectiveMarker === "archives")
+      ) {
         const payloadField = byValue.get(op.aggregateId);
         if (payloadField !== undefined) {
           const fieldSchema = shape[payloadField];

package/src/index.ts

@@ -10,11 +10,17 @@
 // authors never juggle a separate zod dependency (or risk a second zod instance).
 export { z } from "zod";
 export {
+  defineDomain,
+  defineFeature,
+  featureDependenciesOf,
   definePackage,
   validateNomosPackageConfig,
+  type NomosPackageFeatureConfig,
   type NomosPackageConfig,
   type NomosPackageDefinition,
   type NomosPackageDomainConfig,
+  type NormalizedNomosPackageConfig,
+  type NormalizedNomosPackageDomainConfig,
 } from "./package_config.js";
 export {
   applicationHomeGenesis,
@@ -50,6 +56,10 @@ export {
   type FieldEvolutionDeclaration,
   type StringRules,
   type IntRules,
+  type TimestampField,
+  type TemporalEnumStates,
+  type TemporalEnumFieldDeclaration,
+  type TemporalEnumTransition,
   NULL_ADMITTING,
   admitsNull,
   jsonNoNullSchema,
@@ -113,6 +123,12 @@ export {
   type GeoMultiPointValue,
   type ValueObjectUsage,
 } from "./value_object.js";
+export {
+  enumType,
+  enumTypeNameOf,
+  isEnumType,
+  type EnumType,
+} from "./enum_type.js";
 export {
   type PrincipalEvidence,
   type AttributionPrincipal,
@@ -387,6 +403,8 @@ export {
 export {
   derived,
   type DerivedDecl,
+  type TemporalEnumDecl,
+  type AnyDerivedDecl,
   type DerivedOf,
   type TypelessDerived,
   type DeriveFn,
@@ -407,6 +425,8 @@ export {
   EntityGraphBuilder,
   days,
   hours,
+  minutes,
+  seconds,
   type QueryAst,
   type QueryRow,
   type Report,

package/src/kernel_capabilities.ts

@@ -48,7 +48,9 @@ export type KernelFeature =
   /** Law-declared immutable pending-conflict snapshots (compare-and-set merge refs). */
   | "conflictSnapshots"
   /** `.owned()` automatic owner stamp, atomic per-record seat, and framework-custodied epoch-0 key. */
-  | "ownedAudience";
+  | "ownedAudience"
+  /** Captured-clock temporal enum projections declared by `t.timestamp().temporalEnum(...)`. */
+  | "temporalEnum";
 
 /** The USD-IR era key each derived-from-law capability rides on, for the requirement
  *  derivation below (a package that emits the era key needs the capability). */
@@ -64,6 +66,7 @@ export const ERA_KEY_TO_FEATURE: Readonly<Record<string, KernelFeature>> = {
 /** A minimal shape of a compiled domain module — enough to derive its kernel needs. */
 export interface FeatureProbeModule {
   readonly queries?: readonly QueryDecl[];
+  readonly deriveds?: readonly unknown[];
   readonly surfacedResolvers?: readonly unknown[];
   readonly aggregates?: readonly { audience?: { kind?: string } }[];
   /** The domain's USD-IR layer (the era keys ride here). Optional — shape-derived
@@ -83,6 +86,11 @@ export function requiredKernelFeatures(modules: readonly FeatureProbeModule[]):
     for (const q of m.queries ?? []) {
       if (Array.isArray(q.key) && q.key.length > 1) needs.add("compoundKeys");
     }
+    if ((m.deriveds ?? []).some((derived) =>
+      typeof derived === "object" && derived !== null && "kind" in derived &&
+      derived.kind === "temporalEnum")) {
+      needs.add("temporalEnum");
+    }
     if ((m.surfacedResolvers?.length ?? 0) > 0) needs.add("conflictSnapshots");
     if ((m.aggregates ?? []).some((aggregate) => aggregate.audience?.kind === "owned")) {
       needs.add("ownedAudience");
@@ -251,6 +259,9 @@ export function assessKernelCoherence(params: {
       (missing.includes("compoundKeys")
         ? `A compound-key query (\`.key(a, b, …)\`) will be refused deep in a law fold with ` +
           `"query declares N index keys; the read router supports exactly one". `
+        : missing.includes("temporalEnum")
+          ? `A temporal enum read will be refused while mounting law with ` +
+            `"unknown nomos:readKind temporalEnum". `
         : ``) +
       `Upgrade the cloud's kernel (or point at a cloud whose kernel is coherent with this release).`,
   };

package/src/law_check.ts

@@ -63,6 +63,12 @@ export interface Finding {
   readonly what: string;
   /** How to fix it (or, for a note, how the repair keeps the law valid). */
   readonly fix: string;
+  /** Exact authored source anchor when the finding belongs to a file rather than a law declaration. */
+  readonly source?: {
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+  };
 }
 
 /** Payload field names the FRAMEWORK consumes off the intent (never the plan) — excluded from the
@@ -150,6 +156,33 @@ function probeDirective(dir: Directive<unknown>, where: string): ProbeResult | u
   return { synth, probePayload, returned, threw, error, ops, reads, readFields };
 }
 
+/** Empirical agent-DX guardrail from the CO2 migration: agents model `last…At` observations as a
+ * plain integer, erasing clock semantics and then rebuilding freshness in Dart. Keep this narrow:
+ * it only warns for the observed `lastXAt`/`lastXTimestamp` shape, and recommends the discoverable
+ * timestamp primitive without presuming that every timestamp needs a temporal enum. */
+function timestampFieldFindings(mod: DomainModule): Finding[] {
+  const domain = mod.domain ?? mod.name;
+  const findings: Finding[] = [];
+  for (const aggregate of mod.aggregates) {
+    for (const [fieldName, field] of Object.entries(aggregate.fields as Record<string, Field>)) {
+      if (
+        field.kind === "int" &&
+        field.isTimestamp !== true &&
+        /^last[A-Z].*(?:At|Timestamp)$/.test(fieldName)
+      ) {
+        findings.push({
+          domain,
+          directiveId: aggregate.id,
+          level: "warn",
+          what: `aggregate '${aggregate.id}' field '${fieldName}' looks like a captured timestamp but is declared as a plain t.int(); agents then tend to rebuild age/freshness policy in the client`,
+          fix: `declare '${fieldName}: t.timestamp()…'; autocomplete will then expose .temporalEnum(...) when the business value changes with age`,
+        });
+      }
+    }
+  }
+  return findings;
+}
+
 /** `zodObjectShape` with a swallow — a non-object payload yields `{}` (the return twin handles it). */
 function safeShape(schema: z.ZodTypeAny): Record<string, z.ZodTypeAny> {
   try {
@@ -609,52 +642,97 @@ function isScalarLeafDescriptor(d: ValueObjectFieldDescriptor): boolean {
   return d.type === "string" || d.type === "number" || d.type === "boolean" || d.type === "enum" || d.type === "literal";
 }
 
-/** Enumerate every dotted leaf path reachable through `object`/`geometry` refs under one VO
- *  descriptor, `prefix`-rooted. Arrays/maps are not name-addressable, so they are not descended. */
+/** Enumerate every dotted leaf path reachable through `object`/`geometry` refs or variant arms
+ *  under one VO descriptor, `prefix`-rooted. Anonymous variant-arm fields are flattened beside
+ *  `type`; named-VO arms descend through their wire-level `value` member. Arrays/maps are not
+ *  name-addressable, so they are not descended. */
 function voLeafPaths(
   desc: ValueObjectDescriptor,
   byName: ReadonlyMap<string, ValueObjectDescriptor>,
   prefix: string,
   seen: ReadonlySet<string>,
 ): string[] {
-  if (desc.fields === undefined) return []; // a geo/union VO exposes no named structural subfields here
   if (seen.has(desc.name)) return []; // cycle guard (a VO transitively nesting itself)
   const nextSeen = new Set(seen).add(desc.name);
-  const out: string[] = [];
-  for (const [name, f] of Object.entries(desc.fields)) {
-    const path = `${prefix}.${name}`;
-    if (isScalarLeafDescriptor(f)) {
-      out.push(path);
-    } else if ((f.type === "object" || f.type === "geometry") && byName.has(f.ref)) {
-      out.push(...voLeafPaths(byName.get(f.ref)!, byName, path, nextSeen));
+  const out = new Set<string>();
+  const visitFields = (
+    fields: Readonly<Record<string, ValueObjectFieldDescriptor>>,
+    fieldPrefix: string,
+  ): void => {
+    for (const [name, f] of Object.entries(fields)) {
+      const path = `${fieldPrefix}.${name}`;
+      if (isScalarLeafDescriptor(f)) {
+        out.add(path);
+      } else if ((f.type === "object" || f.type === "geometry") && byName.has(f.ref)) {
+        for (const nested of voLeafPaths(byName.get(f.ref)!, byName, path, nextSeen)) out.add(nested);
+      }
+    }
+  };
+  if (desc.fields !== undefined) visitFields(desc.fields, prefix);
+  if (desc.union !== undefined) {
+    out.add(`${prefix}.type`);
+    for (const arm of Object.values(desc.union)) {
+      if ("fields" in arm) {
+        visitFields(arm.fields, prefix);
+      } else if (byName.has(arm.ref)) {
+        for (const nested of voLeafPaths(byName.get(arm.ref)!, byName, `${prefix}.value`, nextSeen)) out.add(nested);
+      }
     }
   }
-  return out;
+  return [...out];
 }
 
-/** Resolve a dotted path (segments AFTER the lead VO field) through a VO descriptor tree. Returns
- *  `"leaf"` if it lands on a scalar leaf, `"nonleaf"` if it resolves but to a non-scalar node (an
- *  object/array/map — not indexable), or `undefined` if a segment is absent. */
+type VoPathVerdict = "leaf" | "nonleaf" | undefined;
+
+function resolveFieldPath(
+  field: ValueObjectFieldDescriptor,
+  byName: ReadonlyMap<string, ValueObjectDescriptor>,
+  remaining: readonly string[],
+  seen: ReadonlySet<string>,
+): VoPathVerdict {
+  if (remaining.length === 0) return isScalarLeafDescriptor(field) ? "leaf" : "nonleaf";
+  if ((field.type === "object" || field.type === "geometry") && byName.has(field.ref)) {
+    return resolveVoPath(byName.get(field.ref)!, byName, remaining, seen);
+  }
+  return undefined;
+}
+
+/** Resolve one path through a structural VO or a discriminated variant. A field which exists only
+ *  on SOME anonymous variant arms is still a lawful sparse index: rows in the other arms simply
+ *  contribute no key, matching the projection's JSON-path extraction semantics. */
 function resolveVoPath(
   rootDesc: ValueObjectDescriptor,
   byName: ReadonlyMap<string, ValueObjectDescriptor>,
   segments: readonly string[],
-): "leaf" | "nonleaf" | undefined {
-  let desc: ValueObjectDescriptor | undefined = rootDesc;
-  for (let i = 0; i < segments.length; i++) {
-    const seg = segments[i]!;
-    const f = desc?.fields?.[seg];
-    if (f === undefined) return undefined;
-    const isLast = i === segments.length - 1;
-    if (isLast) return isScalarLeafDescriptor(f) ? "leaf" : "nonleaf";
-    // A non-terminal segment must descend into a nested VO by ref.
-    if ((f.type === "object" || f.type === "geometry") && byName.has(f.ref)) {
-      desc = byName.get(f.ref);
-    } else {
-      return undefined; // a scalar/array/map mid-path can't be descended by name
+  seen: ReadonlySet<string> = new Set(),
+): VoPathVerdict {
+  if (segments.length === 0 || seen.has(rootDesc.name)) return undefined;
+  const [seg, ...rest] = segments;
+  const nextSeen = new Set(seen).add(rootDesc.name);
+
+  const direct = rootDesc.fields?.[seg!];
+  if (direct !== undefined) return resolveFieldPath(direct, byName, rest, nextSeen);
+
+  if (rootDesc.union === undefined) return undefined;
+  if (seg === "type") return rest.length === 0 ? "leaf" : undefined;
+
+  const verdicts: Exclude<VoPathVerdict, undefined>[] = [];
+  for (const arm of Object.values(rootDesc.union)) {
+    let verdict: VoPathVerdict;
+    if ("fields" in arm) {
+      const field = arm.fields[seg!];
+      verdict = field === undefined
+        ? undefined
+        : resolveFieldPath(field, byName, rest, nextSeen);
+    } else if (seg === "value" && byName.has(arm.ref)) {
+      verdict = rest.length === 0
+        ? "nonleaf"
+        : resolveVoPath(byName.get(arm.ref)!, byName, rest, nextSeen);
     }
+    if (verdict !== undefined) verdicts.push(verdict);
   }
-  return undefined;
+  if (verdicts.length === 0) return undefined;
+  return verdicts.every((verdict) => verdict === "leaf") ? "leaf" : "nonleaf";
 }
 
 function dottedQueryKeyFindings(mod: DomainModule, aggById: ReadonlyMap<string, AggregateHandle>): Finding[] {
@@ -1239,6 +1317,7 @@ export function checkDomainModules(
 
     // Slice-2 twin: the module top level read the captured ports (pristine-pool ineligibility).
     findings.push(...topLevelPortReadFindings(mod, portReadingDomains));
+    findings.push(...timestampFieldFindings(mod));
 
     for (const dir of mod.directives as Directive<unknown>[]) {
       const where = `${domain}/${dir.id}`;