@gate-forge/pack-playwright 0.1.0

package/dist/supervisor/spool.js

@@ -0,0 +1,263 @@
+/**
+ * The runner-side lifecycle SPOOL (enforcement-review fix 3): the
+ * untrusted runner child cannot call the witness's supervisor surface,
+ * so the gateforge reporter instead writes test lifecycle events
+ * (testBegin / testEnd with the observed outcome) as NUL-safe JSON lines
+ * into the run-state spool. The TRUSTED CLI drains this spool while the
+ * suite runs and performs the witness's supervisor calls (session
+ * open/close) with credentials (run token + verifier key) that exist
+ * ONLY in the CLI process. The spool file itself carries no secrets —
+ * test identities and outcomes only.
+ *
+ * Protocol: one JSON object per line, canonical JSON (control characters
+ * — NUL included — are escaped, so the format is NUL-safe), terminated
+ * by '\n'. Consumers only treat a line as complete once its '\n' has
+ * been written, which makes partial writes impossible to misparse.
+ */
+import { mkdirSync, openSync, closeSync, writeSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { canonicalOf } from '../json.js';
+import { SPOOL_DIR_NAME, SPOOL_EVENTS_FILE, SPOOL_INTENTS_FILE } from '../constants.js';
+/**
+ * Resolves the spool events file for one run.
+ *
+ * Args:
+ *   stateDir: absolute run-state directory.
+ *   runId: the run identity both sides agree on (env-carried).
+ *
+ * Returns:
+ *   string: absolute `<stateDir>/spool/<runId>/events.jsonl` path.
+ */
+export function spoolPathFor(stateDir, runId) {
+    return join(stateDir, SPOOL_DIR_NAME, runId, SPOOL_EVENTS_FILE);
+}
+/**
+ * Appends one lifecycle event to the run's spool (runner-side; the
+ * reporter calls this). The event is sanitized: string fields are
+ * coerced/validated, unknown statuses ride as strings, and canonical
+ * JSON escapes every control character (NUL included) — the line is
+ * NUL-safe by construction. A failed append never crashes the run: the
+ * CLI drain then simply never opens that session and the witness
+ * rejects the suite's submissions fail-closed.
+ *
+ * Args:
+ *   spoolFile: absolute spool events file (see {@link spoolPathFor}).
+ *   event: the lifecycle event to append.
+ */
+export function appendSpoolEvent(spoolFile, event) {
+    try {
+        const clean = {
+            kind: event.kind,
+            testId: String(event.testId),
+            workerIndex: Number.isInteger(event.workerIndex) && event.workerIndex >= 0 ? event.workerIndex : 0,
+            file: typeof event.file === 'string' ? event.file : null,
+            titlePath: Array.isArray(event.titlePath) ? event.titlePath.map((part) => String(part)) : [],
+            project: typeof event.project === 'string' ? event.project : null,
+            ...(event.kind === 'testEnd'
+                ? {
+                    // Omitted (never null) when the runner reported no string
+                    // outcome: `undefined` reads as "outcome unknown" end to end,
+                    // and the drain seals the session WITHOUT an outcome — which
+                    // the trace grades not-passed.
+                    ...(typeof event.outcome === 'string' ? { outcome: event.outcome } : {}),
+                    attempt: Number.isInteger(event.attempt) && event.attempt >= 1 ? event.attempt : 1,
+                }
+                : {}),
+            ...(Array.isArray(event.claims) && event.claims.length > 0
+                ? { claims: event.claims.map((claim) => String(claim)) }
+                : {}),
+        };
+        mkdirSync(join(spoolFile, '..'), { recursive: true });
+        const line = `${canonicalOf(clean)}\n`;
+        const fd = openSync(spoolFile, 'a');
+        try {
+            writeSync(fd, line, undefined, 'utf8');
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch (error) {
+        console.warn(`[gateforge] cannot append to the lifecycle spool: ${error.message}`);
+    }
+}
+/**
+ * Reads every COMPLETE spool line past the given byte offset (CLI-side
+ * drain). A trailing fragment without its terminating newline is left
+ * for the next poll — partial writes are never parsed.
+ *
+ * Args:
+ *   spoolFile: absolute spool events file.
+ *   offset: byte offset to read from (0 = from the start).
+ *
+ * Returns:
+ *   {events, nextOffset}: parsed events in file order and the offset to
+ *   resume from (equal to `offset` when nothing complete was added).
+ */
+export function readSpoolEvents(spoolFile, offset) {
+    let size;
+    try {
+        size = statSync(spoolFile).size;
+    }
+    catch {
+        return { events: [], nextOffset: offset };
+    }
+    if (size <= offset)
+        return { events: [], nextOffset: offset };
+    let raw;
+    try {
+        raw = readFileSync(spoolFile, 'utf8');
+    }
+    catch {
+        return { events: [], nextOffset: offset };
+    }
+    // Byte offsets are only tracked for complete lines; converting the
+    // whole file each poll is bounded by the spool's lifetime size.
+    const events = [];
+    let consumed = 0;
+    const lines = raw.split('\n');
+    for (const line of lines) {
+        const lineBytes = Buffer.byteLength(line, 'utf8') + 1; // + '\n'
+        const start = consumed;
+        consumed += lineBytes;
+        if (start < offset)
+            continue;
+        if (line.trim().length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue; // never crash the drain on a corrupt line
+        }
+        if (typeof parsed !== 'object' || parsed === null)
+            continue;
+        const row = parsed;
+        if (typeof row['kind'] !== 'string' || typeof row['testId'] !== 'string')
+            continue;
+        events.push(parsed);
+    }
+    const trailing = lines[lines.length - 1] ?? '';
+    const completeBytes = raw.endsWith('\n') ? size : size - Buffer.byteLength(trailing, 'utf8');
+    return { events, nextOffset: Math.max(offset, completeBytes) };
+}
+/** Resolves the intents spool file for one run (`<stateDir>/spool/<runId>/persistence-intents.jsonl`). */
+export function persistenceIntentsPathFor(stateDir, runId) {
+    return join(stateDir, SPOOL_DIR_NAME, runId, SPOOL_INTENTS_FILE);
+}
+/**
+ * Appends one persistence intent to the run's intents spool (test-side
+ * helper; the CONTRACT is the JSONL line, this writer only keeps it
+ * canonical and NUL-safe). A failed append never crashes the test: the
+ * drain then simply never forwards the intent and the claim grades
+ * fail-closed without its witnessed record.
+ *
+ * Args:
+ *   intentsFile: absolute intents spool file (see {@link persistenceIntentsPathFor}).
+ *   intent: the claim intent to append.
+ */
+export function appendPersistenceIntent(intentsFile, intent) {
+    try {
+        const clean = {
+            entity: String(intent.entity),
+            operation: intent.operation,
+            phase: intent.phase,
+            intent: intent.intent,
+            key: intent.key,
+            claimId: String(intent.claimId),
+            testId: String(intent.testId),
+            sequence: Number.isInteger(intent.sequence) && intent.sequence >= 1 ? intent.sequence : 1,
+        };
+        mkdirSync(join(intentsFile, '..'), { recursive: true });
+        const line = `${canonicalOf(clean)}\n`;
+        const fd = openSync(intentsFile, 'a');
+        try {
+            writeSync(fd, line, undefined, 'utf8');
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch (error) {
+        console.warn(`[gateforge] cannot append to the persistence-intents spool: ${error.message}`);
+    }
+}
+/** Minimal structural validation for one drained intent line. */
+function isPersistenceIntent(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const row = value;
+    return (typeof row['entity'] === 'string' &&
+        (row['operation'] === 'create' ||
+            row['operation'] === 'read' ||
+            row['operation'] === 'update' ||
+            row['operation'] === 'delete') &&
+        (row['phase'] === 'pre' || row['phase'] === 'post') &&
+        (row['intent'] === 'expect-present' || row['intent'] === 'expect-absent') &&
+        (typeof row['key'] === 'string' ||
+            typeof row['key'] === 'number' ||
+            typeof row['key'] === 'boolean' ||
+            (typeof row['key'] === 'object' && row['key'] !== null && !Array.isArray(row['key']))) &&
+        typeof row['claimId'] === 'string' &&
+        typeof row['testId'] === 'string' &&
+        typeof row['sequence'] === 'number' &&
+        Number.isInteger(row['sequence']));
+}
+/**
+ * Reads every COMPLETE intent line past the given byte offset (CLI-side
+ * drain). Trailing fragments without their newline are left for the next
+ * poll; structurally invalid lines are skipped (the claim simply never
+ * resolves — fail closed, never crash the drain).
+ *
+ * Args:
+ *   intentsFile: absolute intents spool file.
+ *   offset: byte offset to read from (0 = from the start).
+ *
+ * Returns:
+ *   {intents, nextOffset}: parsed intents in file order and the offset to
+ *   resume from.
+ */
+export function readPersistenceIntents(intentsFile, offset) {
+    let size;
+    try {
+        size = statSync(intentsFile).size;
+    }
+    catch {
+        return { intents: [], nextOffset: offset };
+    }
+    if (size <= offset)
+        return { intents: [], nextOffset: offset };
+    let raw;
+    try {
+        raw = readFileSync(intentsFile, 'utf8');
+    }
+    catch {
+        return { intents: [], nextOffset: offset };
+    }
+    const intents = [];
+    let consumed = 0;
+    const lines = raw.split('\n');
+    for (const line of lines) {
+        const lineBytes = Buffer.byteLength(line, 'utf8') + 1; // + '\n'
+        const start = consumed;
+        consumed += lineBytes;
+        if (start < offset)
+            continue;
+        if (line.trim().length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue; // never crash the drain on a corrupt line
+        }
+        if (isPersistenceIntent(parsed))
+            intents.push(parsed);
+    }
+    const trailing = lines[lines.length - 1] ?? '';
+    const completeBytes = raw.endsWith('\n') ? size : size - Buffer.byteLength(trailing, 'utf8');
+    return { intents, nextOffset: Math.max(offset, completeBytes) };
+}
+//# sourceMappingURL=spool.js.map

package/dist/supervisor/spool.js.map

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

package/dist/surface.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The consumer-declared surface descriptor (plan Phase 1 item 7): the
+ * APPLICATION-SPECIFIC half of evidence — how the rendered UI is
+ * observed and driven (list page, rows and field cells, form templates,
+ * archive control, status values). The pack ships selectors for NO
+ * application; the consumer declares its own.
+ *
+ * OWNERSHIP: the descriptor's selectors are LOCATORS, never proof. The
+ * engine-owned browser (witness `browser.ts`) drives the rendered app
+ * with them and verifies navigation, the application request, the
+ * visible outcome, and persistence itself — a lying descriptor fails
+ * closed (elements never match) instead of manufacturing proof.
+ */
+/**
+ * The surface-descriptor contract version this pack speaks. Consumers
+ * must declare `schemaVersion: SURFACE_DESCRIPTOR_VERSION` in their
+ * descriptor; a different version fails closed with a precise error
+ * instead of silently misreading selectors.
+ */
+export declare const SURFACE_DESCRIPTOR_VERSION = 1;
+/** How the rendered LIST page is observed (rows and their cells). */
+export interface SurfaceList {
+    /** List page path relative to the app base (e.g. `/`). */
+    path: string;
+    /** Selector proving the list page rendered (e.g. the page heading). */
+    readySelector: string;
+    /** Selector matching one entity row inside the list. */
+    rowSelector: string;
+    /** Index of the row cell carrying the entity id (0-based). */
+    idCellIndex: number;
+    /** Field name → 0-based row-cell index, for reading rendered fields. */
+    fieldCellIndexes: Record<string, number>;
+}
+/** How the CREATE form is driven. */
+export interface SurfaceCreate {
+    /** Create-form page path relative to the app base. */
+    formPath: string;
+    /** Selector proving the create form rendered. */
+    formReadySelector: string;
+    /** Field name → input selector on the create form. */
+    fields: Record<string, string>;
+    /** Submit control selector on the create form. */
+    submitSelector: string;
+}
+/**
+ * How the EDIT form is reached and driven. `{id}` templates are
+ * substituted with the entity id; the edit link is located INSIDE the
+ * entity's row.
+ */
+export interface SurfaceEdit {
+    /** Row-scoped selector of the control navigating to the edit form. */
+    linkSelector: string;
+    /** `{id}`-templated selector proving the edit form rendered. */
+    formReadySelectorTemplate: string;
+    /** Field name → input selector on the edit form. */
+    fields: Record<string, string>;
+    /** `{id}`-templated page-scoped selector of the edit SAVE control. */
+    saveSelectorTemplate: string;
+}
+/** How the archive/delete control is located (row-scoped, `{id}`-templated). */
+export interface SurfaceArchive {
+    /** `{id}`-templated row-scoped selector of the archive/delete control. */
+    controlSelectorTemplate: string;
+}
+/**
+ * Rendered-status observations the primitives assert after create and
+ * archive (fail-closed visible postconditions).
+ */
+export interface SurfaceStatus {
+    /** Field name the status renders under (must be a row field). */
+    field: string;
+    /** Expected rendered value right after a create (e.g. `'active'`). */
+    createdValue?: string;
+    /** Expected rendered value after archive (e.g. `'archived'`). */
+    archivedValue?: string;
+}
+/**
+ * The declarative, consumer-owned description of the application
+ * surface the evidence primitives observe (plan Phase 1 item 7): the
+ * pack ships selectors for NO application — the consumer declares its
+ * own. Selector/path strings containing `{id}` are substituted with the
+ * entity id before use.
+ */
+export interface SurfaceDescriptor {
+    /** Must equal {@link SURFACE_DESCRIPTOR_VERSION} (fail-closed otherwise). */
+    schemaVersion: number;
+    list: SurfaceList;
+    create: SurfaceCreate;
+    edit: SurfaceEdit;
+    archive: SurfaceArchive;
+    status: SurfaceStatus;
+    /**
+     * Where the browser lands after a successful mutation (the rendered
+     * result page); `path` is the expected `location.pathname`.
+     */
+    afterAction: {
+        path: string;
+    };
+    /**
+     * Fields recorded on a delete/archive `ui.action` record (the
+     * owner-declared archived state the journey drove, e.g.
+     * `{status: 'archived'}`).
+     */
+    deleteFields: Record<string, string>;
+}
+/**
+ * Substitutes `{id}` in a consumer-declared selector/path template with
+ * the entity id. Fail closed on ids that could break selector context
+ * (quotes/control characters) — a malformed id must error here, not
+ * silently match a different element.
+ */
+export declare function renderSurfaceTemplate(template: string, entityId: string): string;
+/**
+ * Structural validation of the consumer-declared surface descriptor
+ * (fail closed with the EXACT missing piece — a misdeclared surface must
+ * never surface later as a confusing selector timeout).
+ *
+ * Args:
+ *   surface: the candidate descriptor.
+ *
+ * Returns:
+ *   SurfaceDescriptor: the same descriptor, validated.
+ *
+ * Throws:
+ *   Error: naming the first structural problem found.
+ */
+export declare function validateSurface(surface: SurfaceDescriptor): SurfaceDescriptor;
+/**
+ * Fills descriptor input fields exactly: every declared key must be a
+ * selector-known field with a string value (fail closed — the engine
+ * never invents form fields the consumer did not declare).
+ */
+export declare function declaredSurfaceFields(where: string, input: Record<string, string>, known: Record<string, string>): Record<string, string>;
+//# sourceMappingURL=surface.d.ts.map

package/dist/surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../src/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,aAAa,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,kDAAkD;IAClD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,yBAAyB,EAAE,MAAM,CAAC;IAClC,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,sEAAsE;IACtE,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC;IACtB;;;OAGG;IACH,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQhF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,iBAAiB,CAuE7E;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBxB"}

package/dist/surface.js

@@ -0,0 +1,139 @@
+/**
+ * The consumer-declared surface descriptor (plan Phase 1 item 7): the
+ * APPLICATION-SPECIFIC half of evidence — how the rendered UI is
+ * observed and driven (list page, rows and field cells, form templates,
+ * archive control, status values). The pack ships selectors for NO
+ * application; the consumer declares its own.
+ *
+ * OWNERSHIP: the descriptor's selectors are LOCATORS, never proof. The
+ * engine-owned browser (witness `browser.ts`) drives the rendered app
+ * with them and verifies navigation, the application request, the
+ * visible outcome, and persistence itself — a lying descriptor fails
+ * closed (elements never match) instead of manufacturing proof.
+ */
+/**
+ * The surface-descriptor contract version this pack speaks. Consumers
+ * must declare `schemaVersion: SURFACE_DESCRIPTOR_VERSION` in their
+ * descriptor; a different version fails closed with a precise error
+ * instead of silently misreading selectors.
+ */
+export const SURFACE_DESCRIPTOR_VERSION = 1;
+/**
+ * Substitutes `{id}` in a consumer-declared selector/path template with
+ * the entity id. Fail closed on ids that could break selector context
+ * (quotes/control characters) — a malformed id must error here, not
+ * silently match a different element.
+ */
+export function renderSurfaceTemplate(template, entityId) {
+    if (/['"\r\n\\]/.test(entityId)) {
+        throw new Error(`surface template '${template}' cannot be rendered for entity id ${JSON.stringify(entityId)}: ` +
+            'ids carrying quotes or control characters are rejected fail-closed');
+    }
+    return template.replaceAll('{id}', entityId);
+}
+/**
+ * Structural validation of the consumer-declared surface descriptor
+ * (fail closed with the EXACT missing piece — a misdeclared surface must
+ * never surface later as a confusing selector timeout).
+ *
+ * Args:
+ *   surface: the candidate descriptor.
+ *
+ * Returns:
+ *   SurfaceDescriptor: the same descriptor, validated.
+ *
+ * Throws:
+ *   Error: naming the first structural problem found.
+ */
+export function validateSurface(surface) {
+    const requireSelectorMap = (where, map) => {
+        if (typeof map !== 'object' || map === null || Array.isArray(map)) {
+            throw new Error(`surface.${where} must be a record of field name → selector`);
+        }
+        for (const [field, selector] of Object.entries(map)) {
+            if (typeof selector !== 'string' || selector.length === 0) {
+                throw new Error(`surface.${where}.${field} must be a non-empty selector string`);
+            }
+        }
+    };
+    const requireIndexMap = (where, map) => {
+        if (typeof map !== 'object' || map === null || Array.isArray(map)) {
+            throw new Error(`surface.${where} must be a record of field name → cell index`);
+        }
+        for (const [field, index] of Object.entries(map)) {
+            if (!Number.isInteger(index) || index < 0) {
+                throw new Error(`surface.${where}.${field} must be a non-negative integer cell index`);
+            }
+        }
+    };
+    if (typeof surface !== 'object' || surface === null || Array.isArray(surface)) {
+        throw new Error('surface must be a SurfaceDescriptor object declared by the consumer');
+    }
+    if (surface.schemaVersion !== SURFACE_DESCRIPTOR_VERSION) {
+        throw new Error(`surface.schemaVersion ${String(surface.schemaVersion)} is not supported: this pack speaks ` +
+            `surface-descriptor version ${String(SURFACE_DESCRIPTOR_VERSION)} — redeclare the surface ` +
+            'against the current version');
+    }
+    for (const section of ['list', 'create', 'edit', 'archive', 'status', 'afterAction']) {
+        if (typeof surface[section] !== 'object' || surface[section] === null) {
+            throw new Error(`surface.${section} is required by the surface descriptor`);
+        }
+    }
+    for (const key of ['path', 'readySelector', 'rowSelector']) {
+        if (typeof surface.list[key] !== 'string' || surface.list[key].length === 0) {
+            throw new Error(`surface.list.${key} must be a non-empty string`);
+        }
+    }
+    if (!Number.isInteger(surface.list.idCellIndex) || surface.list.idCellIndex < 0) {
+        throw new Error('surface.list.idCellIndex must be a non-negative integer');
+    }
+    requireIndexMap('list.fieldCellIndexes', surface.list.fieldCellIndexes);
+    for (const key of ['formPath', 'formReadySelector', 'submitSelector']) {
+        if (typeof surface.create[key] !== 'string' || surface.create[key].length === 0) {
+            throw new Error(`surface.create.${key} must be a non-empty string`);
+        }
+    }
+    requireSelectorMap('create.fields', surface.create.fields);
+    for (const key of ['linkSelector', 'formReadySelectorTemplate', 'saveSelectorTemplate']) {
+        if (typeof surface.edit[key] !== 'string' || surface.edit[key].length === 0) {
+            throw new Error(`surface.edit.${key} must be a non-empty string`);
+        }
+    }
+    requireSelectorMap('edit.fields', surface.edit.fields);
+    if (typeof surface.archive.controlSelectorTemplate !== 'string' ||
+        surface.archive.controlSelectorTemplate.length === 0) {
+        throw new Error('surface.archive.controlSelectorTemplate must be a non-empty string');
+    }
+    if (typeof surface.status.field !== 'string' || surface.status.field.length === 0) {
+        throw new Error('surface.status.field must be a non-empty field name');
+    }
+    if (typeof surface.afterAction.path !== 'string' || surface.afterAction.path.length === 0) {
+        throw new Error('surface.afterAction.path must be a non-empty path string');
+    }
+    requireSelectorMap('deleteFields', surface.deleteFields);
+    return surface;
+}
+/**
+ * Fills descriptor input fields exactly: every declared key must be a
+ * selector-known field with a string value (fail closed — the engine
+ * never invents form fields the consumer did not declare).
+ */
+export function declaredSurfaceFields(where, input, known) {
+    const entries = Object.entries(input ?? {});
+    if (entries.length === 0) {
+        throw new Error(`${where} requires at least one input field the journey enters in the UI`);
+    }
+    const declared = {};
+    for (const [field, value] of entries) {
+        if (!(field in known)) {
+            throw new Error(`${where} declares field '${field}' which the consumer's surface descriptor does not ` +
+                `declare a selector for (declared fields: ${Object.keys(known).sort().join(', ')})`);
+        }
+        if (typeof value !== 'string') {
+            throw new Error(`${where}.${field} must be a string (form inputs are text)`);
+        }
+        declared[field] = value;
+    }
+    return declared;
+}
+//# sourceMappingURL=surface.js.map

package/dist/surface.js.map

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

package/dist/witness/adapter-registry.d.ts

@@ -0,0 +1,38 @@
+import type { AdapterContext, EvidenceAdapter } from './types.js';
+/**
+ * Loads every `.mjs` adapter in `dir` into a frozen registry.
+ *
+ * Args:
+ *   dir: the configured adapters directory (absolute).
+ *
+ * Returns:
+ *   Map<string, EvidenceAdapter>: keyed by the file basename sans `.mjs`.
+ *
+ * Throws:
+ *   AdapterRegistryError: fail-closed load problems — unreadable dir,
+ *     unimportable module, or a module missing any contract member.
+ */
+export declare function loadAdapters(dir: string): Promise<Map<string, EvidenceAdapter>>;
+/**
+ * Validates one adapter module against the pin-#8 contract.
+ *
+ * Args:
+ *   module: the default export of the adapter file.
+ *   name: adapter name, used in diagnostics.
+ *
+ * Returns:
+ *   EvidenceAdapter: the validated adapter.
+ *
+ * Throws:
+ *   AdapterRegistryError: when any required member is missing or shaped
+ *   wrong. Optional `baseUrl` (a string) overrides the witness's
+ *   configured adapter base for this adapter.
+ */
+export declare function validateAdapter(module: unknown, name: string): EvidenceAdapter;
+/** Fail-closed adapter-loading error (witness startup aborts). */
+export declare class AdapterRegistryError extends Error {
+    constructor(message: string);
+}
+/** The transport the witness hands to adapter `read` calls (GET-only). */
+export declare function makeAdapterContext(baseUrl: string, resourceId: string, get: AdapterContext['get'], headers?: Record<string, string>): AdapterContext;
+//# sourceMappingURL=adapter-registry.d.ts.map

package/dist/witness/adapter-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-registry.d.ts","sourceRoot":"","sources":["../../src/witness/adapter-registry.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElE;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CA6BrF;AAqBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,CAkD9E;AAED,kEAAkE;AAClE,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,EAC1B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,cAAc,CAEhB"}