@gate-forge/witness 0.0.0-stage → 0.8.0

package/dist/adapter/index.js

@@ -0,0 +1,2 @@
+export { CONTRACT_SCENARIOS, contractScenario, runRunnerAdapterContract } from './contract-suite.js';
+//# sourceMappingURL=index.js.map

package/dist/adapter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/adapter-kit/config.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Adapter-kit configuration: the reviewed CONFIG a project writes
+ * instead of a hand-rolled `read`/`list`/`normalize` triple.
+ *
+ * The kit is a constructor, never a contract change: what it returns is
+ * the frozen pin-#8 `EvidenceAdapter` a hand-written module exports, and
+ * a hand-written module keeps working unchanged. Everything here is
+ * GET-only — the kit can log in (one POST to a declared login path
+ * with credentials named by WITNESS env vars) and then read, but it can
+ * never create, update, or delete business state.
+ *
+ * Design rules carried by these types:
+ * - every doubt fails closed with a plain message (a truncated list, an
+ *   unknown field, a redirect-only path, a cap that hid rows);
+ * - `volatileFields` is declared, never inferred: the engine skips the
+ *   exact-value echo for those keys and says so in the report;
+ * - credentials are named by ENV VAR, never inlined, and are read only
+ *   from the witness process environment.
+ */
+/** How one collection read walks its pages. */
+export type PagingKind = 'cursor' | 'page' | 'offset';
+/**
+ * Paging declaration for a collection read. Bounded on purpose: a walk
+ * that reaches the cap with a next page available is a TRUNCATION, not
+ * a complete list, and the kit fails closed instead of returning a
+ * partial id set (E11, E27).
+ */
+export interface HttpAdapterPaging {
+    /** Cursor-, page-number-, or offset-addressed pages. */
+    kind: PagingKind;
+    /** Rows per page for `page`/`offset` (default 100). */
+    pageSize?: number;
+    /** Hard page cap for every kind (default 100). */
+    maxPages?: number;
+    /** Query parameter carrying the page number (default `page`). */
+    pageParam?: string;
+    /** Query parameter carrying the page size (default `page_size`). */
+    pageSizeParam?: string;
+    /** Query parameter carrying the offset (default `offset`). */
+    offsetParam?: string;
+    /** Query parameter carrying the row limit (default `limit`). */
+    limitParam?: string;
+}
+/** One named login seat: credentials named by WITNESS env vars. */
+export interface CookieLoginSeat {
+    /** Path the one login POST is sent to (absolute path). */
+    loginPath: string;
+    /**
+     * Login request body field -> WITNESS env var holding its value.
+     * The values are read from `process.env` at call time and never
+     * printed, logged, or written anywhere.
+     */
+    credentials: Readonly<Record<string, string>>;
+    /** Keep only this cookie name from the login response (default: all). */
+    cookieName?: string;
+    /** Extra headers for the login POST (e.g. `content-type`). */
+    headers?: Readonly<Record<string, string>>;
+}
+/** One named bearer seat: a token named by a WITNESS env var. */
+export interface BearerSeat {
+    /** WITNESS env var holding the bearer token. */
+    tokenEnv: string;
+    /** Prefix prepended to the token (default `Bearer`). */
+    scheme?: string;
+}
+/** Read authentication for one adapter (witness-side only). */
+export type HttpAdapterAuth = {
+    kind: 'none';
+} | {
+    kind: 'bearer';
+    seats: Readonly<Record<string, BearerSeat>>;
+    seat?: string;
+} | {
+    kind: 'cookie-login';
+    seats: Readonly<Record<string, CookieLoginSeat>>;
+    seat?: string;
+};
+/** One kit adapter's whole declaration. */
+export interface HttpAdapterConfig {
+    /** Registry identity; must equal the adapter file name. */
+    resourceId: string;
+    /**
+     * By-id read path. A function receives the entity id; a string may
+     * carry the `{id}` placeholder. `null` resolves members from the
+     * collection read instead.
+     */
+    readPath?: string | ((id: string) => string) | null;
+    /** Key holding the entity inside a by-id response body (default: none). */
+    itemWrapper?: string | null;
+    /** Collection path, or a `(cursor) => path` function for cursors. */
+    listPath?: string | ((cursor: string | undefined) => string) | null;
+    /** Key holding the array in a collection body, or a selector. */
+    collectionKey?: string | ((body: unknown) => unknown) | null;
+    /** Next cursor from a page body (cursor paging only). */
+    pageCursor?: (body: unknown) => string | null | undefined;
+    /** Paging declaration for the collection walk. */
+    paging?: HttpAdapterPaging;
+    /**
+     * Per-parent fan-out: composes a whole collection from several
+     * collections. Receives `readAll(pathFor, shape)` and MUST return the
+     * complete member list.
+     */
+    listCollection?: (readAll: CollectionReader) => Promise<readonly unknown[]>;
+    /**
+     * Projected business fields. Dotted paths are allowed (`owner.name`)
+     * and every declared key is checked against the compiled graph by
+     * `gateforge adapters check`.
+     */
+    fields?: readonly string[];
+    /** Projected name -> key the response actually carries. */
+    fieldMap?: Readonly<Record<string, string>>;
+    /** Key identifying the entity when the row has no `id` (default `id`). */
+    entityIdKey?: string;
+    /** How removal manifests for this resource. */
+    deletion: 'hard' | 'archive';
+    /** Target-environment marker the witness compares (GF-13). */
+    environmentFingerprint: string;
+    /**
+     * Fields the SERVER computes on its own. The engine skips the
+     * exact-value echo for them and reports the skip — never silently.
+     */
+    volatileFields?: readonly string[];
+    /** Entity-scoped create absence without a collection list. */
+    identity?: 'natural-key';
+    /** Read authentication (witness environment credentials only). */
+    auth?: HttpAdapterAuth;
+    /** Base override for THIS adapter's reads. */
+    baseUrl?: string;
+    /** Optional server probe (contract addition, passed through as-is). */
+    probeServer?: (...args: never[]) => unknown;
+    /** Optional observe binding (contract addition, passed through as-is). */
+    observe?: unknown;
+    /** Optional trusted scope observation (contract addition). */
+    snapshotScope?: (...args: never[]) => unknown;
+    /** Optional completion-barrier observer (contract addition). */
+    awaitBarrier?: (...args: never[]) => unknown;
+}
+/** Options a {@link CollectionReader} call accepts. */
+export interface CollectionReadOptions {
+    /** Key holding the array in the page body (default: none). */
+    collectionKey?: string | ((body: unknown) => unknown) | null;
+    /** Next cursor from a page body (cursor paging only). */
+    pageCursor?: (body: unknown) => string | null | undefined;
+    /** Paging override for this collection. */
+    paging?: HttpAdapterPaging;
+    /** Page cap override for this collection. */
+    maxPages?: number;
+}
+/**
+ * Reads one (possibly paged) collection to completion.
+ *
+ * Args:
+ *   pathFor: collection path, or a `(cursor) => path` function.
+ *   options: collection key, cursor extraction, and paging overrides.
+ *
+ * Returns:
+ *   Promise<readonly unknown[]>: every member row across all pages.
+ * @throws Error when a page is malformed, a cursor repeats, or the walk
+ *   reaches its cap with rows still unread (a truncated list is never
+ *   reported as a complete one).
+ */
+export type CollectionReader = (pathFor: string | ((cursor: string | undefined) => string), options?: CollectionReadOptions) => Promise<readonly unknown[]>;
+//# sourceMappingURL=config.d.ts.map

