@jini-ai/cms 0.1.0

package/dist/content-types/write-service.d.ts

@@ -0,0 +1,141 @@
+import type { ClockPort } from "../core/ports.js";
+import { type ActorIdentityInput, type ActorPrincipalKind, type ContentTypeFieldDef, type ContentTypeRecord, type Result } from "./types.js";
+/**
+ * @file Write-service — `registerContentType`/`updateContentTypeFields`, the single write
+ * chokepoint for the `content_types` registry.
+ *
+ * Purpose:
+ * The ONLY path that creates or full-replaces a content type's field schema. Every export here:
+ * `authorize()` first (fail-closed) -> the fixed definition-time guard sequence (CIC U-002-B1) ->
+ * same-transaction row + revision write (+ watermark stamp when supplied) -> index provisioning.
+ *
+ * `registerContentType`'s CIC U-002-B1 guard order is binding, not incidental: key grammar ->
+ * reserved-key -> field-name grammar -> field-kind -> queryable-cap, evaluation stops at the
+ * first failure. `updateContentTypeFields`'s CIC U-004-B1 additionally requires `expectedVersion`
+ * to be checked BEFORE the `fields_empty` floor and before any per-field guard, so a stale
+ * `expectedVersion` combined with `fields: []` reports `VERSION_CONFLICT`, never
+ * `VALIDATION_ERROR(fields_empty)`.
+ *
+ * How it relates to the project:
+ * `deps.watermark` (REQ-01/INV-08) and the actor-identity delegation fields
+ * (`delegatedByWorkspaceId`/`delegatedById`, REQ-16) are both optional/additive — every
+ * pre-existing call site that omits them is unaffected; `watermark-stamping.integration.test.ts`
+ * exercises both.
+ *
+ * Architectural role:
+ * `features/content-types` domain logic. Depends only on `core/ports` and this package's own
+ * `errors.ts`/`index-provisioning.ts`/`types.ts` — no adapter, no other feature.
+ */
+/** Matches every other feature's chokepoint `AuthorizeFn` shape structurally — no shared import, kept decoupled. */
+export type AuthorizeFn = (params: {
+    principalId: string;
+    permission: string;
+    workspaceId: string;
+}) => Promise<{
+    allowed: boolean;
+    reason: string;
+}>;
+export interface ContentTypeRevisionInput {
+    contentTypeKey: string;
+    workspaceId: string;
+    op: "register" | "field-change";
+    stateJson: ContentTypeRecord;
+    actorId: string;
+    /**
+     * Audit provenance — the actor CLASS behind `actorId` (`'user'` for a human admin request,
+     * `'agent'` for a write made through the assistant's tool surface, `'system'` for an internal
+     * boot-time registration). `null` when the caller did not supply one; see
+     * `ActorIdentityInput.principalKind` for why `actorId` alone cannot answer the audit question.
+     */
+    principalKind: ActorPrincipalKind | null;
+    delegatedByWorkspaceId: string | null;
+    delegatedById: string | null;
+    recordedAt: string;
+}
+export interface ContentTypeRepoPort {
+    save(row: ContentTypeRecord): Promise<void>;
+    appendRevision(revision: ContentTypeRevisionInput): Promise<void>;
+    findByKey(params: {
+        workspaceId: string;
+        key: string;
+    }): Promise<ContentTypeRecord | null>;
+    transaction<T>(fn: () => Promise<T>): Promise<T>;
+}
+export interface IndexProvisionerPort {
+    provisionIndexesForNewContentType(input: {
+        workspaceId: string;
+        contentTypeKey: string;
+        fields: ContentTypeFieldDef[];
+    }): Promise<void>;
+    applyFieldIndexTransitions(input: {
+        workspaceId: string;
+        contentTypeKey: string;
+        transitions: Array<{
+            fieldName: string;
+            action: "provision" | "teardown" | "reprovision";
+        }>;
+    }): Promise<void>;
+}
+export interface OutboxPort {
+    enqueue(event: {
+        name: string;
+        payload: Record<string, unknown>;
+    }): Promise<void>;
+}
+/** Optional (REQ-01/INV-08) — advances `database_write_watermark` by exactly 1 when supplied. */
+export interface WatermarkPort {
+    stampWatermark(input: {
+        workspaceId: string;
+    }): Promise<number>;
+}
+export interface ContentTypeWriteServiceDeps {
+    repo: ContentTypeRepoPort;
+    clock: ClockPort;
+    ids: {
+        newId: () => string;
+    };
+    authorize: AuthorizeFn;
+    indexProvisioner: IndexProvisionerPort;
+    outbox: OutboxPort;
+    watermark?: WatermarkPort;
+}
+export interface RegisterContentTypeRequired {
+    deps: ContentTypeWriteServiceDeps;
+    input: ActorIdentityInput & {
+        workspaceId: string;
+        key: string;
+        label: string;
+        fields: ContentTypeFieldDef[];
+    };
+}
+/**
+ * REQ-01..08 — registers a new content type. Guard order is CIC U-002-B1, fixed and stop-at-first-
+ * failure: key grammar -> reserved-key -> field-name grammar -> field-kind -> queryable-cap.
+ *
+ * @complexity O(f) in the number of submitted fields (two guard passes over `fields`).
+ * @overallScore 100
+ */
+export declare function registerContentType(required: RegisterContentTypeRequired): Promise<Result<{
+    contentType: ContentTypeRecord;
+}, Error>>;
+export interface UpdateContentTypeFieldsRequired {
+    deps: ContentTypeWriteServiceDeps;
+    input: ActorIdentityInput & {
+        workspaceId: string;
+        key: string;
+        fields: ContentTypeFieldDef[];
+        expectedVersion: number;
+    };
+}
+/**
+ * REQ-26 — full-replace of a content type's field schema. CIC U-004-B1: `expectedVersion` is
+ * checked BEFORE the `fields_empty` floor and before any per-field guard, so a stale version
+ * combined with an empty array reports `VERSION_CONFLICT`, never `VALIDATION_ERROR`.
+ *
+ * @complexity O(f) in the number of submitted fields.
+ * @overallScore 100
+ */
+export declare function updateContentTypeFields(required: UpdateContentTypeFieldsRequired): Promise<Result<{
+    contentType: ContentTypeRecord;
+}, Error>>;
+//# sourceMappingURL=write-service.d.ts.map

