@gate-forge/witness 0.0.0-stage → 0.9.0

package/dist/adapter-kit/index.js

@@ -0,0 +1,32 @@
+/**
+ * `@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 { firstArrayOf, readPath, projectEntity, } from './projection.js';
+export { createSessionReader, KitAuthError, KitRedirectError, } from './session.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapter-kit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEtF,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,aAAa,GAGd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,GAKjB,MAAM,cAAc,CAAC"}

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

@@ -0,0 +1,69 @@
+/**
+ * Row projection: the shared, deterministic mapping from one raw
+ * response body onto the evidence shape `{ entityId, fields }`.
+ *
+ * Pure and total: an absent field is omitted (never invented as
+ * `null`), so a field the endpoint does not return can never be
+ * mistaken for a persisted value.
+ */
+/** The evidence shape every adapter's `normalize` returns. */
+export interface NormalizedEntity {
+    /** The entity id, projected from the raw body. */
+    entityId: string;
+    /** Projected fields the obligation's `expectFields` can match. */
+    fields: Record<string, unknown>;
+}
+/** Projection inputs (the kit's field-shaped config). */
+export interface ProjectionConfig {
+    /** Projected field names (dotted paths allowed). */
+    fields?: readonly string[];
+    /** Projected name -> key the response actually carries. */
+    fieldMap?: Readonly<Record<string, string>>;
+    /** Key identifying the entity (default `id`). */
+    entityIdKey?: string;
+}
+/**
+ * Reads one dotted path out of a raw body.
+ *
+ * Args:
+ *   source: the raw row.
+ *   path: key, or dotted path (`owner.name`).
+ *
+ * Returns:
+ *   unknown: the value at that path, or `undefined` when any segment is
+ *   absent (an absent value is never an error here — the caller decides
+ *   what an unknown field means).
+ */
+export declare function readPath(source: unknown, path: string): unknown;
+/**
+ * Projects one raw row onto the evidence shape.
+ *
+ * Args:
+ *   body: the raw response body.
+ *   config: field-shaped kit config (`fields`, `fieldMap`, `entityIdKey`).
+ *
+ * Returns:
+ *   NormalizedEntity: the entity id plus exactly the declared fields the
+ *   row carries. A non-object body yields an empty projection.
+ */
+export declare function projectEntity(body: unknown, config: ProjectionConfig): NormalizedEntity;
+/**
+ * A tolerant collection selector: the first array-valued property of a
+ * collection body, or the body itself when it already IS an array.
+ *
+ * A generated adapter uses it because the compiled graph knows WHICH
+ * collection route serves a resource, never the key the response wraps
+ * its rows in. It fails closed — a body with no array anywhere is an
+ * error the caller reports, not an empty list that would make every
+ * created row look absent — and every generated use is marked as a
+ * guess for the reviewer to replace with the exact key.
+ *
+ * Args:
+ *   body: the parsed collection response body.
+ *
+ * Returns:
+ *   unknown: the first array-valued property value, or the body itself
+ *   when it is an array; undefined when neither is present.
+ */
+export declare function firstArrayOf(body: unknown): unknown;
+//# sourceMappingURL=projection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../src/adapter-kit/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5C,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAO/D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAavF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAOnD"}

package/dist/adapter-kit/projection.js

