@githolon/dsl 0.108.6 → 0.110.0

package/src/framework/workspace_access.ts

@@ -0,0 +1,149 @@
+/** Source-qualified access correspondence. This is law, not a client delivery loop.
+ * The source commits its publication and outbound offer together. The recipient
+ * keeps an ordering receipt and ordinary Zanzibar edges; no sender gets Home authority.
+ */
+import { z } from "zod";
+import { aggregate, instance } from "../aggregate.js";
+import { directive, nomosImplementationDetail, type Directive } from "../directive.js";
+import type { BusinessIntent } from "../intent.js";
+import type { Ports } from "../ctx.js";
+import { Lww } from "../drivers.js";
+import { t } from "../fields.js";
+import { set, withMarker } from "../ops.js";
+import { query } from "../query.js";
+import { readFrameworkDeclaredRows } from "../read.js";
+import { endorsementOf } from "../principal_evidence.js";
+import { RelationTuple, writeTuple, removeTuple } from "./relations.js";
+
+declare const nomos: { sha256(input: string): string };
+
+export const workspaceAccessPayload = z.object({
+  recipient: z.string().regex(/^user:[A-Za-z0-9][A-Za-z0-9_.-]*$/),
+  object: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.:/-]*$/),
+  relation: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/),
+  active: z.boolean(),
+  revision: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+});
+export type WorkspaceAccessPublication = z.infer<typeof workspaceAccessPayload>;
+export type WorkspaceAccessChange = Omit<WorkspaceAccessPublication, "revision">;
+
+export const WorkspaceAccessPublication = nomosImplementationDetail(aggregate("WorkspaceAccessPublication", {
+  coordinate: t.string().merge(Lww),
+  revision: t.int().merge(Lww),
+// Ordering metadata has the same visibility as the public RelationTuple facts;
+// it contains neither device credentials nor encrypted business contents.
+}, { global: true }).public());
+export const workspaceAccessPublication = query("workspaceAccessPublication")
+  .key("coordinate").returns(WorkspaceAccessPublication);
+
+/** Ordering only. Discovery is the RelationTuple below, not another bookmark index. */
+export const WorkspaceAccessReceipt = nomosImplementationDetail(aggregate("WorkspaceAccessReceipt", {
+  coordinate: t.string().merge(Lww),
+  revision: t.int().merge(Lww),
+  subject: t.string().merge(Lww),
+}, { global: true }).public());
+export const workspaceAccessReceipt = query("workspaceAccessReceipt")
+  .key("coordinate").returns(WorkspaceAccessReceipt);
+
+/** Home's ordinary Zanzibar discovery read. It has its own nominal identity;
+ * it must not collide with generic relation queries installed by other domains. */
+export const receivedWorkspaceAccess = nomosImplementationDetail(query("receivedWorkspaceAccess")
+  .key("object").returns(RelationTuple));
+
+export function accessCoordinate(recipient: string, object: string): string {
+  return nomos.sha256(JSON.stringify([recipient, object]));
+}
+export const RECEIVED_ACCESS_RELATION = "receivedAccess";
+export function receivedAccessObject(recipient: string): string {
+  return `received-access:${recipient}`;
+}
+
+/** A fresh publication gets a fresh userset address. Revoked leaves are never
+ * resurrected (the kernel's remove-wins rule), including a later lawful re-share. */
+export function receivedAccessSubject(source: string, p: WorkspaceAccessPublication): string {
+  return `shared:${source}/${p.object}/${p.revision}#${p.relation}`;
+}
+
+export const recordReceivedWorkspaceAccess = nomosImplementationDetail(directive("recordReceivedWorkspaceAccess")
+  .ensures(RelationTuple)
+  .payload(workspaceAccessPayload)
+  .plan((p, ctx) => {
+    const actor = endorsementOf(ctx.principal().asAttribution())?.principal ?? "";
+    if (!actor.startsWith("workspace:")) throw new Error("share requires a verified workspace speaker");
+    const source = actor.slice("workspace:".length);
+    const coordinate = `${source}/${accessCoordinate(p.recipient, p.object)}`;
+    const rows = readFrameworkDeclaredRows(workspaceAccessReceipt, WorkspaceAccessReceipt, { coordinate });
+    if (rows.length > 1) throw new Error("duplicate workspace access receipt");
+    const previous = rows[0];
+    // Old instruments are acknowledged without re-applying their consequences.
+    if ((previous?.revision ?? 0) >= p.revision) return [];
+    const object = receivedAccessObject(p.recipient);
+    const subject = receivedAccessSubject(source, p);
+    const at = new Date(ctx.clock().physical).toISOString();
+    const receipt = instance(WorkspaceAccessReceipt, `access-receipt:${coordinate}`);
+    return [
+      ...(previous?.subject ? removeTuple({ object, relation: RECEIVED_ACCESS_RELATION,
+        subject: previous.subject, grantedBy: actor, grantedAt: at, revokedBy: actor, revokedAt: at }) : []),
+      ...(p.active ? writeTuple({ object, relation: RECEIVED_ACCESS_RELATION, subject,
+        grantedBy: actor, grantedAt: at }) : []),
+      withMarker(set(receipt, "coordinate", coordinate), "ensures"),
+      set(receipt, "revision", p.revision),
+      set(receipt, "subject", p.active ? subject : ""),
+    ];
+  })
+  .affectsOptional()
+  .alsoEnsuresOptional(WorkspaceAccessReceipt)
+  .reads(workspaceAccessReceipt)
+  .acceptsVerifiedWorkspaceClaim());
+
+/** Attach one typed, durable correspondence to a normal public offer. No session,
+ * network, key, clock cache or retry state is introduced by this wrapper. */
+export function publishesWorkspaceAccess<P>(
+  action: BusinessIntent<P>,
+  change: (facts: P, ctx: Ports) => WorkspaceAccessChange | null,
+  recipientWorkspace: (recipient: string) => string,
+  receiver?: Directive<WorkspaceAccessPublication>,
+): BusinessIntent<P>;
+export function publishesWorkspaceAccess<P>(
+  action: Directive<P>,
+  change: (facts: P, ctx: Ports) => WorkspaceAccessChange | null,
+  recipientWorkspace: (recipient: string) => string,
+  receiver?: Directive<WorkspaceAccessPublication>,
+): Directive<P>;
+export function publishesWorkspaceAccess<P>(
+  action: Directive<P>,
+  change: (facts: P, ctx: Ports) => WorkspaceAccessChange | null,
+  recipientWorkspace: (recipient: string) => string,
+  receiver: Directive<WorkspaceAccessPublication> = recordReceivedWorkspaceAccess,
+): Directive<P> {
+  const publication = (facts: P, ctx: Ports): WorkspaceAccessPublication => {
+    const access = change(facts, ctx);
+    if (access === null) throw new Error("this offer has no identified access recipient");
+    const coordinate = accessCoordinate(access.recipient, access.object);
+    const rows = readFrameworkDeclaredRows(workspaceAccessPublication, WorkspaceAccessPublication, { coordinate });
+    if (rows.length > 1) throw new Error("duplicate workspace access publication");
+    return workspaceAccessPayload.parse({ ...access, revision: (rows[0]?.revision ?? 0) + 1 });
+  };
+  return {
+    ...action,
+    secondaryOutputs: [...(action.secondaryOutputs ?? []), {
+      aggregateId: WorkspaceAccessPublication.id, aggregate: WorkspaceAccessPublication, marker: "ensures", optional: true,
+    }],
+    declaredQueryReads: [...(action.declaredQueryReads ?? []), workspaceAccessPublication],
+    plan(facts, ctx) {
+      const ops = action.plan(facts, ctx);
+      if (change(facts, ctx) === null) return ops;
+      const p = publication(facts, ctx);
+      const coordinate = accessCoordinate(p.recipient, p.object);
+      const counter = instance(WorkspaceAccessPublication, `access-publication:${coordinate}`);
+      return [...ops, withMarker(set(counter, "coordinate", coordinate), "ensures"), set(counter, "revision", p.revision)];
+    },
+    workspaceEffects: [...(action.workspaceEffects ?? []), {
+      target: receiver,
+      // Payload and destination are evaluated from the same captured ports by the plan encoder.
+      destination: { kind: "workspace", address: (facts, ctx) => recipientWorkspace(publication(facts, ctx).recipient) },
+      when: (facts, ctx) => change(facts, ctx) !== null,
+      payload: publication,
+    }],
+  };
+}