package/dist/content-types/write-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-service.d.ts","sourceRoot":"","sources":["../../src/content-types/write-service.ts"],"names":[],"mappings":"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"}

package/dist/content-types/write-service.js

@@ -0,0 +1,180 @@
+import { ContentTypeNotFoundError, ForbiddenError, InvalidFieldKindError, InvalidFieldNameGrammarError, InvalidKeyGrammarError, QueryableFieldCapExceededError, ReservedContentTypeKeyError, ValidationError, VersionConflictError, } from "./errors.js";
+import { resolveFieldIndexTransition, validateIdentifierGrammar } from "./index-provisioning.js";
+import { isContentTypeFieldKind, } from "./types.js";
+/** Reserved forever for the legacy `posts` table — an operator Collection can never take these keys. */
+const RESERVED_CONTENT_TYPE_KEYS = new Set(["post", "page"]);
+/** Per-type cap on `queryable` fields (queryable-index sprawl mitigation). */
+const QUERYABLE_FIELD_CAP = 20;
+function countQueryableFields(fields) {
+    return fields.filter((f) => f.queryable).length;
+}
+/**
+ * REQ-01..08 — registers a new content type. Guard order is CIC U-002-B1, fixed and stop-at-first-
+ * failure: key grammar -> reserved-key -> field-name grammar -> field-kind -> queryable-cap.
+ *
+ * @complexity O(f) in the number of submitted fields (two guard passes over `fields`).
+ * @overallScore 100
+ */
+export async function registerContentType(required) {
+    const { deps, input } = required;
+    const authResult = await deps.authorize({
+        principalId: input.actorId,
+        permission: "admin.collections.manage",
+        workspaceId: input.workspaceId,
+    });
+    if (!authResult.allowed) {
+        return { ok: false, error: new ForbiddenError(`principal '${input.actorId}' cannot register a content type (${authResult.reason})`) };
+    }
+    // Guard 1: key grammar.
+    if (!validateIdentifierGrammar(input.key)) {
+        return { ok: false, error: new InvalidKeyGrammarError(`content-type key '${input.key}' fails the identifier grammar gate ^[a-z][a-z0-9_]{0,63}$`) };
+    }
+    // Guard 2: reserved key.
+    if (RESERVED_CONTENT_TYPE_KEYS.has(input.key)) {
+        return { ok: false, error: new ReservedContentTypeKeyError(`key '${input.key}' is permanently reserved for the legacy 'posts' table`) };
+    }
+    // Guard 3: field-name grammar (every field, before any kind/cap check).
+    for (const field of input.fields) {
+        if (!validateIdentifierGrammar(field.name)) {
+            return { ok: false, error: new InvalidFieldNameGrammarError(`field name '${field.name}' fails the identifier grammar gate`) };
+        }
+    }
+    // Guard 4: field-kind, closed enum.
+    for (const field of input.fields) {
+        if (!isContentTypeFieldKind(field.kind)) {
+            return { ok: false, error: new InvalidFieldKindError(`field '${field.name}' has kind '${field.kind}', not one of the closed field-kind enum`) };
+        }
+    }
+    // Guard 5: queryable-field cap, submitted array alone.
+    if (countQueryableFields(input.fields) > QUERYABLE_FIELD_CAP) {
+        return { ok: false, error: new QueryableFieldCapExceededError(`content type '${input.key}' submits more than ${QUERYABLE_FIELD_CAP} queryable fields`) };
+    }
+    const now = deps.clock.nowIso();
+    const contentType = {
+        workspaceId: input.workspaceId,
+        key: input.key,
+        label: input.label,
+        fields: input.fields,
+        status: "active",
+        version: 1,
+        tombstonedAt: null,
+    };
+    await deps.repo.transaction(async () => {
+        await deps.repo.save(contentType);
+        await deps.repo.appendRevision({
+            contentTypeKey: input.key,
+            workspaceId: input.workspaceId,
+            op: "register",
+            stateJson: contentType,
+            actorId: input.actorId,
+            principalKind: input.principalKind ?? null,
+            delegatedByWorkspaceId: input.delegatedByWorkspaceId ?? null,
+            delegatedById: input.delegatedById ?? null,
+            recordedAt: now,
+        });
+        if (deps.watermark)
+            await deps.watermark.stampWatermark({ workspaceId: input.workspaceId });
+    });
+    await deps.indexProvisioner.provisionIndexesForNewContentType({
+        workspaceId: input.workspaceId,
+        contentTypeKey: input.key,
+        fields: input.fields,
+    });
+    return { ok: true, value: { contentType } };
+}
+/**
+ * REQ-26 — full-replace of a content type's field schema. CIC U-004-B1: `expectedVersion` is
+ * checked BEFORE the `fields_empty` floor and before any per-field guard, so a stale version
+ * combined with an empty array reports `VERSION_CONFLICT`, never `VALIDATION_ERROR`.
+ *
+ * @complexity O(f) in the number of submitted fields.
+ * @overallScore 100
+ */
+export async function updateContentTypeFields(required) {
+    const { deps, input } = required;
+    const authResult = await deps.authorize({
+        principalId: input.actorId,
+        permission: "admin.collections.manage",
+        workspaceId: input.workspaceId,
+    });
+    if (!authResult.allowed) {
+        return { ok: false, error: new ForbiddenError(`principal '${input.actorId}' cannot update content type '${input.key}' (${authResult.reason})`) };
+    }
+    const current = await deps.repo.findByKey({ workspaceId: input.workspaceId, key: input.key });
+    if (!current) {
+        return { ok: false, error: new ContentTypeNotFoundError(`content type '${input.key}' was not found in workspace '${input.workspaceId}'`) };
+    }
+    // U-004-B1: expectedVersion checked FIRST — before fields_empty, before any per-field guard.
+    if (input.expectedVersion !== current.version) {
+        return { ok: false, error: new VersionConflictError(`expected version ${input.expectedVersion} for content type '${input.key}', found ${current.version}`) };
+    }
+    if (input.fields.length === 0) {
+        return { ok: false, error: new ValidationError(`content type '${input.key}' update submitted an empty fields array`, "fields_empty") };
+    }
+    for (const field of input.fields) {
+        if (!validateIdentifierGrammar(field.name)) {
+            return { ok: false, error: new InvalidFieldNameGrammarError(`field name '${field.name}' fails the identifier grammar gate`) };
+        }
+    }
+    for (const field of input.fields) {
+        if (!isContentTypeFieldKind(field.kind)) {
+            return { ok: false, error: new InvalidFieldKindError(`field '${field.name}' has kind '${field.kind}', not one of the closed field-kind enum`) };
+        }
+    }
+    if (countQueryableFields(input.fields) > QUERYABLE_FIELD_CAP) {
+        return { ok: false, error: new QueryableFieldCapExceededError(`content type '${input.key}' submits more than ${QUERYABLE_FIELD_CAP} queryable fields`) };
+    }
+    const before = current.fields;
+    const after = input.fields;
+    const now = deps.clock.nowIso();
+    const updated = { ...current, fields: after, version: current.version + 1 };
+    await deps.repo.transaction(async () => {
+        await deps.repo.save(updated);
+        await deps.repo.appendRevision({
+            contentTypeKey: input.key,
+            workspaceId: input.workspaceId,
+            op: "field-change",
+            stateJson: updated,
+            actorId: input.actorId,
+            principalKind: input.principalKind ?? null,
+            delegatedByWorkspaceId: input.delegatedByWorkspaceId ?? null,
+            delegatedById: input.delegatedById ?? null,
+            recordedAt: now,
+        });
+        if (deps.watermark)
+            await deps.watermark.stampWatermark({ workspaceId: input.workspaceId });
+    });
+    await deps.indexProvisioner.applyFieldIndexTransitions({
+        workspaceId: input.workspaceId,
+        contentTypeKey: input.key,
+        transitions: computeFullReplaceTransitions(before, after),
+    });
+    return { ok: true, value: { contentType: updated } };
+}
+/**
+ * CIC U-003-B1 composition — resolves an index transition for every field name present on either
+ * side of a full-replace update (union of before/after names), one before/after comparison per
+ * name, and returns only the actionable (non-`"none"`) transitions.
+ *
+ * @complexity O(f) in the number of distinct field names across both arrays.
+ * @overallScore 100
+ */
+function computeFullReplaceTransitions(before, after) {
+    const beforeByName = new Map(before.map((f) => [f.name, f]));
+    const afterByName = new Map(after.map((f) => [f.name, f]));
+    const allNames = new Set([...beforeByName.keys(), ...afterByName.keys()]);
+    const transitions = [];
+    for (const name of allNames) {
+        const b = beforeByName.get(name);
+        const a = afterByName.get(name);
+        const transition = resolveFieldIndexTransition({
+            before: b ? { kind: b.kind, queryable: b.queryable } : undefined,
+            after: a ? { kind: a.kind, queryable: a.queryable } : undefined,
+        });
+        if (transition.action !== "none") {
+            transitions.push({ fieldName: name, action: transition.action });
+        }
+    }
+    return transitions;
+}
+//# sourceMappingURL=write-service.js.map

