@xemahq/kernel-contracts 0.29.0 → 0.31.0

package/dist/workspace-image/lib/schemas.d.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { ImageLayerKind, VariantStatus } from './enums';
+export declare const imageLayerKindSchema: z.ZodEnum<typeof ImageLayerKind>;
+export declare const variantStatusSchema: z.ZodEnum<typeof VariantStatus>;
+export declare const imageLayerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<ImageLayerKind.Apt>;
+    packages: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<ImageLayerKind.Dnf>;
+    packages: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<ImageLayerKind.Apk>;
+    packages: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<ImageLayerKind.Pip>;
+    packages: z.ZodArray<z.ZodString>;
+    pythonVersion: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<ImageLayerKind.NpmGlobal>;
+    packages: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<ImageLayerKind.Env>;
+    vars: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<ImageLayerKind.File>;
+    path: z.ZodString;
+    contentBase64: z.ZodString;
+    mode: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], "kind">;
+export declare const workspaceImageManifestSchema: z.ZodObject<{
+    layers: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<ImageLayerKind.Apt>;
+        packages: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ImageLayerKind.Dnf>;
+        packages: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ImageLayerKind.Apk>;
+        packages: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ImageLayerKind.Pip>;
+        packages: z.ZodArray<z.ZodString>;
+        pythonVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ImageLayerKind.NpmGlobal>;
+        packages: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ImageLayerKind.Env>;
+        vars: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ImageLayerKind.File>;
+        path: z.ZodString;
+        contentBase64: z.ZodString;
+        mode: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>], "kind">>;
+    workdir: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const workspaceImageVariantSchema: z.ZodObject<{
+    id: z.ZodString;
+    orgId: z.ZodString;
+    slug: z.ZodString;
+    description: z.ZodString;
+    runtimeKind: z.ZodEnum<typeof import("../../worker-runtime").WorkerRuntimeKind>;
+    baseImage: z.ZodString;
+    manifest: z.ZodObject<{
+        layers: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<ImageLayerKind.Apt>;
+            packages: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<ImageLayerKind.Dnf>;
+            packages: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<ImageLayerKind.Apk>;
+            packages: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<ImageLayerKind.Pip>;
+            packages: z.ZodArray<z.ZodString>;
+            pythonVersion: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<ImageLayerKind.NpmGlobal>;
+            packages: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<ImageLayerKind.Env>;
+            vars: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<ImageLayerKind.File>;
+            path: z.ZodString;
+            contentBase64: z.ZodString;
+            mode: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>], "kind">>;
+        workdir: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    contentHash: z.ZodString;
+    registryRef: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<typeof VariantStatus>;
+    isOrgDefault: z.ZodBoolean;
+    autoRebake: z.ZodBoolean;
+    regions: z.ZodArray<z.ZodString>;
+    buildLog: z.ZodOptional<z.ZodString>;
+    builtAt: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/workspace-image/lib/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/workspace-image/lib/schemas.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExD,eAAO,MAAM,oBAAoB,kCAA+B,CAAC;AACjE,eAAO,MAAM,mBAAmB,iCAA8B,CAAC;AAI/D,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;2BAoB3B,CAAC;AAEH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAGvC,CAAC;AAEH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiBtC,CAAC"}

package/dist/workspace-image/lib/schemas.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workspaceImageVariantSchema = exports.workspaceImageManifestSchema = exports.imageLayerSchema = exports.variantStatusSchema = exports.imageLayerKindSchema = void 0;
+const zod_1 = require("zod");
+const worker_runtime_1 = require("../../worker-runtime");
+const enums_1 = require("./enums");
+exports.imageLayerKindSchema = zod_1.z.nativeEnum(enums_1.ImageLayerKind);
+exports.variantStatusSchema = zod_1.z.nativeEnum(enums_1.VariantStatus);
+const packagesArray = zod_1.z.array(zod_1.z.string().min(1));
+exports.imageLayerSchema = zod_1.z.discriminatedUnion('kind', [
+    zod_1.z.object({ kind: zod_1.z.literal(enums_1.ImageLayerKind.Apt), packages: packagesArray }),
+    zod_1.z.object({ kind: zod_1.z.literal(enums_1.ImageLayerKind.Dnf), packages: packagesArray }),
+    zod_1.z.object({ kind: zod_1.z.literal(enums_1.ImageLayerKind.Apk), packages: packagesArray }),
+    zod_1.z.object({
+        kind: zod_1.z.literal(enums_1.ImageLayerKind.Pip),
+        packages: packagesArray,
+        pythonVersion: zod_1.z.string().min(1).optional(),
+    }),
+    zod_1.z.object({ kind: zod_1.z.literal(enums_1.ImageLayerKind.NpmGlobal), packages: packagesArray }),
+    zod_1.z.object({
+        kind: zod_1.z.literal(enums_1.ImageLayerKind.Env),
+        vars: zod_1.z.record(zod_1.z.string().min(1), zod_1.z.string()),
+    }),
+    zod_1.z.object({
+        kind: zod_1.z.literal(enums_1.ImageLayerKind.File),
+        path: zod_1.z.string().min(1),
+        contentBase64: zod_1.z.string().min(1),
+        mode: zod_1.z.number().int().nonnegative().optional(),
+    }),
+]);
+exports.workspaceImageManifestSchema = zod_1.z.object({
+    layers: zod_1.z.array(exports.imageLayerSchema),
+    workdir: zod_1.z.string().min(1).optional(),
+});
+exports.workspaceImageVariantSchema = zod_1.z.object({
+    id: zod_1.z.string().min(1),
+    orgId: zod_1.z.string().min(1),
+    slug: zod_1.z.string().min(1),
+    description: zod_1.z.string(),
+    runtimeKind: worker_runtime_1.workerRuntimeKindSchema,
+    baseImage: zod_1.z.string().min(1),
+    manifest: exports.workspaceImageManifestSchema,
+    contentHash: zod_1.z.string().min(1),
+    registryRef: zod_1.z.string().min(1).optional(),
+    status: exports.variantStatusSchema,
+    isOrgDefault: zod_1.z.boolean(),
+    autoRebake: zod_1.z.boolean(),
+    regions: zod_1.z.array(zod_1.z.string().min(1)),
+    buildLog: zod_1.z.string().optional(),
+    builtAt: zod_1.z.string().min(1).optional(),
+    createdAt: zod_1.z.string().min(1),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/workspace-image/lib/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/workspace-image/lib/schemas.ts"],"names":[],"mappings":"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"}

package/dist/workspace-image/lib/types.d.ts

@@ -0,0 +1,50 @@
+import type { WorkerRuntimeKind } from '../../worker-runtime';
+import type { ImageLayerKind, VariantStatus } from './enums';
+export type ImageLayer = {
+    readonly kind: ImageLayerKind.Apt;
+    readonly packages: readonly string[];
+} | {
+    readonly kind: ImageLayerKind.Dnf;
+    readonly packages: readonly string[];
+} | {
+    readonly kind: ImageLayerKind.Apk;
+    readonly packages: readonly string[];
+} | {
+    readonly kind: ImageLayerKind.Pip;
+    readonly packages: readonly string[];
+    readonly pythonVersion?: string;
+} | {
+    readonly kind: ImageLayerKind.NpmGlobal;
+    readonly packages: readonly string[];
+} | {
+    readonly kind: ImageLayerKind.Env;
+    readonly vars: Readonly<Record<string, string>>;
+} | {
+    readonly kind: ImageLayerKind.File;
+    readonly path: string;
+    readonly contentBase64: string;
+    readonly mode?: number;
+};
+export interface WorkspaceImageManifest {
+    readonly layers: readonly ImageLayer[];
+    readonly workdir?: string;
+}
+export interface WorkspaceImageVariant {
+    readonly id: string;
+    readonly orgId: string;
+    readonly slug: string;
+    readonly description: string;
+    readonly runtimeKind: WorkerRuntimeKind;
+    readonly baseImage: string;
+    readonly manifest: WorkspaceImageManifest;
+    readonly contentHash: string;
+    readonly registryRef?: string;
+    readonly status: VariantStatus;
+    readonly isOrgDefault: boolean;
+    readonly autoRebake: boolean;
+    readonly regions: readonly string[];
+    readonly buildLog?: string;
+    readonly builtAt?: string;
+    readonly createdAt: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/workspace-image/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/workspace-image/lib/types.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAU7D,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,GAAG,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,GAAG,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,GAAG,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC3E;IACE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,GAAG,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACjF;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,GAAG,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,GACtF;IACE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAUN,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IAExC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAE1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAEpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}

package/dist/workspace-image/lib/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/workspace-image/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/workspace-image/lib/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/kernel-contracts",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Consolidated Xema OS kernel wire contracts — pure types + zod schemas for the kernel protocol surfaces. One package, one npm scope, wildcard per-surface subpath exports. No framework/runtime deps.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",

package/src/decision-gate/index.ts

@@ -0,0 +1,13 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/decision-gate-contracts — Kernel layer
+//
+// Per-kind schemas for the DECISION_GATE InquiryKind: pin one or more
+// artifact versions, ask deciders for a verdict, aggregate per the
+// inquiry's policy, output the approved-version pinned set for downstream
+// consumers (publish-kb etc.) to use unconditionally.
+//
+// Pure types + Zod. Workflow VM imports `import type` only.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/pinned-subject-artifact';
+export * from './lib/decision-gate';

package/src/decision-gate/lib/decision-gate.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+
+import { PinnedSubjectArtifactSchema } from './pinned-subject-artifact';
+
+/**
+ * Verdict a decider returns on a Decision Gate inquiry.
+ *
+ * `ABSTAIN` is distinct from `REJECT`: a non-vote that the gate's policy
+ * may treat as "skip and wait for the rest" or "implicit reject" depending
+ * on the policy's `abstainTreatment`. Humans cannot ABSTAIN today (UI
+ * exposes only Approve / Reject); agents and endpoints may, e.g. when
+ * their structured output fails validation or the underlying activity
+ * exhausts retries.
+ */
+export enum DecisionVerdict {
+  APPROVE = 'approve',
+  REJECT = 'reject',
+  ABSTAIN = 'abstain',
+}
+
+/**
+ * Terminal outcome of the gate as a whole. Distinct from per-recipient
+ * verdict because it accounts for timeout + policy aggregation.
+ */
+export enum DecisionGateOutcome {
+  APPROVED = 'approved',
+  REJECTED = 'rejected',
+  EXPIRED_APPROVED = 'expired_approved',
+  EXPIRED_REJECTED = 'expired_rejected',
+  CANCELLED = 'cancelled',
+}
+
+/**
+ * Prompt payload for a DECISION_GATE inquiry. The pinned set is what
+ * deciders are deciding on; `description` is human-readable context shown
+ * to humans + included in the agent decider's prompt.
+ *
+ * `passthrough()` keeps unknown keys on the parsed object — used by
+ * orchestrators (e.g. `xema/review@v3`) that inject extra context for
+ * the FE to render (`reviewIteration`, `reviewerFindings`,
+ * `pastIterations`). Decision-gate itself never reads them; the FE
+ * gates rendering on field presence and ignores when absent.
+ */
+export const DecisionGatePromptSchema = z
+  .object({
+    subjectArtifacts: z.array(PinnedSubjectArtifactSchema),
+    description: z.string().optional(),
+  })
+  .passthrough();
+export type DecisionGatePrompt = z.infer<typeof DecisionGatePromptSchema>;
+
+/**
+ * Reply payload submitted by one decider (human / agent / endpoint). The
+ * shape is identical across recipient kinds — what differs is the
+ * `submittedBy` attribution and how the payload was produced (UI form,
+ * agent structured output, endpoint verdict mapper).
+ *
+ * `reason` is REQUIRED when the verdict is REJECT and must be a non-empty
+ * trimmed string. The contract enforces this at every entry point (engine
+ * controller, agent reply, endpoint verdict-mapper) so a reviewer cannot
+ * reject a deliverable without articulating why. APPROVE and ABSTAIN
+ * leave `reason` optional — the happy path stays frictionless and an
+ * ABSTAIN typically means "validation failed / cannot decide" which has
+ * no human-authored justification to capture.
+ */
+export const DecisionGateReplySchema = z
+  .object({
+    verdict: z.nativeEnum(DecisionVerdict),
+    reason: z.string().optional(),
+    attachment: z.record(z.string(), z.unknown()).optional(),
+  })
+  .superRefine((value, ctx) => {
+    if (value.verdict !== DecisionVerdict.REJECT) return;
+    const trimmed = value.reason?.trim() ?? '';
+    if (trimmed.length === 0) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['reason'],
+        message: 'reason is required and must be non-empty when verdict is reject',
+      });
+    }
+  });
+export type DecisionGateReply = z.infer<typeof DecisionGateReplySchema>;
+
+/**
+ * One row in the decision trail — used for audit and to render "alice
+ * approved 12:34:56, bob rejected 12:35:10, oracle-agent abstained" in
+ * the FE focused-page detail view.
+ */
+export const DecisionRecordSchema = z.object({
+  recipientId: z.string().min(1),
+  verdict: z.nativeEnum(DecisionVerdict),
+  reason: z.string().nullable(),
+  submittedBy: z.string().min(1),
+  submittedAtIso: z.string(),
+});
+export type DecisionRecord = z.infer<typeof DecisionRecordSchema>;
+
+/**
+ * Aggregated verdict the gate workflow returns to its parent. Downstream
+ * consumers (`publish-kb`, KB ingest, audit) read `approvedArtifacts` —
+ * NOT `Math.max(version)` — for the bytes to publish.
+ *
+ * `approvedArtifacts` is non-empty iff `outcome` is APPROVED /
+ * EXPIRED_APPROVED. On REJECTED / EXPIRED_REJECTED / CANCELLED, the array
+ * is empty by construction (consumers must not run).
+ */
+export const DecisionGateVerdictSchema = z.object({
+  outcome: z.nativeEnum(DecisionGateOutcome),
+  approvedArtifacts: z.array(PinnedSubjectArtifactSchema),
+  decisionTrail: z.array(DecisionRecordSchema),
+});
+export type DecisionGateVerdict = z.infer<typeof DecisionGateVerdictSchema>;