package/src/framework/workspace_invariant.ts

@@ -35,10 +35,40 @@
  * workspace scan / projection read / ambient "current world" read — only the declared refs.
  */
 
+import type { AggregateHandle, ReadModelRow } from "../aggregate.js";
+import type { Directive } from "../directive.js";
+import type { ValueObject, NominalCase } from "../value_object.js";
 import type { PointGuardSpec } from "../point_guard.js";
 
 /** A TYPED verdict — identical shape to the aggregate invariant (the engine parses both). */
-export type WorkspaceInvariantVerdict = { accept: true } | { reject: string };
+export type WorkspaceInvariantVerdict<R = string> = { accept: true } | { reject: R };
+export const accept = (): { accept: true } => ({ accept: true });
+export const reject = <R>(value: R): { reject: R } => ({ reject: value });
+
+declare const READ_SNAPSHOT: unique symbol;
+type TypedReadBinding<B extends string, R> = InvariantReadBinding & {
+  readonly binding: B;
+  readonly [READ_SNAPSHOT]?: R;
+};
+type ReadRow<A> = A extends AggregateHandle<string, infer F> ? ReadModelRow<F> : Record<string, unknown>;
+type ReadBuilder<B extends string, R> = {
+  at(id: string): TypedReadBinding<B, R>;
+  fromPayload(path: string | readonly string[], options?: { readonly prefix?: string; readonly suffix?: string }): TypedReadBinding<B, R>;
+  fromOptionalPayload(path: string | readonly string[], options?: { readonly prefix?: string; readonly suffix?: string }): TypedReadBinding<B, R | undefined>;
+  fromTemplate(parts: readonly InvariantReadIdPart[], options?: { readonly optional?: boolean }): TypedReadBinding<B, R | undefined>;
+  forEach(path: string | readonly string[], parts: readonly InvariantReadIdPart[], options?: { readonly optional?: boolean }): TypedReadBinding<`${B}${number}`, R | undefined>;
+  pre(): ReadBuilder<B, R>;
+  post(): ReadBuilder<B, R>;
+};
+type ReadSnapshots<B extends readonly InvariantReadBinding[]> = {
+  [R in B[number] as R["binding"]]: R extends TypedReadBinding<string, infer V> ? V : Record<string, unknown>;
+};
+declare const READ_SET_SNAPSHOTS: unique symbol;
+type TypedReadSet<S> = WorkspaceInvariantReads & { readonly [READ_SET_SNAPSHOTS]?: S };
+type SnapshotsOf<R> = typeof READ_SET_SNAPSHOTS extends keyof R
+  ? R extends TypedReadSet<infer S> ? S : never
+  : Record<string, Record<string, unknown>>;
+
 
 /**
  * One DECLARED read: the aggregate TYPE (qualified `domain.Aggregate`) + the concrete instance
@@ -120,22 +150,10 @@ function aggregateName(aggregate: { readonly id: string } | string): string {
 
 /** Begin one typed, bounded aggregate read. Prefer an aggregate handle; strings remain available
  * for framework composition where the declaration is intentionally late-bound. */
