@gate-forge/witness 0.0.0-stage → 0.8.0

package/dist/surface.d.ts

@@ -0,0 +1,211 @@
+/**
+ * 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 current surface-descriptor version. Version 3 adds constrained
+ * locator-based list fields; earlier cell-index descriptors stay valid.
+ */
+export declare const SURFACE_DESCRIPTOR_VERSION = 3;
+/** Legacy surface-descriptor version (single-form create only). */
+export declare const SURFACE_DESCRIPTOR_VERSION_1 = 1;
+/** Surface-descriptor version with optional wizard create steps. */
+export declare const SURFACE_DESCRIPTOR_VERSION_2 = 2;
+/** Shared list-page and row selectors. */
+interface SurfaceListBase {
+    /** 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;
+}
+/** How v1/v2 list rows expose ids and fields in table cells. */
+export interface SurfaceListCells extends SurfaceListBase {
+    /** 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>;
+    idLocator?: never;
+    fieldLocators?: never;
+}
+/** How a v3 list row exposes ids and fields through relative locators. */
+export interface SurfaceListLocators extends SurfaceListBase {
+    /** Locator evaluated inside one matched row to read its entity id. */
+    idLocator: string;
+    /** Field name → locator evaluated inside the matched row. */
+    fieldLocators: Record<string, string>;
+    idCellIndex?: never;
+    fieldCellIndexes?: never;
+}
+/** List shape selected by the surface descriptor version. */
+export type SurfaceList = SurfaceListCells | SurfaceListLocators;
+/** How the CREATE form is driven (legacy single form, v1 + v2). */
+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;
+}
+/**
+ * One engine-driven wizard step (surface v2, Phase 3): the closed
+ * operation set the engine can perform while walking a multi-screen
+ * create flow (draft orb → type picker → radios → searchable lists →
+ * submit). Steps are LOCATORS plus field references — never proof: a
+ * lying step fails closed (elements never match) exactly like a lying
+ * legacy selector. Custom searchable dropdowns, drag-and-drop, file
+ * pickers, and hover menus are NOT expressible — those flows stay on
+ * the Observe channel (documented limitation, never silently widened).
+ */
+export type SurfaceStep = 
+/** Navigate to an app-relative path. */
+{
+    goto: string;
+}
+/** Click a selector. */
+ | {
+    click: string;
+}
+/**
+ * Fill an input: `field` references a test-input field name (the
+ * engine types the journey's value for it); `value` is a literal the
+ * map declares. Exactly one of the two.
+ */
+ | {
+    fill: {
+        selector: string;
+        field?: string;
+        value?: string;
+    };
+}
+/** Check a radio/checkbox. */
+ | {
+    check: string;
+}
+/** Press a dismiss/confirm key (dialogs that close on Escape/Enter). */
+ | {
+    press: 'Escape' | 'Enter';
+}
+/** Wait for a selector (async panels, search results). */
+ | {
+    waitFor: string;
+};
+/**
+ * Wizard-driven CREATE (surface v2): `steps` replace the legacy
+ * single-form trio (`formPath`/`formReadySelector`/`submitSelector`
+ * must be ABSENT — a mixed descriptor is refused fail-closed, never
+ * driven half-legacy). `fields` stays REQUIRED: it declares the input
+ * vocabulary the test provides and the echo grades.
+ */
+export interface SurfaceCreateSteps {
+    /** Declared input vocabulary (echo source; selectors live in steps). */
+    fields: Record<string, string>;
+    /** The wizard walk, in order. Non-empty. */
+    steps: SurfaceStep[];
+}
+/** How CREATE is driven: one legacy form (v1 + v2) or a wizard walk (v2 only). */
+export type SurfaceCreateFlow = SurfaceCreate | SurfaceCreateSteps;
+/**
+ * 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 {
+    /** Version 3 adds relative list locators; cell indexes remain compatible. */
+    schemaVersion: number;
+    list: SurfaceList;
+    create: SurfaceCreateFlow;
+    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>;
+export {};
+//# 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":"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"}

package/dist/surface.js

@@ -0,0 +1,268 @@
+/**
+ * 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 current surface-descriptor version. Version 3 adds constrained
+ * locator-based list fields; earlier cell-index descriptors stay valid.
+ */
+export const SURFACE_DESCRIPTOR_VERSION = 3;
+/** Legacy surface-descriptor version (single-form create only). */
+export const SURFACE_DESCRIPTOR_VERSION_1 = 1;
+/** Surface-descriptor version with optional wizard create steps. */
+export const SURFACE_DESCRIPTOR_VERSION_2 = 2;
+/**
+ * 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) {
+    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_1 &&
+        surface.schemaVersion !== SURFACE_DESCRIPTOR_VERSION_2 &&
+        surface.schemaVersion !== SURFACE_DESCRIPTOR_VERSION) {
+        throw new Error(`surface.schemaVersion ${String(surface.schemaVersion)} is not supported: this pack speaks ` +
+            `surface-descriptor versions ${String(SURFACE_DESCRIPTOR_VERSION_1)} (legacy single-form ` +
+            `create), ${String(SURFACE_DESCRIPTOR_VERSION_2)} (wizard steps), and ` +
+            `${String(SURFACE_DESCRIPTOR_VERSION)} (relative list locators) — redeclare ` +
+            'the surface against a 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 (surface.schemaVersion === SURFACE_DESCRIPTOR_VERSION) {
+        const hasRelativeLocators = 'idLocator' in surface.list || 'fieldLocators' in surface.list;
+        if (hasRelativeLocators) {
+            const locatorList = surface.list;
+            if (typeof locatorList.idLocator !== 'string' || locatorList.idLocator.length === 0) {
+                throw new Error('surface.list.idLocator must be a non-empty locator relative to the row');
+            }
+            requireSelectorMap('list.fieldLocators', locatorList.fieldLocators);
+            if ('idCellIndex' in surface.list || 'fieldCellIndexes' in surface.list) {
+                throw new Error('surface v3 list must not mix relative locators and cell indexes');
+            }
+        }
+        else {
+            // A v3 descriptor may keep an existing table-index map unchanged.
+            const cellList = surface.list;
+            if (!Number.isInteger(cellList.idCellIndex) || cellList.idCellIndex < 0) {
+                throw new Error('surface.list.idLocator or a non-negative idCellIndex is required');
+            }
+            requireIndexMap('list.fieldCellIndexes', cellList.fieldCellIndexes);
+        }
+    }
+    else {
+        const cellList = surface.list;
+        if (!Number.isInteger(cellList.idCellIndex) || cellList.idCellIndex < 0) {
+            throw new Error('surface.list.idCellIndex must be a non-negative integer');
+        }
+        requireIndexMap('list.fieldCellIndexes', cellList.fieldCellIndexes);
+        if ('idLocator' in surface.list || 'fieldLocators' in surface.list) {
+            throw new Error('surface v1/v2 list must use cell indexes, not v3 relative locators');
+        }
+    }
+    validateCreateFlow(surface.schemaVersion, surface.create);
+    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;
+}
+/**
+ * Requires a field name → selector record (module-level: shared by the
+ * descriptor validator and the create-flow validator).
+ */
+function 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`);
+        }
+    }
+}
+/**
+ * Requires a field name → cell index record (module-level: shared by
+ * the descriptor validator and the create-flow validator).
+ */
+function 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`);
+        }
+    }
+}
+/**
+ * Validates the create flow: legacy single-form trio, or a wizard step
+ * walk in versions 2 and 3. Mixed shapes fail closed.
+ */
+function validateCreateFlow(schemaVersion, create) {
+    if (typeof create !== 'object' || create === null || Array.isArray(create)) {
+        throw new Error('surface.create must be an object (legacy form or v2 steps)');
+    }
+    const record = create;
+    if ('steps' in record) {
+        if (schemaVersion !== SURFACE_DESCRIPTOR_VERSION_2 && schemaVersion !== SURFACE_DESCRIPTOR_VERSION) {
+            throw new Error('surface.create.steps requires surface-descriptor version ' +
+                `${String(SURFACE_DESCRIPTOR_VERSION_2)} or ${String(SURFACE_DESCRIPTOR_VERSION)} ` +
+                `(declared ${String(schemaVersion)})`);
+        }
+        for (const legacy of ['formPath', 'formReadySelector', 'submitSelector']) {
+            if (record[legacy] !== undefined) {
+                throw new Error(`surface.create mixes wizard steps with legacy '${legacy}' — declare steps or the ` +
+                    'single form, never both');
+            }
+        }
+        requireSelectorMap('create.fields', create.fields);
+        validateSteps(create.steps, create.fields);
+        return;
+    }
+    for (const key of ['formPath', 'formReadySelector', 'submitSelector']) {
+        if (typeof create[key] !== 'string' || create[key].length === 0) {
+            throw new Error(`surface.create.${key} must be a non-empty string`);
+        }
+    }
+    requireSelectorMap('create.fields', create.fields);
+}
+/**
+ * Validates one wizard step walk: non-empty, closed operation set,
+ * non-empty selectors/paths, fills carrying exactly one of
+ * field/value with the field in the declared vocabulary.
+ */
+function validateSteps(steps, fields) {
+    if (!Array.isArray(steps) || steps.length === 0) {
+        throw new Error('surface.create.steps must be a non-empty array of wizard steps');
+    }
+    steps.forEach((step, index) => {
+        const where = `surface.create.steps[${String(index)}]`;
+        if (typeof step !== 'object' || step === null || Array.isArray(step)) {
+            throw new Error(`${where} must be a single-operation step object`);
+        }
+        const keys = Object.keys(step);
+        if (keys.length !== 1) {
+            throw new Error(`${where} must carry exactly one operation (goto/click/fill/check/press/waitFor)`);
+        }
+        const operation = keys[0];
+        const value = step[operation];
+        switch (operation) {
+            case 'goto':
+            case 'click':
+            case 'check':
+            case 'waitFor':
+                if (typeof value !== 'string' || value.length === 0) {
+                    throw new Error(`${where}.${operation} must be a non-empty string`);
+                }
+                if (operation === 'goto' && !value.startsWith('/')) {
+                    throw new Error(`${where}.goto must be an app-relative path starting with '/'`);
+                }
+                break;
+            case 'press':
+                if (value !== 'Escape' && value !== 'Enter') {
+                    throw new Error(`${where}.press must be 'Escape' or 'Enter'`);
+                }
+                break;
+            case 'fill': {
+                if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+                    throw new Error(`${where}.fill must be {selector, field?/value?}`);
+                }
+                const fill = value;
+                if (typeof fill['selector'] !== 'string' || fill['selector'].length === 0) {
+                    throw new Error(`${where}.fill.selector must be a non-empty string`);
+                }
+                const hasField = typeof fill['field'] === 'string' && fill['field'].length > 0;
+                const hasValue = typeof fill['value'] === 'string';
+                if (hasField === hasValue) {
+                    throw new Error(`${where}.fill needs exactly one of field/value (a test-input reference or a map literal)`);
+                }
+                if (hasField && !Object.prototype.hasOwnProperty.call(fields, fill['field'])) {
+                    throw new Error(`${where}.fill.field '${fill['field']}' is not in the declared create.fields ` +
+                        `vocabulary (${Object.keys(fields).sort().join(', ') || '<none>'})`);
+                }
+                break;
+            }
+            default:
+                throw new Error(`${where} carries unknown operation '${String(operation)}' (allowed: goto/click/fill/check/press/waitFor)`);
+        }
+    });
+}
+/**
+ * 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,92 @@
+import type { AdapterContext, EvidenceAdapter, SessionIdentity } 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`, `identity`, and `fields` refine read and
+ *   create-proof capabilities without changing adapters that omit them.
+ */
+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);
+}
+/**
+ * Validates one adapter's optional `observe` binding (Observe channel,
+ * Phase 2): a plain object with per-operation `{method, path}`
+ * entries. Method must be a concrete uppercase verb; path must be an
+ * absolute backend-facing path whose only template segment is `{id}` —
+ * required on read/update/delete (the entity-id carrier), forbidden on
+ * create (create ids come from the adapter list-diff, never from a
+ * path guess).
+ *
+ * Args:
+ *   value: the adapter's `observe` export.
+ *
+ * Returns:
+ *   string | null: the contract-violation description, or null when valid.
+ */
+export declare function validateObserveBinding(value: unknown): string | null;
+/**
+ * Validates one operation's optional `collection` declaration: the
+ * response shape whose ROWS name the entities an observe read credits.
+ * A collection read must be a `read` over `GET` on a path that carries
+ * no `{id}` template (the by-id reader owns that), and must declare the
+ * row `idKey`; `rowsKey` is optional and its absence declares that the
+ * response root is the row array. Every failure is a load-time
+ * contract violation — an adapter can never quietly fall back to
+ * inferring a collection from an arbitrary response body.
+ *
+ * Args:
+ *   value: the operation entry's `collection` export.
+ *   operation: the observe operation the declaration sits on.
+ *   method: the operation's already-validated HTTP method.
+ *   path: the operation's already-validated path template.
+ *
+ * Returns:
+ *   string | null: the contract-violation description, or null when valid.
+ */
+export declare function validateObserveCollection(value: unknown, operation: string, method: string, path: string): string | null;
+/**
+ * The transport the witness hands to adapter `read` calls (GET-only).
+ *
+ * Args:
+ *   baseUrl: the resolved read base.
+ *   resourceId: the resource this adapter serves.
+ *   get: the mediated GET primitive.
+ *   headers: engine-side read headers, when the run issues one.
+ *   session: the test session the read belongs to and the identity THAT
+ *     session registered (plan Phase 4b item 3b). Omitted for
+ *     engine-driven, probe and supervisor reads — those are not a test
+ *     session's read and must never inherit one.
+ *
+ * Returns:
+ *   AdapterContext: the frozen read context.
+ */
+export declare function makeAdapterContext(baseUrl: string, resourceId: string, get: AdapterContext['get'], headers?: Record<string, string>, session?: {
+    sessionId: string;
+    sessionIdentity: SessionIdentity | null;
+}): 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":"AAoCA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEnF;;;;;;;;;;;;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,CAuG9E;AAED,kEAAkE;AAClE,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAgBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAsDpE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,IAAI,CAqCf;AACD;;;;;;;;;;;;;;;GAeG;AACH,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,EAChC,OAAO,CAAC,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,eAAe,GAAG,IAAI,CAAA;CAAE,GACvE,cAAc,CAUhB"}