package/dist/adapter-kit/config.d.ts.map

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

package/dist/adapter-kit/config.js

@@ -0,0 +1,21 @@
+/**
+ * Adapter-kit configuration: the reviewed CONFIG a project writes
+ * instead of a hand-rolled `read`/`list`/`normalize` triple.
+ *
+ * The kit is a constructor, never a contract change: what it returns is
+ * the frozen pin-#8 `EvidenceAdapter` a hand-written module exports, and
+ * a hand-written module keeps working unchanged. Everything here is
+ * GET-only — the kit can log in (one POST to a declared login path
+ * with credentials named by WITNESS env vars) and then read, but it can
+ * never create, update, or delete business state.
+ *
+ * Design rules carried by these types:
+ * - every doubt fails closed with a plain message (a truncated list, an
+ *   unknown field, a redirect-only path, a cap that hid rows);
+ * - `volatileFields` is declared, never inferred: the engine skips the
+ *   exact-value echo for those keys and says so in the report;
+ * - credentials are named by ENV VAR, never inlined, and are read only
+ *   from the witness process environment.
+ */
+export {};
+//# sourceMappingURL=config.js.map

package/dist/adapter-kit/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/adapter-kit/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/adapter-kit/define.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `defineHttpAdapter(config)`: the reviewed config → contract-valid
+ * adapter constructor.
+ *
+ * What it buys a project: a correct by-id read, a complete (paged)
+ * collection read, a deterministic projection, declared
+ * server-computed fields, and witness-side login — from configuration
+ * instead of a hand-rolled module. What it never does: trust itself.
+ * The returned object is an ordinary pin-#8 adapter; the gate treats a
+ * generated adapter exactly like a hand-written one, every doubt fails
+ * closed with a plain message, and nothing here can write.
+ */
+import type { HttpAdapterConfig } from './config.js';
+import type { EvidenceAdapter, SessionIdentity } from '../witness/types.js';
+/** The context a probe read runs under (the audit passes just a base URL). */
+export type KitProbeContext = {
+    baseUrl: string;
+    headers?: Record<string, string>;
+    /**
+     * The session a witnessed read belongs to, and the identity THAT
+     * session registered (plan Phase 4b item 3b). A probe (no session)
+     * carries neither and reads through the environment seat, exactly as
+     * before.
+     */
+    sessionId?: string;
+    sessionIdentity?: SessionIdentity | null;
+};
+/** Default page cap for every bounded collection walk. */
+export declare const DEFAULT_MAX_PAGES = 100;
+/** Default rows per page for page/offset paging. */
+export declare const DEFAULT_PAGE_SIZE = 100;
+/**
+ * Builds one contract-valid adapter from reviewed configuration.
+ *
+ * Args:
+ *   config: the adapter declaration (paths, projection, paging, auth).
+ *
+ * Returns:
+ *   EvidenceAdapter: a frozen pin-#8 adapter. `list` is exported only
+ *   when the config declares a collection read, so a resource without
+ *   one honestly reports that the witness cannot pre-observe it.
+ * @throws Error when the config can never produce a valid adapter
+ *   (no read and no list; an unusable projection) — fail closed at
+ *   write time rather than at gate time.
+ */
+export declare function defineHttpAdapter(config: HttpAdapterConfig): EvidenceAdapter;
+//# sourceMappingURL=define.d.ts.map