package/dist/content-types/write-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-service.js","sourceRoot":"","sources":["../../src/content-types/write-service.ts"],"names":[],"mappings":"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"}

package/dist/core/commands/change-set.d.ts

@@ -0,0 +1,98 @@
+import type { DomainEvent, ISODateTime, JsonObject, UUID } from "../ports.js";
+/**
+ * @file Change-set vocabulary and persistence contract.
+ *
+ * Purpose:
+ * Defines the durable rows that make every mutation auditable and revertible,
+ * for human and AI actors alike.
+ *
+ * How it relates to the project:
+ * - `command.ts` records one change set per executed command.
+ * - `revert.ts` walks items in reverse to undo an applied change set.
+ * - `repo.memory.ts` provides the in-memory adapter for local dev/tests.
+ *
+ * Architectural role:
+ * This is the storage shape required to land with the first persistent
+ * schema. SQLite/Postgres adapters must satisfy `ChangeSetRepoPort` unchanged.
+ *
+ * `insert()`'s optional third argument lets the caller pass the fully-formed outbox event through
+ * the SAME call, so a durable adapter can co-persist it inside the same transaction as the header
+ * + items. This does NOT bring the domain write (`mutation.execute()`) into the transaction — that
+ * remains covered by `executeCommand()`'s existing compensating-rollback path. See
+ * `docs/decisions/change-set-outbox-transaction-boundary.md` for the full rationale, including why
+ * this shape was chosen over threading a transaction handle through `OutboxPort`/`mutation.execute()`.
+ */
+export type ChangeSetStatus = "proposed" | "applied" | "reverted" | "discarded";
+export type ChangeSetOperation = "create" | "update" | "delete" | "activate";
+/** Durable header row for one reviewable, revertible unit of change. */
+export interface ChangeSetRecord {
+    id: UUID;
+    workspaceId: UUID;
+    /** Principal (user or agent) that caused the change. */
+    actorId?: UUID;
+    status: ChangeSetStatus;
+    /** Human-readable description shown in audit/review UIs. */
+    summary: string;
+    /** Client-supplied key that makes retried commands safe to reject. */
+    idempotencyKey?: string | undefined;
+    /** Link back to the chat message / plan step that motivated the change. */
+    intentRef?: string | undefined;
+    createdAt: ISODateTime;
+    appliedAt?: ISODateTime;
+    revertedAt?: ISODateTime;
+}
+/** One entity mutation inside a change set. */
+export interface ChangeSetItemRecord {
+    id: UUID;
+    changeSetId: UUID;
+    /** Entity type key used to resolve an inverse applier, e.g. `post`. */
+    entityType: string;
+    entityId: UUID;
+    operation: ChangeSetOperation;
+    /** Revision pointers for revisioned entity types. */
+    beforeRevisionId?: UUID | undefined;
+    afterRevisionId?: UUID | undefined;
+    /**
+     * Inline inverse for non-revisioned entities. An item with neither revision
+     * pointers nor an inverse payload cannot be reverted — and such
+     * entities must not be mutated by agents.
+     */
+    inversePayload?: JsonObject | undefined;
+    /**
+     * Entity version *after* the mutation (REQ-08 guard input). Revert refuses
+     * unless the entity's current version still equals this — otherwise the entity
+     * has moved on since. Undefined for entity types without a version.
+     */
+    entityVersionAtApply?: number | undefined;
+    /** Apply order; revert walks positions in reverse. */
+    position: number;
+}
+/** Change set header plus its ordered items. */
+export interface ChangeSetWithItems {
+    changeSet: ChangeSetRecord;
+    items: ChangeSetItemRecord[];
+}
+/** Persistence contract for change sets. */
+export interface ChangeSetRepoPort {
+    /**
+     * `event`, when present, must be durably recorded atomically with `record`/`items` (BR-04 —
+     * see this file's header). A SQLite adapter co-persists it inside the same transaction; the
+     * in-memory adapter forwards it to its injected event bus/outbox. Omit `event` for a change set
+     * that has no associated domain event to deliver.
+     */
+    insert(record: ChangeSetRecord, items: ChangeSetItemRecord[], event?: DomainEvent): Promise<void>;
+    findById(required: {
+        workspaceId: UUID;
+        id: UUID;
+    }): Promise<ChangeSetWithItems | null>;
+    findByIdempotencyKey(required: {
+        workspaceId: UUID;
+        idempotencyKey: string;
+    }): Promise<ChangeSetRecord | null>;
+    listByWorkspace(required: {
+        workspaceId: UUID;
+    }): Promise<ChangeSetRecord[]>;
+    /** Persist status transitions (applied -> reverted, proposed -> discarded, …). */
+    save(record: ChangeSetRecord): Promise<void>;
+}
+//# sourceMappingURL=change-set.d.ts.map