package/src/decision-gate/lib/pinned-subject-artifact.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+
+/**
+ * Pinned reference to a single artifact version. Stored on the inquiry's
+ * `prompt.subjectArtifacts` for `kind=DECISION_GATE` and propagated through
+ * the decision-gate verdict so downstream consumers (e.g. `publish-kb`,
+ * KB ingest, audit) resolve "the bytes the deciders approved" — not
+ * "whatever happens to be latest at publish time."
+ *
+ * The four-tuple `(artifactId, versionId, version, hash)` is the result
+ * of `flattenSubjectArtifacts` over upstream `deliverables[]` at the
+ * moment the gate workflow registers the inquiry. Once written, it is
+ * frozen for the lifetime of the inquiry.
+ *
+ * Canonical home for this type. Predecessor refactors (artifact-identity
+ * PR1-PR3) inlined it inside the human-approval workflow file because the
+ * workflow VM cannot run Zod; this package keeps the type importable as
+ * `import type` from the workflow file while the engine validates it via
+ * Zod at the controller boundary.
+ */
+export const PinnedSubjectArtifactSchema = z.object({
+  artifactId: z.string().min(1),
+  versionId: z.string().min(1),
+  version: z.number().int().positive(),
+  hash: z.string().min(1),
+});
+export type PinnedSubjectArtifact = z.infer<
+  typeof PinnedSubjectArtifactSchema
+>;

