@githolon/dsl 0.101.5 → 0.102.0

package/src/intent.ts

@@ -0,0 +1,587 @@
+// NOMOS — business intent composition.
+//
+// A tenant application publishes intentions, not storage directives. One intent
+// lowers to one kernel offer while composing any number of private directive
+// plans; those plans may fan out again across aggregate types. The offer is
+// therefore atomic inside one workspace without making an aggregate the owner of
+// the business action.
+
+import type { z } from "zod";
+
+import type {
+  Directive,
+  PreconditionDescriptor,
+  ReferentialMarker,
+  SecondaryOutput,
+} from "./directive.js";
+import type { Ports } from "./ctx.js";
+import type { PlannedOp } from "./ops.js";
+import type { Field } from "./fields.js";
+import type { AggregateHandle } from "./aggregate.js";
+import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
+import { businessBirthConsequence, type BusinessBirthDirective } from "./business_birth.js";
+import type { BusinessBirthDecl } from "./births.js";
+import type { WorkspaceSharingPolicy } from "./workspace_sharing.js";
+
+const INTENT_BRAND = "__nomos_business_intent_v1" as const;
+const LANGUAGE_BRAND = "__nomos_application_language_v1" as const;
+
+export interface IntentStep<I = unknown, P = unknown> {
+  readonly directive: Directive<P>;
+  readonly payload: (facts: I) => P;
+}
+
+export interface BusinessIntent<I = unknown> extends Directive<I> {
+  readonly [INTENT_BRAND]: true;
+  readonly steps: readonly IntentStep<I, any>[];
+  /** The complete public business boundary. Runtime lowering still uses Directive.payloadSchema privately. */
+  readonly contract: IntentContract<I>;
+}
+
+/** The public promise of one business action. Outputs are inferred from its composed consequences unless
+ * the author names them explicitly, in which case the compiler verifies the promise exactly. */
+export interface IntentContract<I = unknown> {
+  readonly accepts: z.ZodType<I>;
+  readonly returns: readonly string[];
+  readonly refuses: readonly string[];
+}
+
+export interface IntentContractDeclaration<I> {
+  readonly accepts: z.ZodType<I>;
+  readonly returns?: readonly AggregateHandle[];
+  readonly refuses?: readonly string[];
+}
+
+export interface ApplicationLanguage {
+  readonly [LANGUAGE_BRAND]: true;
+  readonly domain: string;
+  readonly intents: readonly BusinessIntent<any>[];
+  readonly workspaceSharing: readonly WorkspaceSharingPolicy[];
+}
+
+export interface ApplicationLanguageOptions {
+  readonly workspaceSharing?: readonly WorkspaceSharingPolicy[];
+}
+
+const stable = (value: unknown): string => {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stable).join(",")}]`;
+  return `{${Object.entries(value as Record<string, unknown>)
+    .filter(([, child]) => child !== undefined)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, child]) => `${JSON.stringify(key)}:${stable(child)}`)
+    .join(",")}}`;
+};
+
+function oneStaticRelationGate<I>(steps: readonly IntentStep<I, any>[]): Directive["requiresRelationGate"] {
+  const gates = steps
+    .map((step) => step.directive.requiresRelationGate)
+    .filter((gate): gate is NonNullable<Directive["requiresRelationGate"]> => gate !== undefined);
+  if (gates.length === 0) return undefined;
+  if (gates.some((gate) => gate.objectFrom !== undefined)) {
+    throw new Error(
+      "compound intent cannot yet remap a per-record access gate — bind that gate on the intent itself",
+    );
+  }
+  const first = stable(gates[0]);
+  if (gates.some((gate) => stable(gate) !== first)) {
+    throw new Error(
+      "compound intent directives require different access gates — declare one jointly satisfiable intent gate",
+    );
+  }
+  return gates[0];
+}
+
+function unsupportedKernelGate(directive: Directive<any>): string | undefined {
+  if (directive.attestationAuthorizedGate !== undefined) return "attestation authorization";
+  if (directive.delegatedRoleGate !== undefined) return "delegated authority";
+  if (directive.firstDeviceEnrollGate !== undefined) return "first-device enrollment";
+  if (directive.certifiesEraGate !== undefined) return "era certification";
+  if (directive.businessSourceTrust !== undefined) return "source-trust preflight";
+  if ((directive.businessRecordInputs?.length ?? 0) > 0) return "record-input binding";
+  return undefined;
+}
+
+const dedupeBy = <T>(values: readonly T[], key: (value: T) => string): T[] => {
+  const out: T[] = [];
+  const seen = new Set<string>();
+  for (const value of values) {
+    const k = key(value);
+    if (seen.add(k)) out.push(value);
+  }
+  return out;
+};
+
+/**
+ * Carry a private consequence's declared target onto its primary operations.
+ *
+ * A bare-handle `set(Aggregate, ...)` intentionally contains no instance/type plumbing. When that
+ * consequence is an Ensure inside a public intent, however, the wire gate must see the declared aggregate
+ * type so it can distinguish a sanctioned deterministic ensure from an invented raw id. The declaration is
+ * already authoritative; composing it here keeps domain authors out of `ensure(type, handWrittenId)` recipes.
+ */
+function composePrimaryConsequenceOp(
+  directive: Directive<any>,
+  op: PlannedOp,
+): PlannedOp {
+  if (op.kind === "strike") return op;
+  const targetsPrimary = op.aggregateType !== undefined
+    ? op.aggregateType === directive.aggregateId
+    : op.aggregateId === directive.aggregateId;
+  if (!targetsPrimary) return op;
+  return {
+    ...op,
+    ...(directive.marker === "ensures" && op.aggregateType === undefined
+      ? { aggregateType: directive.aggregateId }
+      : {}),
+    marker: directive.marker,
+  };
+}
+
+class IntentBuilder<I> {
+  constructor(
+    private readonly id: string,
+    private readonly contractDeclaration: IntentContractDeclaration<I>,
+    private readonly steps: readonly IntentStep<I, any>[] = [],
+  ) {}
+
+  /** Add one private directive consequence to this business intent. */
+  directs<P>(directive: Directive<P>, payload: (facts: I) => P): IntentBuilder<I> {
+    if (isBusinessIntent(directive)) {
+      throw new Error(`intent('${this.id}') cannot direct another intent — compose its private directives instead`);
+    }
+    if (directive.birthsChild === true) {
+      throw new Error(`intent('${this.id}') composes a declared birth with .births(...), never a raw birth directive`);
+    }
+    return new IntentBuilder(this.id, this.contractDeclaration, [
+      ...this.steps,
+      { directive, payload },
+    ]);
+  }
+
+  /** Add one declared child birth as a consequence; Nomos owns the private genesis recipe. */
+  births<P extends Record<string, unknown>, F extends Record<string, Field>>(
+    declaration: BusinessBirthDecl<P, F>,
+    payload: (facts: I) => P,
+  ): IntentBuilder<I> {
+    const directive = businessBirthConsequence(declaration);
+    return new IntentBuilder(this.id, this.contractDeclaration, [
+      ...this.steps,
+      { directive, payload },
+    ]);
+  }
+
+  /** Finish the intent and lower its directive graph to one atomic offer. */
+  atomically(): BusinessIntent<I> {
+    if (this.steps.length === 0) {
+      throw new Error(`intent('${this.id}') needs at least one directed consequence`);
+    }
+    const duplicate = this.steps.find(
+      (step, index) => this.steps.findIndex((candidate) => candidate.directive.id === step.directive.id) !== index,
+    );
+    if (duplicate !== undefined) {
+      throw new Error(`intent('${this.id}') directs '${duplicate.directive.id}' more than once`);
+    }
+    const birthSteps = this.steps.filter((step) => step.directive.birthsChild === true);
+    if (birthSteps.length > 1) {
+      throw new Error(`intent('${this.id}') cannot birth more than one durable life atomically`);
+    }
+    for (const step of this.steps) {
+      const unsupported = unsupportedKernelGate(step.directive);
+      if (unsupported !== undefined) {
+        throw new Error(
+          `intent('${this.id}') cannot compose '${step.directive.id}' yet: ${unsupported} needs intent-level lowering`,
+        );
+      }
+    }
+
+    const primary = this.steps.find((step) => step.directive.birthsChild !== true)?.directive
+      ?? this.steps[0]!.directive;
+    const outputs: SecondaryOutput[] = [];
+    for (const [index, step] of this.steps.entries()) {
+      const candidate = step.directive;
+      if (
+        candidate.birthsChild !== true &&
+        candidate !== primary &&
+        !(candidate.aggregateId === primary.aggregateId && candidate.marker === primary.marker)
+      ) {
+        outputs.push({ aggregateId: candidate.aggregateId, marker: candidate.marker });
+      }
+      if (candidate.birthsChild !== true) outputs.push(...(candidate.secondaryOutputs ?? []));
+    }
+    const secondaryOutputs = dedupeBy(
+      outputs.filter(
+        (output) => !(output.aggregateId === primary.aggregateId && output.marker === primary.marker),
+      ),
+      (output) => `${output.marker}\0${output.aggregateId}`,
+    );
+    const inferredReturns = [
+      primary.aggregateId,
+      ...secondaryOutputs.map((output) => output.aggregateId),
+      ...birthSteps.flatMap((step) => {
+        const aggregateId = (step.directive as BusinessBirthDirective).businessBirth?.aggregateId;
+        return aggregateId === undefined ? [] : [aggregateId];
+      }),
+    ].filter((value, index, values) => values.indexOf(value) === index);
+    const declaredReturns = this.contractDeclaration.returns?.map((aggregate) => aggregate.id);
+    if (
+      declaredReturns !== undefined &&
+      stable([...new Set(declaredReturns)].sort()) !== stable([...inferredReturns].sort())
+    ) {
+      throw new Error(
+        `intent('${this.id}') contract returns ${declaredReturns.join(", ") || "nothing"}, but its ` +
+          `consequences affect ${inferredReturns.join(", ") || "nothing"}`,
+      );
+    }
+
+    const preconditions: PreconditionDescriptor[] = this.steps.flatMap((step) =>
+      (step.directive.preconditions ?? []).map((condition) => ({
+        ...condition,
+        idField: (facts: unknown) => condition.idField(step.payload(facts as I)),
+      })),
+    );
+    const queryReads = dedupeBy(
+      this.steps.flatMap((step) => step.directive.declaredQueryReads ?? []),
+      (query) => query.id,
+    );
+    const foreignReads = dedupeBy(
+      this.steps.flatMap((step) => step.directive.declaredForeignReads ?? []),
+      (read) => stable(read),
+    );
+    const emits: Record<string, { max?: number }> = {};
+    for (const step of this.steps) {
+      for (const [event, declaration] of Object.entries(step.directive.declaredEmits)) {
+        const prior = emits[event];
+        if (prior === undefined) {
+          emits[event] = declaration.max === undefined ? {} : { max: declaration.max };
+        } else if (prior.max === undefined || declaration.max === undefined) {
+          emits[event] = {};
+        } else {
+          emits[event] = { max: prior.max + declaration.max };
+        }
+      }
+    }
+    const relationGate = oneStaticRelationGate(this.steps);
+    const steps = [...this.steps];
+    const plan = (facts: I, ctx: Ports): PlannedOp[] => {
+      const returned: PlannedOp[] = [];
+      for (const step of steps) {
+        const mapped = step.directive.payloadSchema.parse(step.payload(facts));
+        const result = step.directive.plan(mapped, ctx);
+        if (!Array.isArray(result)) {
+          throw new Error(
+            `intent '${this.id}' consequence '${step.directive.id}' did not return an operation array`,
+          );
+        }
+        returned.push(...result.map((op) => composePrimaryConsequenceOp(step.directive, op)));
+      }
+      return returned;
+    };
+
+    const businessBirth = (birthSteps[0]?.directive as BusinessBirthDirective | undefined)?.businessBirth;
+    return {
+      [INTENT_BRAND]: true,
+      id: this.id,
+      contract: {
+        accepts: this.contractDeclaration.accepts,
+        returns: Object.freeze(inferredReturns),
+        refuses: Object.freeze([...(this.contractDeclaration.refuses ?? [])]),
+      },
+      marker: primary.marker as ReferentialMarker,
+      aggregateId: primary.aggregateId,
+      ...(secondaryOutputs.length > 0 ? { secondaryOutputs } : {}),
+      payloadSchema: (birthSteps[0]?.directive.payloadSchema ?? this.contractDeclaration.accepts) as unknown as z.ZodType<I>,
+      plan,
+      steps,
+      declaredReads: [...new Set(this.steps.flatMap((step) => step.directive.declaredReads))].sort(),
+      ...(queryReads.length > 0 ? { declaredQueryReads: queryReads } : {}),
+      ...(foreignReads.length > 0 ? { declaredForeignReads: foreignReads } : {}),
+      declaredEmits: emits,
+      declaredRelations: dedupeBy(
+        this.steps.flatMap((step) => step.directive.declaredRelations),
+        (relation) => stable(relation),
+      ),
+      declaredHostCapabilities: [
+        ...new Set(this.steps.flatMap((step) => step.directive.declaredHostCapabilities)),
+      ].sort(),
+      ...(preconditions.length > 0 ? { preconditions } : {}),
+      ...(relationGate !== undefined ? { requiresRelationGate: relationGate } : {}),
+      ...(businessBirth === undefined
+        ? {}
+        : {
+            birthsChild: true,
+            businessBirth: {
+              ...businessBirth,
+              publicPayloadSchema: this.contractDeclaration.accepts,
+            },
+          }),
+    };
+  }
+}
+
+class IntentContractStep {
+  constructor(private readonly id: string) {}
+
+  /**
+   * Publish one existing effect as a business intent without repeating its
+   * payload schema. Useful while moving an established domain from routable
+   * directives to a closed application language.
+   */
+  performs<P>(effect: Directive<P>): BusinessIntent<P> {
+    if (isBusinessIntent(effect)) {
+      throw new Error(`intent('${this.id}').performs(...) expects a private directive effect, not an intent`);
+    }
+    const step: IntentStep<P, P> = { directive: effect, payload: (facts) => facts };
+    // A one-effect publication does not need to synthesize or approximate any
+    // kernel policy. Preserve the effect's complete metadata (birth, access,
+    // custody, recovery, preconditions, activity...) and change only the public
+    // route identity. Multi-effect intents still use `.directs(...).atomically()`
+    // and its explicit composition checks.
+    return {
+      ...effect,
+      [INTENT_BRAND]: true,
+      id: this.id,
+      contract: {
+        accepts: effect.payloadSchema,
+        returns: Object.freeze([
+          effect.aggregateId,
+          ...(effect.secondaryOutputs ?? []).map((output) => output.aggregateId),
+        ].filter((value, index, values) => values.indexOf(value) === index)),
+        refuses: Object.freeze([]),
+      },
+      steps: [step],
+      plan: (facts, ctx) => effect
+        .plan(effect.payloadSchema.parse(facts), ctx)
+        .map((op) => composePrimaryConsequenceOp(effect, op)),
+    };
+  }
+
+  /** Begin an intent from one declared business birth without repeating its payload schema. */
+  births<P extends Record<string, unknown>, F extends Record<string, Field>>(
+    declaration: BusinessBirthDecl<P, F>,
+  ): IntentBuilder<P> {
+    return new IntentBuilder<P>(this.id, { accepts: declaration.payloadSchema as z.ZodType<P> }, [
+      { directive: businessBirthConsequence(declaration), payload: (facts) => facts },
+    ]);
+  }
+
+  contract<S extends z.ZodTypeAny>(
+    declaration: IntentContractDeclaration<z.infer<S>> & { readonly accepts: S },
+  ): IntentBuilder<z.infer<S>> {
+    return new IntentBuilder(this.id, declaration as IntentContractDeclaration<z.infer<S>>);
+  }
+}
+
+/** Begin one public business intent. */
+export function intent<const Id extends string>(id: Id): IntentContractStep {
+  if (id.trim().length === 0) throw new Error("intent id must not be empty");
+  if (id.startsWith("_nms")) {
+    throw new Error(`intent id '${id}' uses Nomos's reserved internal prefix '_nms'`);
+  }
+  return new IntentContractStep(id);
+}
+
+export function isBusinessIntent(value: unknown): value is BusinessIntent<any> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    (value as Record<string, unknown>)[INTENT_BRAND] === true
+  );
+}
+
+/** Declare the complete public language for one domain. */
+export function language(
+  domain: string,
+  intents: readonly BusinessIntent<any>[],
+  options: ApplicationLanguageOptions = {},
+): ApplicationLanguage {
+  if (domain.trim().length === 0) throw new Error("language domain must not be empty");
+  const seen = new Set<string>();
+  for (const candidate of intents) {
+    if (!isBusinessIntent(candidate)) {
+      throw new Error(`language('${domain}') accepts finished intent(...).atomically() declarations only`);
+    }
+    if (seen.has(candidate.id)) {
+      throw new Error(`language('${domain}') publishes intent '${candidate.id}' more than once`);
+    }
+    seen.add(candidate.id);
+  }
+  const workspaceSharing = Object.freeze([...(options.workspaceSharing ?? [])]);
+  for (const policy of workspaceSharing) {
+    for (const initiator of policy.initiatedBy) {
+      if (!intents.some((candidate) => candidate.id === initiator.id)) {
+        throw new Error(
+          `language('${domain}') workspaceSharing(${policy.orders.id}) initiator '${initiator.id}' is not a public business action`,
+        );
+      }
+    }
+  }
+  return {
+    [LANGUAGE_BRAND]: true,
+    domain,
+    intents: Object.freeze([...intents]),
+    workspaceSharing,
+  };
+}
+
+export function isApplicationLanguage(value: unknown): value is ApplicationLanguage {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    (value as Record<string, unknown>)[LANGUAGE_BRAND] === true
+  );
+}
+
+export function applicationLanguageOf(
+  modules: readonly Record<string, unknown>[],
+  domain: string,
+): ApplicationLanguage | undefined {
+  const found: ApplicationLanguage[] = [];
+  for (const mod of modules) {
+    for (const value of Object.values(mod)) {
+      if (isApplicationLanguage(value)) found.push(value);
+    }
+  }
+  const unique = [...new Set(found)];
+  if (unique.length > 1) {
+    throw new Error(`domain '${domain}' exports more than one application language`);
+  }
+  const language = unique[0];
+  if (language !== undefined && language.domain !== domain) {
+    throw new Error(
+      `domain '${domain}' exports language('${language.domain}') — the language name must match its domain`,
+    );
+  }
+  return language;
+}
+
+/**
+ * Close the executable command surface around a declared application language.
+ * The intent plans are routable; the directives they compose are private plan
+ * fragments and cannot be offered separately.
+ */
+export function executableDirectivesForLanguage(
+  language: ApplicationLanguage,
+  discovered: readonly Directive<any>[],
+  domain: string,
+): Directive<any>[] {
+  const publicById = new Map(language.intents.map((candidate) => [candidate.id, candidate]));
+  const privateIds = new Set(
+    language.intents.flatMap((candidate) => candidate.steps.map((step) => step.directive.id)),
+  );
+
+  for (const candidate of language.intents) {
+    if (privateIds.has(candidate.id)) {
+      throw new Error(
+        `domain '${domain}' publishes intent '${candidate.id}' with the same name as one of its private directives`,
+      );
+    }
+  }
+  for (const candidate of discovered) {
+    const published = publicById.get(candidate.id);
+    const sameLowering =
+      published !== undefined &&
+      isBusinessIntent(candidate) &&
+      candidate.aggregateId === published.aggregateId &&
+      candidate.marker === published.marker &&
+      candidate.steps.length === published.steps.length &&
+      candidate.steps.every(
+        (step, index) => step.directive.id === published.steps[index]?.directive.id,
+      );
+    if (published !== undefined && candidate !== published && !sameLowering) {
+      throw new Error(
+        `domain '${domain}' intent '${candidate.id}' collides with a different directive — rename one of them`,
+      );
+    }
+    if (isBusinessIntent(candidate) && published === undefined) {
+      throw new Error(
+        `domain '${domain}' exports intent '${candidate.id}' outside its declared language — add it to language('${domain}', [...]) or remove it`,
+      );
+    }
+  }
+
+  const remaining = discovered.filter(
+    (candidate) => !privateIds.has(candidate.id) && !isBusinessIntent(candidate),
+  );
+  return [...remaining, ...language.intents];
+}
+
+/**
+ * Refuse a half-migrated source module. Once a domain declares its language,
+ * every authored directive export must either be a published intent or one of
+ * that intent's private effects. Compiler-generated framework directives are
+ * added later and are deliberately outside this source-level completeness gate.
+ */
+export function assertApplicationLanguageCoversAuthoredDirectives(
+  language: ApplicationLanguage,
+  authored: readonly Directive<any>[],
+  domain: string,
+): void {
+  const publicIds = new Set(language.intents.map((candidate) => candidate.id));
+  const privateIds = new Set(
+    language.intents.flatMap((candidate) => candidate.steps.map((step) => step.directive.id)),
+  );
+  const sharingReceiptIds = new Set(
+    language.workspaceSharing.flatMap((policy) =>
+      [...policy.delivered, ...policy.refused].map((receipt) => receipt.records.id)
+    ),
+  );
+  const uncovered = authored
+    .filter(
+      (directive) =>
+        directive.businessBirthInternal !== true &&
+        !publicIds.has(directive.id) &&
+        !privateIds.has(directive.id) &&
+        !sharingReceiptIds.has(directive.id),
+    )
+    .map((directive) => directive.id)
+    .sort();
+  if (uncovered.length > 0) {
+    throw new Error(
+      `domain '${domain}' declares language('${domain}', [...]) but still exports routable directive ` +
+        `${uncovered.map((id) => `'${id}'`).join(", ")} outside it — publish business intents for ` +
+        `those actions or make their effects private`,
+    );
+  }
+}
+
+/** Carry a private directive's invariant onto every public intent that uses it. */
+export function remapWorkspaceInvariantsForLanguage(
+  invariants: readonly WorkspaceInvariantDecl[],
+  language: ApplicationLanguage,
+): WorkspaceInvariantDecl[] {
+  const out: WorkspaceInvariantDecl[] = [];
+  for (const invariant of invariants) {
+    const uses = language.intents.flatMap((candidate) =>
+      candidate.steps
+        .filter((step) => step.directive.id === invariant.on)
+        .map((step) => ({ intent: candidate, step })),
+    );
+    if (uses.length === 0) {
+      out.push(invariant);
+      continue;
+    }
+    for (const use of uses) {
+      const mapFacts = (facts: Record<string, unknown>): Record<string, unknown> => {
+        const mapped = use.step.payload(facts);
+        const parsed = use.step.directive.payloadSchema.safeParse(mapped);
+        // The flow/security compiler probes invariant read-sets with empty
+        // placeholder facts. That probe must remain total even when the real
+        // business payload requires non-empty values. Runtime intent planning
+        // still validates every mapped consequence before it can commit.
+        return (parsed.success ? parsed.data : mapped) as Record<string, unknown>;
+      };
+      out.push({
+        ...invariant,
+        id: `${use.intent.id}__${invariant.id}`,
+        on: use.intent.id,
+        reads: (ctx) => invariant.reads({ ...ctx, intent: mapFacts(ctx.intent) }),
+        assert: (snapshots, ctx) => invariant.assert(
+          snapshots,
+          ctx === undefined ? undefined : { ...ctx, intent: mapFacts(ctx.intent) },
+        ),
+      });
+    }
+  }
+  return out;
+}