package/dist/core/commands/change-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-set.d.ts","sourceRoot":"","sources":["../../../src/core/commands/change-set.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;AAEhF,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE7E,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,IAAI,CAAC;IACT,WAAW,EAAE,IAAI,CAAC;IAClB,wDAAwD;IACxD,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,MAAM,EAAE,eAAe,CAAC;IACxB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,SAAS,EAAE,WAAW,CAAC;IACvB,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,UAAU,CAAC,EAAE,WAAW,CAAC;CAC1B;AAED,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,IAAI,CAAC;IACT,WAAW,EAAE,IAAI,CAAC;IAClB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,IAAI,CAAC;IACf,SAAS,EAAE,kBAAkB,CAAC;IAC9B,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;IACpC,eAAe,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;IACnC;;;;OAIG;IACH,cAAc,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACxC;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,eAAe,CAAC;IAC3B,KAAK,EAAE,mBAAmB,EAAE,CAAC;CAC9B;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,mBAAmB,EAAE,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClG,QAAQ,CAAC,QAAQ,EAAE;QAAE,WAAW,EAAE,IAAI,CAAC;QAAC,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IACxF,oBAAoB,CAAC,QAAQ,EAAE;QAC7B,WAAW,EAAE,IAAI,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;KACxB,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IACpC,eAAe,CAAC,QAAQ,EAAE;QAAE,WAAW,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAC7E,kFAAkF;IAClF,IAAI,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C"}