package/src/document-patch/index.ts

@@ -0,0 +1,25 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/document-patch-contracts — Kernel layer
+//
+// Wire contracts for the per-hunk edits to a knowledge-base document page.
+//
+// Pending patches are NOT authored by the agent. They are platform-derived:
+// `document-sync` diffs the agent's working file against the accepted base
+// and re-derives the page's `PendingPatch` rows as contiguous line-range
+// hunks. Used by:
+//   - knowledge-base-api's pending-patches endpoints (DTO shapes)
+//   - the frontend hunk-decoration UI (type-only)
+//
+// Per-hunk accept/reject is the central UX primitive: the user can take any
+// subset of the agent's changes. To make that safe against concurrent user
+// edits, every hunk carries the base version it was computed against and a
+// line-range `anchor` describing WHERE it applies. The accept endpoint
+// refuses the apply if the surrounding text shifted out from under the
+// anchor (`PendingPatchStatus.STALE`), so silent drift is impossible.
+//
+// Pure types + Zod. Zero runtime adapter knowledge.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/patch-enums';
+export * from './lib/patch-anchor';
+export * from './lib/pending-patch';

package/src/document-patch/lib/patch-anchor.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+/**
+ * Where a pending patch applies in the document: a 1-based inclusive
+ * line range in BASE. Pending patches are platform-derived by diffing
+ * the agent's working file against the accepted base — every hunk is a
+ * contiguous line range, so this is the only anchor shape.
+ *
+ * `endLine === startLine - 1` is the canonical encoding for a
+ * pure-insertion-before-line patch (zero-length range positioned just
+ * before `startLine`).
+ */
+export const LineRangeAnchorSchema = z
+  .object({
+    startLine: z.number().int().min(1),
+    endLine: z.number().int().min(0),
+  })
+  .refine((v) => v.endLine >= v.startLine - 1, {
+    message: 'LineRangeAnchor requires endLine >= startLine - 1',
+    path: ['endLine'],
+  });
+export type LineRangeAnchor = z.infer<typeof LineRangeAnchorSchema>;