@@ -0,0 +1,85 @@
+/**
+ * Row projection: the shared, deterministic mapping from one raw
+ * response body onto the evidence shape `{ entityId, fields }`.
+ *
+ * Pure and total: an absent field is omitted (never invented as
+ * `null`), so a field the endpoint does not return can never be
+ * mistaken for a persisted value.
+ */
+/**
+ * Reads one dotted path out of a raw body.
+ *
+ * Args:
+ *   source: the raw row.
+ *   path: key, or dotted path (`owner.name`).
+ *
+ * Returns:
+ *   unknown: the value at that path, or `undefined` when any segment is
+ *   absent (an absent value is never an error here — the caller decides
+ *   what an unknown field means).
+ */
+export function readPath(source, path) {
+    let current = source;
+    for (const segment of path.split('.')) {
+        if (current === null || typeof current !== 'object')
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * Projects one raw row onto the evidence shape.
+ *
+ * Args:
+ *   body: the raw response body.
+ *   config: field-shaped kit config (`fields`, `fieldMap`, `entityIdKey`).
+ *
+ * Returns:
+ *   NormalizedEntity: the entity id plus exactly the declared fields the
+ *   row carries. A non-object body yields an empty projection.
+ */
+export function projectEntity(body, config) {
+    if (body === null || typeof body !== 'object') {
+        return { entityId: '', fields: {} };
+    }
+    const fields = {};
+    for (const key of config.fields ?? []) {
+        const sourceKey = config.fieldMap?.[key] ?? key;
+        const value = readPath(body, sourceKey);
+        if (value !== undefined)
+            fields[key] = value;
+    }
+    const idKey = config.entityIdKey ?? 'id';
+    const rawId = readPath(body, idKey);
+    return { entityId: rawId === undefined || rawId === null ? '' : String(rawId), fields };
+}
+/**
+ * A tolerant collection selector: the first array-valued property of a
+ * collection body, or the body itself when it already IS an array.
+ *
+ * A generated adapter uses it because the compiled graph knows WHICH
+ * collection route serves a resource, never the key the response wraps
+ * its rows in. It fails closed — a body with no array anywhere is an
+ * error the caller reports, not an empty list that would make every
+ * created row look absent — and every generated use is marked as a
+ * guess for the reviewer to replace with the exact key.
+ *
+ * Args:
+ *   body: the parsed collection response body.
+ *
+ * Returns:
+ *   unknown: the first array-valued property value, or the body itself
+ *   when it is an array; undefined when neither is present.
+ */
+export function firstArrayOf(body) {
+    if (Array.isArray(body))
+        return body;
+    if (body === null || typeof body !== 'object')
+        return undefined;
+    for (const value of Object.values(body)) {
+        if (Array.isArray(value))
+            return value;
+    }
+    return undefined;
+}
+//# sourceMappingURL=projection.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"projection.js","sourceRoot":"","sources":["../../src/adapter-kit/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoBH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAe,EAAE,IAAY;IACpD,IAAI,OAAO,GAAY,MAAM,CAAC;IAC9B,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACtC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACtE,OAAO,GAAI,OAAmC,CAAC,OAAO,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa,EAAE,MAAwB;IACnE,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9C,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACtC,CAAC;IACD,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QACtC,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;QAChD,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACxC,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC/C,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,IAAI,IAAI,CAAC;IACzC,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACpC,OAAO,EAAE,QAAQ,EAAE,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;AAC1F,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChE,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,IAA+B,CAAC,EAAE,CAAC;QACnE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;IACzC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

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

@@ -0,0 +1,105 @@
+/**
+ * Witness-side authenticated session for kit adapters.
+ *
+ * Credentials live in the WITNESS process environment and nowhere else:
+ * every seat names its env vars in the adapter config, the values are
+ * read at call time, and nothing here logs, prints, or returns them. A
+ * seat performs exactly one login POST (the same request a human
+ * browser performs) and then issues GET-only evidence reads with the
+ * session it obtained; a read rejected with 401 triggers ONE re-login
+ * and one retry, never a loop.
+ *
+ * This module can authenticate and read. It cannot create, update, or
+ * delete business state — no method here issues anything but the
+ * declared login POST and GETs.
+ */
+import type { HttpAdapterAuth } from './config.js';
+import type { SessionIdentity } from '../witness/types.js';
+/** One cached seat session (per base URL). */
+interface SeatSession {
+    /** Credential header value, or null while not logged in. */
+    authorization: string | null;
+    /** Cookie header value, or null while not logged in. */
+    cookie: string | null;
+}
+/** Sessions keyed by `<baseUrl>|<seat>`, shared by every read of one kit adapter. */
+export type SessionStore = Map<string, SeatSession>;
+/** The result of one kit-issued GET. */
+export interface KitGetResult {
+    /** HTTP status. */
+    status: number;
+    /** Response headers (fingerprint marker lives here). */
+    headers: Headers;
+    /** Parsed JSON body, or undefined for a non-JSON body. */
+    body: unknown;
+}
+/** What one probe read showed, as the kit's own read path saw it. */
+export interface KitProbeResult {
+    /** The exact path the read GET hit. */
+    path: string;
+    /** HTTP status of that GET. */
+    status: number;
+    /** Response headers (the environment marker lives here). */
+    headers: Headers;
+}
+/** The witness env vars a seat failure is about (names, never values). */
+export interface KitAuthFailure {
+    /** The seat that could not authenticate. */
+    seat: string;
+    /** Env var names the seat needs, or null when the login was rejected. */
+    envVars: readonly string[] | null;
+}
+/** Raised when the witness environment does not carry a credential. */
+export declare class KitAuthError extends Error {
+    /** Which seat failed, and which env vars it needs (null: rejected login). */
+    readonly failure: KitAuthFailure | null;
+    /**
+     * Builds one auth failure.
+     *
+     * Args:
+     *   message: the plain message a witnessed run shows.
+     *   failure: the structured facts a probe reports, when it has them.
+     */
+    constructor(message: string, failure?: KitAuthFailure | null);
+}
+/** Raised when a read only succeeds through a redirect. */
+export declare class KitRedirectError extends Error {
+    constructor(message: string);
+}
+/** The kit's per-adapter read transport. */
+export interface SessionReaderOptions {
+    /** The adapter's declared auth (default: none). */
+    auth?: HttpAdapterAuth;
+    /** Registry identity, for diagnostics. */
+    resourceId: string;
+    /**
+     * The witness-adapter context the read runs under, carrying the
+     * session the read belongs to and the identity THAT session
+     * registered (plan Phase 4b item 3b).
+     */
+    ctx: {
+        baseUrl: string;
+        headers?: Record<string, string>;
+        sessionId?: string;
+        sessionIdentity?: SessionIdentity | null;
+    };
+    /** Per-request timeout in ms (default 10000). */
+    timeoutMs?: number;
+    /** Session store shared across reads (one login, then reused). */
+    sessions?: SessionStore;
+}
+/**
+ * Builds the kit's GET transport for one adapter invocation.
+ *
+ * Args:
+ *   options: declared auth, resource id, and the witness context.
+ *
+ * Returns:
+ *   (path: string) => Promise<KitGetResult>: one read, login included.
+ * @throws KitAuthError on missing/rejected credentials; KitRedirectError
+ *   when the app answers the read with a redirect (a read that only
+ *   works through a redirect is never a stable evidence path).
+ */
+export declare function createSessionReader(options: SessionReaderOptions): (path: string) => Promise<KitGetResult>;
+export {};
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/adapter-kit/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAA+B,eAAe,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,8CAA8C;AAC9C,UAAU,WAAW;IACnB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,wDAAwD;IACxD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAmBD,qFAAqF;AACrF,MAAM,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEpD,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,IAAI,EAAE,OAAO,CAAC;CACf;AAED,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CACnC;AAED,uEAAuE;AACvE,qBAAa,YAAa,SAAQ,KAAK;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAExC;;;;;;OAMG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,cAAc,GAAG,IAAW;CAKnE;AAED,2DAA2D;AAC3D,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AA8JD,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,GAAG,EAAE;QACH,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;KAC1C,CAAC;IACF,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAwE1G"}

package/dist/adapter-kit/session.js

@@ -0,0 +1,230 @@
+/** Raised when the witness environment does not carry a credential. */
+export class KitAuthError extends Error {
+    /** Which seat failed, and which env vars it needs (null: rejected login). */
+    failure;
+    /**
+     * Builds one auth failure.
+     *
+     * Args:
+     *   message: the plain message a witnessed run shows.
+     *   failure: the structured facts a probe reports, when it has them.
+     */
+    constructor(message, failure = null) {
+        super(message);
+        this.name = 'KitAuthError';
+        this.failure = failure;
+    }
+}
+/** Raised when a read only succeeds through a redirect. */
+export class KitRedirectError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'KitRedirectError';
+    }
+}
+/**
+ * Resolves the seat one read authenticates with: the identity THIS
+ * session registered (plan Phase 4b item 3b) when it names a declared
+ * seat, else the adapter's configured seat with the process-global
+ * environment credentials — today's behavior, byte-identical when no
+ * identity is registered.
+ *
+ * Args:
+ *   auth: the adapter's declared auth.
+ *   identity: the reading session's registered identity, or null.
+ *
+ * Returns:
+ *   ResolvedSeat | null: the seat plus its credential source, or null
+ *   for `kind: 'none'`.
+ * @throws KitAuthError when the named seat does not exist, or when an
+ *   identity names a seat this adapter does not declare.
+ */
+function resolveSeat(auth, identity) {
+    if (auth.kind === 'none')
+        return null;
+    const seats = auth.seats;
+    if (identity !== null && seats[identity.seat] === undefined) {
+        throw new KitAuthError(`session identity seat '${identity.seat}' is not declared by this adapter (available: ` +
+            `${Object.keys(seats).sort().join(', ')})`);
+    }
+    // The registered identity WINS for the seat it names; every other seat
+    // keeps reading through the process-global environment.
+    const name = identity?.seat ?? auth.seat ?? Object.keys(seats)[0];
+    if (name === undefined) {
+        throw new KitAuthError('auth declares no seats: add a named seat (credentials are read from the witness environment)');
+    }
+    const seat = seats[name];
+    if (seat === undefined) {
+        throw new KitAuthError(`auth seat '${name}' is not declared (available: ${Object.keys(seats).sort().join(', ')})`);
+    }
+    // Credential source: the session's own values for the seat it named,
+    // else the witness process environment.
+    const values = identity !== null && identity.seat === name ? identity.values : null;
+    if (auth.kind === 'bearer') {
+        const bearer = seat;
+        if (typeof bearer.tokenEnv !== 'string') {
+            throw new KitAuthError(`auth seat '${name}' must declare tokenEnv (a witness env var)`);
+        }
+        return { kind: 'bearer', name, bearer, values };
+    }
+    const login = seat;
+    if (typeof login.loginPath !== 'string' || typeof login.credentials !== 'object') {
+        throw new KitAuthError(`auth seat '${name}' must declare loginPath and credentials (field -> witness env var)`);
+    }
+    return { kind: 'cookie-login', name, login, values };
+}
+/**
+ * The credential header one GET carries, logging in first when needed.
+ *
+ * The values come from the session's REGISTERED identity when it named
+ * this seat (every declared variable must be present — a partial
+ * identity fails closed instead of completing itself from the
+ * process-global seat), otherwise from the witness process environment
+ * exactly as before. Either way a diagnostic names the variables, never
+ * their values.
+ *
+ * Args:
+ *   seat: the resolved seat.
+ *   seatKey: session cache key.
+ *   baseUrl: the adapter base the read targets.
+ *   sessions: this kit's session store.
+ *
+ * Returns:
+ *   Promise<Record<string, string>>: headers to merge into the read.
+ * @throws KitAuthError when credentials are absent or login is rejected.
+ */
+async function credentialHeaders(seat, seatKey, baseUrl, sessions) {
+    // Credentials are read from the witness process environment, never
+    // from the repo, argv, or the suite — and a seat that cannot be
+    // satisfied is named by its env vars, never by a bare 401 later.
+    const config = seat.kind === 'bearer' ? seat.bearer : seat.login;
+    const envVars = 'tokenEnv' in config ? [config.tokenEnv] : Object.values(config.credentials);
+    const identity = seat.values;
+    const valueOf = (name) => (identity === null ? undefined : identity[name]) ?? process.env[name];
+    const missing = envVars.filter((name) => {
+        const value = valueOf(name);
+        return value === undefined || value === '';
+    });
+    if (missing.length > 0) {
+        throw new KitAuthError(identity === null
+            ? `adapter seat '${seat.name}' needs ${missing.join(', ')} in the WITNESS process ` +
+                'environment (never in the repo, argv, or the suite)'
+            : `session identity for seat '${seat.name}' is missing ${missing.join(', ')}: a ` +
+                'registered identity must carry EVERY credential the seat declares', { seat: seat.name, envVars: missing });
+    }
+    if ('tokenEnv' in config) {
+        const scheme = config.scheme ?? 'Bearer';
+        return { authorization: `${scheme} ${String(valueOf(config.tokenEnv))}` };
+    }
+    const login = config;
+    const cached = sessions.get(seatKey);
+    if (cached?.cookie != null)
+        return { cookie: cached.cookie };
+    const body = {};
+    for (const [field, envVar] of Object.entries(login.credentials)) {
+        body[field] = String(valueOf(envVar));
+    }
+    const response = await fetch(`${baseUrl}${login.loginPath}`, {
+        method: 'POST',
+        headers: {
+            accept: 'application/json',
+            'content-type': 'application/json',
+            ...(login.headers ?? {}),
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        throw new KitAuthError(`adapter seat '${seat.name}' login failed: POST ${login.loginPath} -> ${String(response.status)}`);
+    }
+    const cookies = typeof response.headers.getSetCookie === 'function'
+        ? response.headers.getSetCookie()
+        : [response.headers.get('set-cookie') ?? ''];
+    const pairs = cookies
+        .flatMap((header) => header.split(/,(?=\s*[^;=]+=[^;]*)/))
+        .map((header) => header.split(';')[0]?.trim() ?? '')
+        .filter((pair) => pair.includes('='));
+    const wanted = pairs.filter((pair) => {
+        const name = pair.slice(0, pair.indexOf('='));
+        return login.cookieName === undefined || name === login.cookieName;
+    });
+    if (wanted.length === 0) {
+        throw new KitAuthError(`adapter seat '${seat.name}' login set no ${login.cookieName === undefined ? '' : `'${login.cookieName}' `}cookie`);
+    }
+    const cookie = wanted.join('; ');
+    sessions.set(seatKey, { authorization: null, cookie });
+    return { cookie };
+}
+/**
+ * Builds the kit's GET transport for one adapter invocation.
+ *
+ * Args:
+ *   options: declared auth, resource id, and the witness context.
+ *
+ * Returns:
+ *   (path: string) => Promise<KitGetResult>: one read, login included.
+ * @throws KitAuthError on missing/rejected credentials; KitRedirectError
+ *   when the app answers the read with a redirect (a read that only
+ *   works through a redirect is never a stable evidence path).
+ */
+export function createSessionReader(options) {
+    const { auth, resourceId, ctx } = options;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const baseUrl = ctx.baseUrl.replace(/\/$/, '');
+    const identity = ctx.sessionIdentity ?? null;
+    const seat = auth === undefined || auth.kind === 'none' ? null : resolveSeat(auth, identity);
+    // The cache key carries the seat AND the session it was read under: a
+    // cookie logged in as one session's identity is never served to
+    // another session's read, even through the same adapter instance.
+    const seatKey = `${baseUrl}|${seat?.name ?? ''}|${identity === null ? 'env' : `session:${ctx.sessionId ?? 'unattributed'}`}`;
+    // One store per kit adapter: the first read logs in, later reads
+    // reuse the session until the app rejects it with 401.
+    const sessions = options.sessions ?? new Map();
+    /**
+     * Issues one GET and parses its JSON body.
+     *
+     * Args:
+     *     path: absolute path (with query) to read.
+     *     credential: credential headers to attach.
+     *
+     *   Returns:
+     *     Promise<KitGetResult>: status, headers, parsed body.
+     * @throws KitRedirectError when the app answers with a redirect.
+     */
+    const getOnce = async (path, credential) => {
+        const response = await fetch(`${baseUrl}${path}`, {
+            // A read that only works through a redirect is not a stable
+            // evidence path: never follow one silently (E28).
+            redirect: 'manual',
+            headers: {
+                accept: 'application/json',
+                ...(ctx.headers ?? {}),
+                ...credential,
+            },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        const body = await response
+            .json()
+            .catch(() => undefined);
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get('location');
+            throw new KitRedirectError(`${resourceId}: GET ${path} answered ${String(response.status)}${location === null ? '' : ` -> ${location}`}; a read that only works through a redirect is not a stable evidence path — point ` +
+                'readPath/listPath at the path the app finally serves');
+        }
+        return { status: response.status, headers: response.headers, body };
+    };
+    if (seat === null) {
+        return async (path) => getOnce(path, {});
+    }
+    return async (path) => {
+        let credential = await credentialHeaders(seat, seatKey, baseUrl, sessions);
+        let result = await getOnce(path, credential);
+        if (result.status === 401) {
+            // One re-login, one retry: an expired session must not become a loop.
+            sessions.delete(seatKey);
+            credential = await credentialHeaders(seat, seatKey, baseUrl, sessions);
+            result = await getOnce(path, credential);
+        }
+        return result;
+    };
+}
+//# sourceMappingURL=session.js.map

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

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