package/dist/core/commands/change-set.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=change-set.js.map

package/dist/core/commands/change-set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-set.js","sourceRoot":"","sources":["../../../src/core/commands/change-set.ts"],"names":[],"mappings":""}

package/dist/core/commands/command.d.ts

@@ -0,0 +1,168 @@
+import type { ClockPort, IdGeneratorPort, JsonObject, OutboxPort, UUID } from "../ports.js";
+import type { ChangeSetOperation, ChangeSetRepoPort } from "./change-set.js";
+/**
+ * @file The single mutation write path.
+ *
+ * Purpose:
+ * Every admin mutation — human save or AI tool call — runs through
+ * `executeCommand`, which captures the inverse, executes the feature call, and
+ * records an auto-applied single-item change set. Audit trail by construction.
+ *
+ * How it relates to the project:
+ * - Wraps `features/*` mutation functions; never contains domain logic itself.
+ * - Persists via `ChangeSetRepoPort`; announces via the outbox when provided.
+ * - `revert.ts` consumes the recorded inverse payloads to undo change sets.
+ *
+ * Architectural role:
+ * The gate that makes "auditable and undoable" a property of the system rather
+ * than a per-feature effort. Proposed (unapplied) multi-item change sets for
+ * agent plans build on this same envelope later.
+ */
+/** Principal executing a command. Agents act on behalf of a user. */
+export interface CommandActor {
+    id: UUID;
+    kind: "user" | "agent";
+    /** User the agent is acting for; unset for direct human commands. */
+    onBehalfOfId?: UUID | undefined;
+}
+/** Cross-cutting command metadata; the mutation itself lives in `CommandMutation`. */
+export interface CommandEnvelope {
+    workspaceId: UUID;
+    actor: CommandActor;
+    /** Human-readable description recorded on the change set. */
+    summary: string;
+    /** Supplied by retry-capable callers (agents must always send one). */
+    idempotencyKey?: string | undefined;
+    /** Chat message / plan step that motivated this command. */
+    intentRef?: string | undefined;
+    /**
+     * The permission this mutation requires, e.g.
+     * `"content.write"`. Must be supplied together with `ExecuteCommandDeps.authorize`
+     * — see that field's doc for the migration story. Optional only so gateway
+     * callers not yet migrated to real identity/authorize wiring keep compiling.
+     */
+    permission?: string | undefined;
+}
+/** The entity write a command performs, with its inverse capture. */
+export interface CommandMutation<TResult> {
+    entityType: string;
+    entityId: UUID;
+    operation: ChangeSetOperation;
+    /**
+     * Snapshot whatever is needed to undo this mutation, read *before* execute.
+     * Return null when no inverse exists — the change set is then recorded but
+     * cannot be reverted (and agents must not be offered this mutation).
+     */
+    captureInverse(): Promise<JsonObject | null>;
+    /** The actual feature call. Runs only after inverse capture succeeds. */
+    execute(): Promise<TResult>;
+    /**
+     * Read the entity's version from the execute result (the version *after* the
+     * mutation, REQ-08 / AC-02). Stamped onto the item as the revert guard input.
+     * Omit for entity types without a version.
+     */
+    captureEntityVersion?(result: TResult): number | null;
+    /**
+     * Compensating rollback for the memory adapter's all-or-nothing guarantee
+     * (REQ-01 / BR-04 / EC-08 / AC-17). If the change-set record fails to persist
+     * *after* `execute()` has applied the feature mutation, the gateway calls this
+     * to undo the mutation — restoring the entity to its exact pre-`execute` state
+     * (verbatim, including `version`) so no "mutation without a record" survives
+     * (INV-01). On the SQLite adapter (RT-004) a real transaction replaces this and
+     * `rollback` becomes a no-op/omitted. Omit only for a mutation whose record step
+     * cannot fail independently of its feature write (none in v1).
+     */
+    rollback?(): Promise<void>;
+}
+/**
+ * The shape of the `authorize()` gate, kept generic here so
+ * `core/commands` never imports the `identity` library (that would invert the
+ * dependency direction — `features`/libraries depend on `core`, not the
+ * reverse; see `identity/authorize.ts`'s file header). Composition roots
+ * (`server/app.ts` / `server/deps.ts`) bind a closure over the real
+ * `identity.authorize()` and its repos, and pass that closure as
+ * `ExecuteCommandDeps.authorize`.
+ */
+export type AuthorizeFn = (params: {
+    principalId: UUID;
+    permission: string;
+    workspaceId: UUID;
+    entityType?: string | undefined;
+    entityId?: UUID | undefined;
+}) => Promise<{
+    allowed: boolean;
+    reason: string;
+}>;
+/** Dependencies for executeCommand. */
+export interface ExecuteCommandDeps {
+    clock: ClockPort;
+    idGen: IdGeneratorPort;
+    changeSets: ChangeSetRepoPort;
+    /** When provided, `change-set.applied` is enqueued for async consumers. */
+    outbox?: OutboxPort | undefined;
+    /**
+     * Authorization gate. Must be supplied together with
+     * `CommandEnvelope.permission` — omitting one while supplying the other is a
+     * wiring bug (see `executeCommand`'s guard) rather than something that
+     * should silently allow or silently skip. Omitting BOTH is the legacy
+     * pre-identity path, kept so gateway callers not yet migrated to real
+     * identity/authorize wiring keep compiling and passing (see the Programmer
+     * handoff for which routes remain unconverted this pass).
+     */
+    authorize?: AuthorizeFn | undefined;
+}
+/** Required parameters for executeCommand. */
+export interface ExecuteCommandRequired<TResult> {
+    deps: ExecuteCommandDeps;
+    command: CommandEnvelope;
+    mutation: CommandMutation<TResult>;
+}
+/** Optional parameters for executeCommand. Reserved for future use. */
+export interface ExecuteCommandOptional {
+}
+/**
+ * Thrown when a command's idempotency key was already used in the workspace.
+ * Callers should re-read current state instead of retrying the mutation.
+ */
+export declare class DuplicateCommandError extends Error {
+    readonly changeSetId: UUID;
+    constructor(message: string, changeSetId: UUID);
+}
+/**
+ * Thrown when `authorize()` denies the caller. Routes map
+ * this to 403 `FORBIDDEN`. Raised before the idempotency check (INV-04) — a
+ * replayed command id from a denied caller therefore never produces
+ * `DuplicateCommandError` either (EC-08).
+ */
+export declare class ForbiddenError extends Error {
+    readonly permission: string;
+    readonly reason: string;
+    constructor(message: string, permission: string, reason: string);
+}
+/**
+ * Execute a mutation through the command gateway.
+ *
+ * Order matters: idempotency check → inverse capture → execute → record.
+ * If execute throws, nothing is recorded; if inverse capture throws, the
+ * mutation never runs.
+ *
+ * The feature mutation and its change-set record commit as one unit of work
+ * (REQ-01): if `changeSets.insert` fails after `execute` has applied the
+ * mutation, the gateway rolls the mutation back via `mutation.rollback` and
+ * re-throws, so no change set and no outbox event survive (EC-08 / AC-17,
+ * INV-01).
+ *
+ * The `change-set.applied` event is passed as `changeSets.insert()`'s third argument, not a
+ * separate `deps.outbox.enqueue()` call afterward — a durable adapter co-persists it inside the
+ * same transaction as the change-set record, so it can never land without a durable delivery
+ * record (or vice versa). This still does NOT cover the domain mutation itself
+ * (`mutation.execute()` stays outside any shared transaction, covered only by the compensating
+ * rollback above), and it covers only this producer. See
+ * `docs/decisions/change-set-outbox-transaction-boundary.md` for the full rationale, including the
+ * other direct `OutboxPort.enqueue()` producers this decision deliberately leaves untouched.
+ */
+export declare function executeCommand<TResult>(required: ExecuteCommandRequired<TResult>, _optional?: ExecuteCommandOptional): Promise<{
+    result: TResult;
+    changeSetId: UUID;
+}>;
+//# sourceMappingURL=command.d.ts.map

package/dist/core/commands/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../src/core/commands/command.ts"],"names":[],"mappings":"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"}