@githolon/dsl 0.1.0

package/src/framework/sync_lifecycle.ts

@@ -0,0 +1,125 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine}. Host JS only instantiates the WASI module and supplies storage/transport;
+// the wasm blob is the deterministic execution boundary. No native, no wasmtime,
+// no 2nd artifact, no domain-JS on host V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * Nomos sync lifecycle.
+ *
+ * Sync is a control-plane impure capability: Nomos records the desired workspace
+ * reconciliation as an ordinary Order, a host/provider performs transport using
+ * explicit capabilities, and the outcome comes back as an ordinary Receipt. The
+ * remote/JWT/network is never ambient domain state; the ledger carries request,
+ * status, cursors, heads, and errors.
+ */
+import { z } from "zod";
+import { instance, type BoundAggregate } from "../aggregate.js";
+import { Lww } from "../drivers.js";
+import { t } from "../fields.js";
+import { set, type PlannedOp } from "../ops.js";
+import {
+  impureCapability,
+  impureCapabilityAggregate,
+  type ImpureCapability,
+} from "./impure_capability.js";
+
+export const WORKSPACE_SYNC_DIRECTIONS = ["pull", "push", "pushPull"] as const;
+export type WorkspaceSyncDirection = (typeof WORKSPACE_SYNC_DIRECTIONS)[number];
+
+const syncParams = {
+  workspaceId: t.string().merge(Lww),
+  branch: t.string().merge(Lww),
+  remote: t.string().merge(Lww),
+  direction: t.enum(WORKSPACE_SYNC_DIRECTIONS).merge(Lww),
+  reason: t.string().merge(Lww).optional(),
+  authSessionRef: t.string().merge(Lww).optional(),
+  sinceCursor: t.string().merge(Lww).optional(),
+  resultHead: t.string().merge(Lww).optional(),
+  resultCursor: t.string().merge(Lww).optional(),
+  appliedIntentCount: t.int().merge(Lww).optional(),
+  pushedIntentCount: t.int().merge(Lww).optional(),
+};
+
+export const WorkspaceSyncOperation = impureCapabilityAggregate(
+  "WorkspaceSyncOperation",
+  syncParams,
+);
+
+function optionalParamOps(
+  sync: BoundAggregate<typeof WorkspaceSyncOperation.id, typeof syncParams>,
+  p: {
+    reason?: string | undefined;
+    authSessionRef?: string | undefined;
+    sinceCursor?: string | undefined;
+  },
+): PlannedOp[] {
+  const ops: PlannedOp[] = [];
+  if (p.reason !== undefined) ops.push(set(sync, "reason", p.reason));
+  if (p.authSessionRef !== undefined) ops.push(set(sync, "authSessionRef", p.authSessionRef));
+  if (p.sinceCursor !== undefined) ops.push(set(sync, "sinceCursor", p.sinceCursor));
+  return ops;
+}
+
+function syncResultOps(taskId: string, resultRef: string): PlannedOp[] {
+  const sync = instance(WorkspaceSyncOperation, taskId);
+  const ops: PlannedOp[] = [];
+  const result = JSON.parse(resultRef) as {
+    head?: unknown;
+    cursor?: unknown;
+    appliedIntentCount?: unknown;
+    pushedIntentCount?: unknown;
+  };
+  if (typeof result.head === "string") ops.push(set(sync, "resultHead", result.head));
+  if (typeof result.cursor === "string") ops.push(set(sync, "resultCursor", result.cursor));
+  if (Number.isInteger(result.appliedIntentCount)) {
+    ops.push(set(sync, "appliedIntentCount", result.appliedIntentCount as number));
+  }
+  if (Number.isInteger(result.pushedIntentCount)) {
+    ops.push(set(sync, "pushedIntentCount", result.pushedIntentCount as number));
+  }
+  return ops;
+}
+
+const workspaceSyncTask = impureCapability({
+  aggregateId: "WorkspaceSyncOperation",
+  orderDirectiveId: "requestWorkspaceSync",
+  completeDirectiveId: "completeWorkspaceSync",
+  failDirectiveId: "failWorkspaceSync",
+  blockDirectiveId: "blockWorkspaceSync",
+  deadLetterDirectiveId: "deadLetterWorkspaceSync",
+  params: syncParams,
+  paramsSchema: {
+    workspaceId: z.string(),
+    branch: z.string().default("main"),
+    remote: z.string(),
+    direction: z.enum(WORKSPACE_SYNC_DIRECTIONS).default("pull"),
+    reason: z.string().optional(),
+    authSessionRef: z.string().optional(),
+    sinceCursor: z.string().optional(),
+  },
+  writeParams: (taskId, p) => {
+    const sync = instance(WorkspaceSyncOperation, taskId);
+    return [
+      set(sync, "workspaceId", p.workspaceId),
+      set(sync, "branch", p.branch),
+      set(sync, "remote", p.remote),
+      set(sync, "direction", p.direction),
+      ...optionalParamOps(sync, p),
+    ];
+  },
+  completeResult: syncResultOps,
+});
+
+export const requestWorkspaceSync = workspaceSyncTask.order.requires("requestWorkspaceSync");
+export const completeWorkspaceSync = workspaceSyncTask.complete.requires("completeWorkspaceSync");
+export const failWorkspaceSync = workspaceSyncTask.fail.requires("failWorkspaceSync");
+export const blockWorkspaceSync = workspaceSyncTask.block.requires("blockWorkspaceSync");
+export const deadLetterWorkspaceSync =
+  workspaceSyncTask.deadLetter.requires("deadLetterWorkspaceSync");
+
+export const NOMOS_SYNC_IMPURE_CAPABILITIES: ImpureCapability<string, never, never>[] = [
+  workspaceSyncTask as unknown as ImpureCapability<string, never, never>,
+];