package/src/document-patch/lib/patch-enums.ts

@@ -0,0 +1,36 @@
+/**
+ * Closed enums for the patch protocol. Real TS enums (not string-literal
+ * unions) so OpenAPI/Orval emit stable enum schemas — see
+ * `docs/API_STANDARDS.md` and.
+ */
+
+/**
+ * Where this pending patch came from.
+ *
+ *   - AGENT_SESSION   — derived from an interactive Document Buddy
+ *                       session's working-file edits (document-sync).
+ *   - WORKFLOW_REVIEW — a workflow activity proposing edits on the user's
+ *                       behalf.
+ */
+export enum PatchOrigin {
+  AGENT_SESSION = 'AGENT_SESSION',
+  WORKFLOW_REVIEW = 'WORKFLOW_REVIEW',
+}
+
+/**
+ * Lifecycle status for a single PendingPatch row.
+ *
+ *   - PENDING  — awaiting a user decision.
+ *   - ACCEPTED — applied to the page (terminal).
+ *   - REJECTED — discarded by the user (terminal).
+ *   - STALE    — the document moved out from under the patch's anchor
+ *                before a decision was made; the user must re-propose or
+ *                discard. Set fail-fast by the accept endpoint when the
+ *                anchor no longer matches current content.
+ */
+export enum PendingPatchStatus {
+  PENDING = 'PENDING',
+  ACCEPTED = 'ACCEPTED',
+  REJECTED = 'REJECTED',
+  STALE = 'STALE',
+}