-export function readRef(
-  binding: string,
-  aggregate: { readonly id: string } | string,
-): {
-  at(id: string): InvariantReadBinding;
-  fromPayload(path: string | readonly string[], options?: { readonly prefix?: string; readonly suffix?: string }): InvariantReadBinding;
-  fromOptionalPayload(path: string | readonly string[], options?: { readonly prefix?: string; readonly suffix?: string }): InvariantReadBinding;
-  fromTemplate(parts: readonly InvariantReadIdPart[], options?: { readonly optional?: boolean }): InvariantReadBinding;
-  forEach(
-    path: string | readonly string[],
-    parts: readonly InvariantReadIdPart[],
-    options?: { readonly optional?: boolean },
-  ): InvariantReadBinding;
-  pre(): ReturnType<typeof readRef>;
-  post(): ReturnType<typeof readRef>;
-} {
+export function readRef<const B extends string, A extends { readonly id: string } | string>(
+  binding: B,
+  aggregate: A,
+): ReadBuilder<B, ReadRow<A>> {
   const build = (state: "pre" | "post") => ({
     at(id: string): InvariantReadBinding {
       return { binding, aggregate: aggregateName(aggregate), state, id: { source: "literal", value: id } };
@@ -189,7 +207,7 @@ export function readRef(
     pre: () => build("pre"),
     post: () => build("post"),
   });
-  return build("post");
+  return build("post") as ReadBuilder<B, ReadRow<A>>;
 }
 
 function valueAtPath(value: unknown, path: readonly string[]): unknown {
@@ -247,7 +265,7 @@ export function resolveInvariantReadId(
 
 /** Declare a bounded set of generic point reads. The returned callable keeps authoring-time tests
  * ergonomic, while the non-enumerable metadata is what the compiler lowers into USDA. */
-export function readSet(...bindings: readonly InvariantReadBinding[]): WorkspaceInvariantReads {
+export function readSet<const B extends readonly InvariantReadBinding[]>(...bindings: B): TypedReadSet<ReadSnapshots<B>> {
   const selector = ((ctx: { intent: Record<string, unknown> }) => {
     const refs: InvariantRef[] = [];
     for (const binding of bindings) {
@@ -379,7 +397,9 @@ export interface WorkspaceInvariantDecl {
   /** Typed generic read recipes lowered into USDA. Absent only for not-yet-migrated callbacks. */
   readonly __nomosReadBindings?: readonly InvariantReadBinding[];
   /** The executable predicate — ships in the engine bundle, NOT the manifest. */
-  readonly assert: WorkspaceInvariantAssert;
+  readonly assert: (...args: Parameters<WorkspaceInvariantAssert>) => WorkspaceInvariantVerdict<unknown>;
+  /** Authenticated nominal output contract; absent preserves the legacy string gate. */
+  readonly refusal?: ValueObject<unknown>;
   /**
    * THE DECLASSIFY WAIVER (nomosFlowGate rule 4 — architecture/security_model.md): present iff
    * the author acknowledged that this invariant's refusal MAY correlate with a secret it reads
@@ -390,7 +410,7 @@ export interface WorkspaceInvariantDecl {
   readonly declassify?: string;
   /** Framework-owned evaluator whose complete semantics are part of the named kernel ABI.
    * Tenant-authored invariants omit this and execute their sealed USDA plan. */
-  readonly __nomosEvaluator?: "birth-quota-v1" | "founder-signer-write-once-v1" | "point-guard-v1";
+  readonly __nomosEvaluator?: "birth-quota-v1" | "founder-signer-write-once-v1" | "founder-signer-write-once-v2" | "point-guard-v1";
   /** Typed point-state law consumed directly by the kernel when evaluator is `point-guard-v1`. */
   readonly __nomosPointGuard?: PointGuardSpec;
   /** Framework-only provenance used to keep compiler errors on the tenant-authored surface. */
@@ -404,45 +424,46 @@ export interface WorkspaceInvariantDecl {
  * The staged builder makes every step REQUIRED at the type level — you cannot register a
  * half-declared invariant (no `.on`, no `.reads`, or no `.assert`).
  */
+type InvariantContext<I> = Omit<NonNullable<Parameters<WorkspaceInvariantAssert>[1]>, "intent"> & { intent: I };
+type TypedAssert<I, S, R> = (snapshots: S, ctx: InvariantContext<I>) => WorkspaceInvariantVerdict<R>;
+interface InvariantAssertions<I, S, R = string> {
+  assert(predicate: TypedAssert<I, S, R>): WorkspaceInvariantDecl;
+  declassify(reason: string): InvariantAssertions<I, S, R>;
+}
+interface InvariantReadsBuilder<I, S> extends InvariantAssertions<I, S> {
+  refuses<const N extends string, V>(refusal: ValueObject<V> & { readonly name: N }):
+    InvariantAssertions<I, S, NominalCase<N, V>>;
+}
+
 export function workspaceInvariant(id: string): {
-  on(directiveId: string): {
-    reads(reads: WorkspaceInvariantReads): {
-      assert(assert: WorkspaceInvariantAssert): WorkspaceInvariantDecl;
-      /** Acknowledge an intended secret-correlated refusal (nomosFlowGate rule 4). The reason
-       *  rides the `nomosFlowGate` era key; then chain `.assert(...)` as usual. */
-      declassify(reason: string): { assert(assert: WorkspaceInvariantAssert): WorkspaceInvariantDecl };
-    };
-  };
+  on<I>(directive: Directive<I>): { reads<R extends WorkspaceInvariantReads>(reads: R): InvariantReadsBuilder<I, SnapshotsOf<R>> };
+  on(directive: string): { reads<R extends WorkspaceInvariantReads>(reads: R): InvariantReadsBuilder<Record<string, unknown>, SnapshotsOf<R>> };
 } {
-  const finish = (directiveId: string, reads: WorkspaceInvariantReads, declassify: string | undefined) => ({
-    assert(assert: WorkspaceInvariantAssert): WorkspaceInvariantDecl {
+  const finish = (directiveId: string, reads: WorkspaceInvariantReads, declassify?: string, refusal?: ValueObject<unknown>) => ({
+    assert(predicate: WorkspaceInvariantDecl["assert"]): WorkspaceInvariantDecl {
       const readBindings = nativeReadBindings(reads);
       return {
-        id,
-        on: directiveId,
-        reads,
+        id, on: directiveId, reads,
         ...(readBindings === undefined ? {} : { __nomosReadBindings: readBindings }),
-        assert,
-        ...(declassify !== undefined ? { declassify } : {}),
-        __isWorkspaceInvariant: true as const,
+        assert: predicate,
+        ...(refusal === undefined ? {} : { refusal }),
+        ...(declassify === undefined ? {} : { declassify }),
+        __isWorkspaceInvariant: true,
       };
     },
+    declassify(reason: string) {
+      if (!reason.trim()) throw new Error(`workspaceInvariant('${id}').declassify needs a non-empty reason`);
+      return finish(directiveId, reads, reason, refusal);
+    },
+    refuses(contract: ValueObject<unknown>) {
+      return finish(directiveId, reads, declassify, contract);
+    },
   });
+  // One erased implementation boundary backs the typed authoring stages. Runtime
+  // admission rechecks the law contract; no generic values leak into predicates.
   return {
-    on(directiveId: string) {
-      return {
-        reads(reads: WorkspaceInvariantReads) {
-          return {
-            assert: finish(directiveId, reads, undefined).assert,
-            declassify(reason: string) {
-              if (typeof reason !== "string" || reason.trim().length === 0) {
-                throw new Error(`workspaceInvariant('${id}').declassify(reason) needs a non-empty human reason — it is the audit record for an intended secret-correlated refusal.`);
-              }
-              return finish(directiveId, reads, reason);
-            },
-          };
-        },
-      };
+    on(directive: string | Directive<any>) {
+      return { reads: (reads: WorkspaceInvariantReads) => finish(typeof directive === "string" ? directive : directive.id, reads) };
     },
-  };
+  } as ReturnType<typeof workspaceInvariant>;
 }