package/dist/adapter-kit/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/adapter-kit/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAGV,iBAAiB,EAElB,MAAM,aAAa,CAAC;AAQrB,OAAO,KAAK,EAAkB,eAAe,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE5F,8EAA8E;AAC9E,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CAC1C,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,MAAM,CAAC;AA4CrC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,eAAe,CA8S5E"}

package/dist/adapter-kit/define.js

@@ -0,0 +1,336 @@
+import { projectEntity } from './projection.js';
+import { createSessionReader, } from './session.js';
+/** Default page cap for every bounded collection walk. */
+export const DEFAULT_MAX_PAGES = 100;
+/** Default rows per page for page/offset paging. */
+export const DEFAULT_PAGE_SIZE = 100;
+/**
+ * Appends a query parameter to a path, preserving what is already there.
+ *
+ * Args:
+ *   path: path (with any existing query) to extend.
+ *   key: query parameter name.
+ *   value: parameter value.
+ *
+ * Returns:
+ *   string: the path with one more query parameter.
+ */
+function withQuery(path, key, value) {
+    const separator = path.includes('?') ? '&' : '?';
+    return `${path}${separator}${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+}
+/**
+ * Applies the declared paging to one page path.
+ *
+ * Args:
+ *   basePath: the collection path without paging parameters.
+ *   paging: the paging declaration.
+ *   page: 1-based page number.
+ *
+ * Returns:
+ *   string: the path for that page.
+ */
+function pagedPath(basePath, paging, page) {
+    if (paging.kind === 'page') {
+        const size = paging.pageSize ?? DEFAULT_PAGE_SIZE;
+        let path = withQuery(basePath, paging.pageParam ?? 'page', String(page));
+        path = withQuery(path, paging.pageSizeParam ?? 'page_size', String(size));
+        return path;
+    }
+    if (paging.kind === 'offset') {
+        const size = paging.pageSize ?? DEFAULT_PAGE_SIZE;
+        const offset = withQuery(basePath, paging.offsetParam ?? 'offset', String((page - 1) * size));
+        return withQuery(offset, paging.limitParam ?? 'limit', String(size));
+    }
+    return basePath;
+}
+/**
+ * Builds one contract-valid adapter from reviewed configuration.
+ *
+ * Args:
+ *   config: the adapter declaration (paths, projection, paging, auth).
+ *
+ * Returns:
+ *   EvidenceAdapter: a frozen pin-#8 adapter. `list` is exported only
+ *   when the config declares a collection read, so a resource without
+ *   one honestly reports that the witness cannot pre-observe it.
+ * @throws Error when the config can never produce a valid adapter
+ *   (no read and no list; an unusable projection) — fail closed at
+ *   write time rather than at gate time.
+ */
+export function defineHttpAdapter(config) {
+    const hasRead = config.readPath !== undefined && config.readPath !== null;
+    const hasList = (config.listPath !== undefined && config.listPath !== null) ||
+        typeof config.listCollection === 'function';
+    if (!hasRead && !hasList) {
+        throw new Error(`${config.resourceId}: adapter declares neither readPath nor listPath/listCollection — ` +
+            'an evidence adapter must be able to observe the resource');
+    }
+    const sessions = new Map();
+    // The context of the read in flight: a kit `listCollection` callback
+    // receives only the reader, never the witness context.
+    let lastCtx = null;
+    /**
+     * Projects one raw body onto the evidence shape.
+     *
+     * Args:
+     *   body: the raw response body.
+     *
+     * Returns:
+     *   NormalizedEntity: entity id plus the declared projected fields.
+     */
+    const normalize = (body) => projectEntity(body, {
+        ...(config.fields !== undefined ? { fields: config.fields } : {}),
+        ...(config.fieldMap !== undefined ? { fieldMap: config.fieldMap } : {}),
+        ...(config.entityIdKey !== undefined ? { entityIdKey: config.entityIdKey } : {}),
+    });
+    /**
+     * Reads one path through the kit transport and returns status+body.
+     *
+     * Args:
+     *   ctx: the read context (the witness adapter context, or a
+     *     probe's base URL).
+     *   path: absolute path to read.
+     *
+     * Returns:
+     *   Promise<KitGetResult>: status, headers, parsed body.
+     */
+    const request = (ctx, path) => createSessionReader({
+        ...(config.auth !== undefined ? { auth: config.auth } : {}),
+        resourceId: config.resourceId,
+        ctx,
+        sessions,
+    })(path);
+    /**
+     * Resolves the declared by-id path for one entity.
+     *
+     * Args:
+     *   id: the entity id.
+     *
+     * Returns:
+     *   string: the by-id path.
+     */
+    const pathForId = (id) => {
+        if (typeof config.readPath === 'function')
+            return config.readPath(id);
+        return config.readPath.replaceAll('{id}', encodeURIComponent(id));
+    };
+    /**
+     * The exact path this adapter's first collection read hits (null
+     * when it composes one itself).
+     *
+     * Returns:
+     *   string | null: the first page path, or null.
+     */
+    const firstListPath = () => {
+        if (config.listCollection !== undefined)
+            return null;
+        if (config.listPath === undefined || config.listPath === null)
+            return null;
+        const paging = config.paging ?? { kind: 'page' };
+        return typeof config.listPath === 'function'
+            ? pagedPath(config.listPath(undefined), paging, 1)
+            : pagedPath(config.listPath, paging, 1);
+    };
+    /**
+     * Walks one (possibly paged) collection to completion.
+     *
+     * Args:
+     *   ctx: the witness adapter context.
+     *   pathFor: the collection path, or a `(cursor) => path` function.
+     *   options: collection key, cursor extraction, paging overrides.
+     *
+     * Returns:
+     *   Promise<readonly unknown[]>: every member row across all pages.
+     * @throws Error on a malformed page, a repeated cursor, or a walk
+     *   that reached its cap with rows still unread (never a silent
+     *   truncation).
+     */
+    const readAllFor = async (ctx, pathFor, options = {}) => {
+        const paging = options.paging ?? config.paging ?? { kind: 'page' };
+        const maxPages = options.maxPages ?? paging.maxPages ?? DEFAULT_MAX_PAGES;
+        const collectionKey = options.collectionKey === undefined ? (config.collectionKey ?? null) : options.collectionKey;
+        const pageCursor = options.pageCursor ?? config.pageCursor;
+        const rows = [];
+        const seenCursors = new Set();
+        let cursor;
+        for (let page = 1; page <= maxPages; page += 1) {
+            let path;
+            if (paging.kind === 'cursor') {
+                if (typeof pathFor === 'function')
+                    path = pathFor(cursor);
+                else if (cursor === undefined)
+                    path = pathFor;
+                else
+                    path = withQuery(pathFor, 'cursor', cursor);
+            }
+            else {
+                const base = typeof pathFor === 'function' ? pathFor(undefined) : pathFor;
+                path = pagedPath(base, paging, page);
+            }
+            const result = await request(ctx, path);
+            if (result.status < 200 || result.status >= 300) {
+                throw new Error(`${config.resourceId}: collection read GET ${path} -> ${String(result.status)}`);
+            }
+            const pageRows = typeof collectionKey === 'function'
+                ? collectionKey(result.body)
+                : collectionKey === null || collectionKey === undefined
+                    ? result.body
+                    : result.body?.[collectionKey];
+            if (!Array.isArray(pageRows)) {
+                throw new Error(`${config.resourceId}: collection read GET ${path} returned no array` +
+                    (collectionKey === null || collectionKey === undefined
+                        ? ' (declare collectionKey when the body wraps the rows)'
+                        : ` under '${String(collectionKey)}'`));
+            }
+            rows.push(...pageRows);
+            if (paging.kind === 'cursor') {
+                const next = pageCursor?.(result.body);
+                if (next === null || next === undefined)
+                    return rows;
+                const key = String(next);
+                // A repeated cursor would loop forever and never prove completeness.
+                if (seenCursors.has(key)) {
+                    throw new Error(`${config.resourceId}: collection cursor repeated ('${key}') — the list would never ` +
+                        'be complete');
+                }
+                seenCursors.add(key);
+                cursor = key;
+                continue;
+            }
+            const size = paging.pageSize ?? DEFAULT_PAGE_SIZE;
+            // A short page IS the last page.
+            if (pageRows.length < size)
+                return rows;
+            // A full page before the cap: keep walking.
+            if (page < maxPages)
+                continue;
+            // A full page AT the cap means rows are unread, which is a
+            // truncation, not a list (E11, E27).
+            throw new Error(`${config.resourceId}: result truncated — ${String(rows.length)} row(s) read in ` +
+                `${String(maxPages)} page(s) of ${String(size)} and the collection still has more ` +
+                '(raise paging.maxPages or fix the collectionKey; a partial id set never proves absence)');
+        }
+        throw new Error(`${config.resourceId}: collection read reached the ${String(maxPages)}-page cap without a ` +
+            'next page (raise paging.maxPages or fix the cursor)');
+    };
+    /**
+     * GET-only read of one entity.
+     *
+     * Args:
+     *   ctx: the witness adapter context.
+     *   id: the entity id.
+     *
+     * Returns:
+     *   Promise<unknown>: the raw entity body, or null when absent (404).
+     * @throws Error on any non-2xx other than 404, and on a redirect.
+     */
+    const read = async (ctx, id) => {
+        lastCtx = ctx;
+        const wanted = String(id);
+        if (hasRead) {
+            const path = pathForId(wanted);
+            const result = await request(ctx, path);
+            if (result.status === 404)
+                return null;
+            if (result.status < 200 || result.status >= 300) {
+                throw new Error(`${config.resourceId}: GET ${path} -> ${String(result.status)}`);
+            }
+            const member = config.itemWrapper === undefined || config.itemWrapper === null
+                ? result.body
+                : result.body?.[config.itemWrapper];
+            return member === undefined ? null : member;
+        }
+        // Collection-resolved member: the read path is unknown, so the id is
+        // located in the complete collection (GET-only).
+        const rows = await listEntities(ctx);
+        return (rows.find((row) => normalize(row).entityId === wanted) ?? null);
+    };
+    /**
+     * Reads the whole collection through whichever source is declared.
+     *
+     * Args:
+     *   ctx: the witness adapter context.
+     *
+     * Returns:
+     *   Promise<readonly unknown[]>: every member row.
+     */
+    const listEntities = async (ctx) => {
+        lastCtx = ctx;
+        if (config.listCollection !== undefined) {
+            const rows = await config.listCollection((pathFor, options) => readAllFor(ctx, pathFor, options));
+            if (!Array.isArray(rows)) {
+                throw new Error(`${config.resourceId}: composed collection returned no array — listCollection must ` +
+                    'resolve the complete member list');
+            }
+            return rows;
+        }
+        return readAllFor(ctx, config.listPath, {});
+    };
+    const readAll = (pathFor, options) => {
+        if (lastCtx === null) {
+            throw new Error(`${config.resourceId}: collection read used outside an adapter read/list call`);
+        }
+        return readAllFor(lastCtx, pathFor, options);
+    };
+    /**
+     * Issues ONE read through this adapter's own transport — seat
+     * login, cookie/bearer, one re-login on 401, GET-only — so a probe
+     * sees exactly what a witnessed run would. Never writes.
+     *
+     * Args:
+     *   ctx: the base URL to read (headers, when the app needs them).
+     *   id: the entity id to read when there is no collection read.
+     *
+     * Returns:
+     *   Promise<KitProbeResult>: the path, status, and headers of that read.
+     * @throws KitAuthError when the seat's credentials are absent or
+     *   rejected; KitRedirectError when the read only works through a
+     *   redirect.
+     */
+    const probe = async (ctx, id) => {
+        const listPath = firstListPath();
+        const path = listPath ?? pathForId(id ?? '0');
+        const result = await request(ctx, path);
+        return { path, status: result.status, headers: result.headers };
+    };
+    return Object.freeze({
+        resourceId: config.resourceId,
+        read,
+        // Read-only introspection for `gateforge adapters check --probe`:
+        // the exact path this adapter's first read of each kind hits. Not
+        // part of the pin-#8 contract; ignored by the witness.
+        evidencePaths: {
+            read: (id) => (hasRead ? pathForId(id) : null),
+            list: () => firstListPath(),
+        },
+        // Read-only introspection for `gateforge adapters check --probe`:
+        // the ONE read this adapter would issue, issued through its own
+        // seat, so the probe reports what a witnessed run would see. Not
+        // part of the pin-#8 contract; ignored by the witness.
+        probe,
+        ...(hasList
+            ? { list: async (ctx) => [...(await listEntities(ctx))] }
+            : {}),
+        normalize,
+        deletion: config.deletion,
+        environmentFingerprint: config.environmentFingerprint,
+        ...(config.fields !== undefined ? { fields: [...config.fields] } : {}),
+        ...(config.volatileFields !== undefined
+            ? { volatileFields: [...config.volatileFields] }
+            : {}),
+        ...(config.identity !== undefined ? { identity: config.identity } : {}),
+        ...(config.baseUrl !== undefined ? { baseUrl: config.baseUrl } : {}),
+        ...(config.probeServer !== undefined
+            ? { probeServer: config.probeServer }
+            : {}),
+        ...(config.observe !== undefined ? { observe: config.observe } : {}),
+        ...(config.snapshotScope !== undefined
+            ? { snapshotScope: config.snapshotScope }
+            : {}),
+        ...(config.awaitBarrier !== undefined
+            ? { awaitBarrier: config.awaitBarrier }
+            : {}),
+    });
+}
+//# sourceMappingURL=define.js.map

package/dist/adapter-kit/define.js.map

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

package/dist/adapter-kit/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `@gate-forge/witness/adapter-kit` — the configuration-first
+ * constructor for evidence adapters.
+ *
+ * A project writes a reviewed config (paths, wrapper keys, projected
+ * fields, paging, login seat) and gets a contract-valid adapter:
+ *
+ * ```js
+ * import { defineHttpAdapter } from '@gate-forge/witness/adapter-kit';
+ *
+ * export default defineHttpAdapter({
+ *   resourceId: 'tenant.accounts',
+ *   readPath: (id) => `/api/accounts/${encodeURIComponent(id)}`,
+ *   listPath: '/api/accounts',
+ *   collectionKey: 'accounts',
+ *   paging: { kind: 'page', pageSize: 100 },
+ *   fields: ['first_name', 'last_name', 'status'],
+ *   deletion: 'archive',
+ *   environmentFingerprint: 'loopback-v1',
+ * });
+ * ```
+ *
+ * The kit is a convenience, never a shortcut past the gate: what it
+ * returns is the frozen pin-#8 adapter, the gate grades a generated
+ * adapter exactly like a hand-written one, and a generated file is a
+ * STARTING POINT for review — `gateforge adapters scaffold` marks
+ * every guess and lists what still needs a human.
+ */
+export { defineHttpAdapter, DEFAULT_MAX_PAGES, DEFAULT_PAGE_SIZE } from './define.js';
+export type { KitProbeContext } from './define.js';
+export { firstArrayOf, readPath, projectEntity, type NormalizedEntity, type ProjectionConfig, } from './projection.js';
+export { createSessionReader, KitAuthError, KitRedirectError, type KitAuthFailure, type KitGetResult, type KitProbeResult, type SessionReaderOptions, } from './session.js';
+export type { BearerSeat, CollectionReader, CollectionReadOptions, CookieLoginSeat, HttpAdapterAuth, HttpAdapterConfig, HttpAdapterPaging, PagingKind, } from './config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapter-kit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapter-kit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACtF,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,oBAAoB,GAC1B,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,GACX,MAAM,aAAa,CAAC"}