package/src/document-patch/lib/pending-patch.ts

@@ -0,0 +1,31 @@
+import { PatchOrigin, PendingPatchStatus } from './patch-enums';
+
+import type { LineRangeAnchor } from './patch-anchor';
+
+/**
+ * Wire shape of a single PendingPatch row as returned by the
+ * knowledge-base-api list/get endpoints and broadcast over the KB
+ * realtime SSE stream. Pure type — no runtime validation needed because
+ * the producer is trusted server code.
+ */
+export interface PendingPatchDto {
+  readonly id: string;
+  readonly pageId: string;
+  readonly proposalId: string;
+  readonly sequence: number;
+  readonly origin: PatchOrigin;
+  readonly sessionId: string | null;
+  readonly workflowJobRunId: string | null;
+  readonly baseVersion: number;
+  readonly anchor: LineRangeAnchor;
+  readonly before: string;
+  readonly after: string;
+  readonly label: string | null;
+  readonly rationale: string | null;
+  readonly status: PendingPatchStatus;
+  readonly decidedBy: string | null;
+  /** ISO-8601 timestamp; null until terminal. */
+  readonly decidedAt: string | null;
+  /** ISO-8601 timestamp. */
+  readonly createdAt: string;
+}

package/src/output/index.ts

@@ -0,0 +1,20 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/output-contracts — Layer 1 / Kernel
+//
+// Wire shapes for the run-detail Outputs panel and the per-kind renderer
+// registry. The legacy
+// JSON-dumping ArtifactContentViewer / OutputPreview pair are replaced by
+// a CLOSED-enum renderer registry. ESLint enforces that every OutputKind
+// value has a registered renderer (xema-fe/output-renderer-coverage).
+//
+// The user reviews deliverables on the canvas — they NEVER see raw JSON
+// unless they click "Show raw". Adding a new output kind is a deliberate
+// extension: enum value → contract type → renderer. No heuristic fallback.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/output-kind';
+export * from './lib/output-render-hint';
+export * from './lib/output-deliverable-expectation';
+export * from './lib/output-version-dto';
+export * from './lib/output-item-dto';
+export * from './lib/payload-schemas';