package/src/framework/workspace_invariant.ts

@@ -0,0 +1,128 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * framework/workspace_invariant — the WORKSPACE INVARIANT authoring surface (#266).
+ *
+ * Consistency level 2 of 3 (see `docs/workspace_invariant.md`): a HARD, synchronous,
+ * admission-time predicate over a BOUNDED, DECLARED set of POST-APPLY aggregate snapshots —
+ * possibly ACROSS DOMAINS within the ONE workspace. (Level 1 = the per-aggregate `invariant`
+ * (#250); level 3 = cross-workspace carried evidence, never a synchronous invariant.)
+ *
+ *   workspaceInvariant("ItemMustReferenceActiveRevision")
+ *     .on("inventory.MoveItem")                          // fires for this directive
+ *     .reads(({ intent }) => [                           // BOUNDED, DECLARED read-set
+ *       ref("inventory.Item", intent.item as string),    //   (refs, possibly cross-domain,
+ *       ref("layout.Revision", intent.revision as string),//   within THIS workspace)
+ *     ])
+ *     .assert(({ item, revision }) =>                    // post-apply predicate, PURE
+ *       (revision as any).status === "active" &&
+ *       (item as any).zone === (revision as any).zone
+ *         ? { accept: true }
+ *         : { reject: "item-must-reference-active-revision" });
+ *
+ * MUST be explicit · bounded · declared · deterministic · versioned · replayable. The body
+ * runs in the SEALED engine over the resolved named-map snapshots (the engine half is
+ * `plan_workspace_invariant`, #266 slice 1); the read-set is RECORDED as validation-deps at
+ * admission (slice 4). PRESENCE ONLY is hashed in the manifest (id + the directive it is `on`),
+ * exactly like a directive `plan` / the aggregate `hasInvariant` — the executable bodies ship
+ * in the engine bundle, NEVER in the ledger. Changing a body does NOT move the domain hash;
+ * adding/removing an invariant DOES (it is law). NO arbitrary SQL / unbounded graph / whole-
+ * workspace scan / projection read / ambient "current world" read — only the declared refs.
+ */
+
+/** A TYPED verdict — identical shape to the aggregate invariant (the engine parses both). */
+export type WorkspaceInvariantVerdict = { accept: true } | { reject: string };
+
+/**
+ * One DECLARED read: the aggregate TYPE (qualified `domain.Aggregate`) + the concrete instance
+ * id, derived from the intent. `name` is the binding key the `.assert` predicate destructures
+ * the resolved snapshot under — derived from the type's short segment (e.g. `inventory.Item`
+ * → `item`, `layout.Revision` → `revision`). For two refs of the same type, pass an explicit
+ * `name` via [`refAs`] to disambiguate.
+ */
+export interface InvariantRef {
+  readonly name: string;
+  readonly aggregate: string;
+  readonly id: string;
+}
+
+/** `inventory.Item` → `item`; `layout.FloorPlan` → `floorPlan` (short segment, first-lower). */
+function deriveName(aggregateType: string): string {
+  const short = aggregateType.includes(".")
+    ? aggregateType.slice(aggregateType.lastIndexOf(".") + 1)
+    : aggregateType;
+  return short.length > 0 ? short[0]!.toLowerCase() + short.slice(1) : short;
+}
+
+/** A declared read of `aggregateType`'s instance `id`; bound under its derived short name. */
+export function ref(aggregateType: string, id: string): InvariantRef {
+  return { name: deriveName(aggregateType), aggregate: aggregateType, id };
+}
+
+/** A declared read bound under an EXPLICIT `name` (disambiguates two refs of the same type). */
+export function refAs(name: string, aggregateType: string, id: string): InvariantRef {
+  return { name, aggregate: aggregateType, id };
+}
+
+/** Derive the BOUNDED declared read-set from the intent payload. Pure — no IO, no live read. */
+export type WorkspaceInvariantReads = (ctx: { intent: Record<string, unknown> }) => InvariantRef[];
+
+/**
+ * The post-apply predicate over the resolved snapshots, keyed by each ref's binding `name`.
+ * PURE over the named map (no clock, no IO, no live reads) — runs in the sealed engine.
+ */
+export type WorkspaceInvariantAssert = (
+  snapshots: Record<string, Record<string, unknown>>,
+) => WorkspaceInvariantVerdict;
+
+/** A complete, registered workspace-invariant declaration (the `.assert` terminal yields this). */
+export interface WorkspaceInvariantDecl {
+  /** The stable wire id — the literal passed to `workspaceInvariant(...)`. Hashed (presence). */
+  readonly id: string;
+  /** The directive id this invariant fires on (e.g. `inventory.MoveItem`). Hashed (presence). */
+  readonly on: string;
+  /** The executable declared read-set — ships in the engine bundle, NOT the manifest. */
+  readonly reads: WorkspaceInvariantReads;
+  /** The executable predicate — ships in the engine bundle, NOT the manifest. */
+  readonly assert: WorkspaceInvariantAssert;
+  /** Brand so a plain object is never mistaken for a declaration. */
+  readonly __isWorkspaceInvariant: true;
+}
+
+/**
+ * Author a workspace invariant: `workspaceInvariant(id).on(directive).reads(fn).assert(fn)`.
+ * 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`).
+ */
+export function workspaceInvariant(id: string): {
+  on(directiveId: string): {
+    reads(reads: WorkspaceInvariantReads): {
+      assert(assert: WorkspaceInvariantAssert): WorkspaceInvariantDecl;
+    };
+  };
+} {
+  return {
+    on(directiveId: string) {
+      return {
+        reads(reads: WorkspaceInvariantReads) {
+          return {
+            assert(assert: WorkspaceInvariantAssert): WorkspaceInvariantDecl {
+              return {
+                id,
+                on: directiveId,
+                reads,
+                assert,
+                __isWorkspaceInvariant: true,
+              };
+            },
+          };
+        },
+      };
+    },
+  };
+}