package/src/output/lib/output-deliverable-expectation.ts

@@ -0,0 +1,25 @@
+import { OutputKind } from './output-kind';
+
+/**
+ * What the workflow EXPECTED to produce at this slot, derived from the
+ * deliverable spec. Compared against {@link OutputItemDto} to detect
+ * missing or unexpected outputs in the Overview "Latest deliverables"
+ * strip.
+ *
+ * The engine emits one expectation per declared deliverable slot at
+ * dispatch time. A run with `produced.length < expectations.length`
+ * is incomplete; the FE renders missing slots as placeholder cards
+ * with the expectation summary.
+ */
+export interface OutputDeliverableExpectation {
+  readonly slug: string;
+  readonly displayName: string;
+  readonly expectedKind: OutputKind;
+  /** Phase that's responsible for producing this slot. */
+  readonly stageKey: string;
+  /**
+   * Whether this deliverable is required for the run to succeed. When
+   * `false`, the FE renders a missing slot in muted styling.
+   */
+  readonly required: boolean;
+}

package/src/output/lib/output-item-dto.ts

@@ -0,0 +1,54 @@
+import { OutputKind } from './output-kind';
+import { OutputRenderHint } from './output-render-hint';
+import { OutputVersionDto } from './output-version-dto';
+
+/**
+ * One card in the run-detail Outputs panel.
+ *
+ * The CARD is the deliverable while reviewing: the user reads the
+ * rendered content
+ * directly, not a JSON dump. `contentRef` points at the lazy-loaded
+ * payload the kind-specific renderer fetches; `summary` is the
+ * always-loaded one-line preview shown collapsed.
+ *
+ * `kbPublishedAt` is set when the artifact-store has linked this
+ * output to a `KB_PAGE` link refType. The FE renders an "Open in
+ * Knowledge Base" affordance when present.
+ */
+export interface OutputItemDto {
+  readonly id: string;
+  readonly kind: OutputKind;
+  readonly title: string;
+  /** One-line collapsed-state preview. Always rendered; never JSON. */
+  readonly summary: string;
+  /** Phase that produced this output. */
+  readonly stageKey: string;
+  readonly renderHint: OutputRenderHint;
+  /** Versions in descending order; first row is current. */
+  readonly versions: readonly OutputVersionDto[];
+  /** Lazy-load handle the renderer dereferences. Format is renderer-specific. */
+  readonly contentRef: OutputContentRef;
+  /** ISO-8601 when the latest version was emitted. */
+  readonly latestEmittedAt: string;
+  /** ISO-8601 when published to the KB; `null` when not yet (or never to be) published. */
+  readonly kbPublishedAt: string | null;
+  /** Direct deep-link to the KB page; `null` when not yet published. */
+  readonly kbPageUrl: string | null;
+}
+
+/**
+ * A renderer-agnostic handle the FE dereferences when the user expands
+ * a card. Renderers narrow on `kind` to know which flavor of resolver
+ * to invoke — there are exactly two flavors:
+ *
+ * - INLINE — the payload is small enough to ship in the list response
+ *   and is already inlined (`payload`). Renderer reads directly.
+ * - REMOTE — the payload requires a separate fetch (`url`). Renderer
+ *   queries `useOutputContent({ url })`.
+ *
+ * Producers MUST pick one. Renderers MUST handle both (the registry
+ * provides this glue once per kind, not per renderer).
+ */
+export type OutputContentRef =
+  | { readonly kind: 'inline'; readonly payload: unknown }
+  | { readonly kind: 'remote'; readonly url: string; readonly contentType: string };