@nifrajs/core 2.9.0 → 2.10.0

package/README.md

@@ -4,6 +4,11 @@ The Bun-native, contract-first HTTP framework at the heart of [nifra](../../READ
 a radix router, a fully type-inferred server, versionable contracts, lifecycle
 middleware, and production hardening.
 
+The Web-standard app can be wrapped for Vercel Edge with `toVercelHandler`, Netlify Functions with
+`toNetlifyHandler`, or API Gateway v1/v2 with `toLambdaHandler` from `@nifrajs/core/server`. These are
+thin event-envelope adapters; application policy, persistence, and platform credentials stay outside
+the core.
+
 ```sh
 bun add @nifrajs/core
 ```
@@ -26,6 +31,8 @@ available only from their explicit subpaths, so an ordinary HTTP server never ev
 import { defineContract, implement } from "@nifrajs/core/contract"
 import { startCausality } from "@nifrajs/core/causality"
 import { defineAssurancePolicy } from "@nifrajs/core/assurance"
+import { createDataPort, defineDataContract, diffDataContract } from "@nifrajs/core/data"
+import { defineChannel, memoryChannelHub } from "@nifrajs/core/channel"
 ```
 
 - **Inline or contract-first.** Write routes inline (types inferred from the
@@ -75,6 +82,16 @@ import { defineAssurancePolicy } from "@nifrajs/core/assurance"
   bounded HTTP representations and supplies the same frame/loader adapters for WebSockets and
   deferred data. Import `richWireCodec()` from `@nifrajs/core/transport-codec-rich`; the separate
   subpath keeps rich-wire code out of plain JSON bundles.
+- **Typed data seam (opt in).** `@nifrajs/core/data` defines token-only operation contracts,
+  `db.read`/`db.write` capability names, an opaque request-local `RlsScope`, typed adapter requests,
+  drift snapshots, and `createDataPort(contract, adapter, { beacon: useCapability })`, which emits the
+  operation's capability evidence - derived from the contract, never from the request - before the
+  private adapter runs. It contains no database driver, tenant identity, policy, row values, or durable
+  store; those belong in the adapter layer.
+- **Typed channels (opt in).** `@nifrajs/core/channel` defines typed message contracts, bounded
+  subscriptions, cancellation, per-channel resume cursors, bounded local replay, and a process-local
+  in-memory hub for tests. Durable replay, presence, rooms, and multi-instance fan-out remain adapter
+  concerns.
 
 ```ts
 import { defineAssurancePolicy, evaluateRouteAssurance, NIFRA_ASSURANCE } from "@nifrajs/core/assurance"

package/dist/channel.d.ts

@@ -0,0 +1,52 @@
+/** Typed, runtime-neutral channel contracts. Durable replay, presence, fan-out, and tenant-aware
+ * routing belong in an adapter; the bundled hub provides only bounded process-local replay for tests
+ * and local development. */
+export interface ChannelContract<Name extends string, Message> {
+    readonly name: Name;
+    /** Type-only message witness; adapters never materialize it. */
+    readonly __message?: (value: Message) => Message;
+}
+export interface ChannelEvent<Message> {
+    /** Monotonic within one channel; adapters may use a different opaque cursor representation. */
+    readonly sequence: number;
+    readonly resumeToken: string;
+    readonly data: Message;
+}
+export type ChannelCloseReason = "closed" | "backpressure" | "aborted";
+export interface ChannelSubscription<Message> extends AsyncIterableIterator<ChannelEvent<Message>> {
+    readonly channel: string;
+    readonly closed: boolean;
+    readonly closeReason: ChannelCloseReason | undefined;
+    readonly resumeToken: string | undefined;
+    close(): void;
+}
+export interface ChannelSubscribeOptions {
+    /** Maximum undelivered events retained for this subscriber. Default 64. */
+    readonly maxQueue?: number;
+    /** Resume after this opaque cursor. The adapter must fail closed when the cursor is unavailable. */
+    readonly resumeFrom?: string;
+    readonly signal?: AbortSignal;
+}
+export interface ChannelHub {
+    subscribe<Name extends string, Message>(channel: ChannelContract<Name, Message>, options?: ChannelSubscribeOptions): ChannelSubscription<Message>;
+    publish<Name extends string, Message>(channel: ChannelContract<Name, Message>, data: Message): ChannelEvent<Message>;
+}
+export interface MemoryChannelHubOptions {
+    /** Default queue bound per subscriber. Default 64. */
+    readonly maxQueue?: number;
+    /** Maximum events retained per channel for local cursor replay. Default: the queue bound. */
+    readonly historySize?: number;
+}
+/** A requested cursor is malformed, belongs to another channel, or fell outside retained history. */
+export declare class ChannelResumeUnavailableError extends Error {
+    readonly channel: string;
+    readonly resumeToken: string;
+    constructor(channel: string, resumeToken: string);
+}
+/** Define a typed channel name. Message types are erased; adapters own validation at their boundary. */
+export declare function defineChannel<Name extends string, Message>(name: Name): ChannelContract<Name, Message>;
+/** A bounded in-memory hub suitable for tests and local development, never for durable fan-out. */
+export declare function memoryChannelHub(options?: MemoryChannelHubOptions): ChannelHub;
+/** Adapt a channel subscription to a cancellable Web stream for SSE/HTTP adapters. */
+export declare function channelReadableStream<Message>(subscription: ChannelSubscription<Message>): ReadableStream<ChannelEvent<Message>>;
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA;;4BAE4B;AAE5B,MAAM,WAAW,eAAe,CAAC,IAAI,SAAS,MAAM,EAAE,OAAO;IAC3D,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,gEAAgE;IAChE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;CACjD;AAED,MAAM,WAAW,YAAY,CAAC,OAAO;IACnC,+FAA+F;IAC/F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,cAAc,GAAG,SAAS,CAAA;AAEtE,MAAM,WAAW,mBAAmB,CAAC,OAAO,CAAE,SAAQ,qBAAqB,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IAChG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,WAAW,EAAE,kBAAkB,GAAG,SAAS,CAAA;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,KAAK,IAAI,IAAI,CAAA;CACd;AAED,MAAM,WAAW,uBAAuB;IACtC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,oGAAoG;IACpG,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,IAAI,SAAS,MAAM,EAAE,OAAO,EACpC,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,EACvC,OAAO,CAAC,EAAE,uBAAuB,GAChC,mBAAmB,CAAC,OAAO,CAAC,CAAA;IAC/B,OAAO,CAAC,IAAI,SAAS,MAAM,EAAE,OAAO,EAClC,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,EACvC,IAAI,EAAE,OAAO,GACZ,YAAY,CAAC,OAAO,CAAC,CAAA;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,6FAA6F;IAC7F,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,qGAAqG;AACrG,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;gBAEhB,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAMjD;AAMD,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,IAAI,SAAS,MAAM,EAAE,OAAO,EACxD,IAAI,EAAE,IAAI,GACT,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAGhC;AAqGD,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,UAAU,CAmGlF;AAED,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,OAAO,EAC3C,YAAY,EAAE,mBAAmB,CAAC,OAAO,CAAC,GACzC,cAAc,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAgBvC"}

package/dist/channel.js

@@ -0,0 +1,231 @@
+/** Typed, runtime-neutral channel contracts. Durable replay, presence, fan-out, and tenant-aware
+ * routing belong in an adapter; the bundled hub provides only bounded process-local replay for tests
+ * and local development. */
+/** A requested cursor is malformed, belongs to another channel, or fell outside retained history. */
+export class ChannelResumeUnavailableError extends Error {
+    channel;
+    resumeToken;
+    constructor(channel, resumeToken) {
+        super("channel: resume cursor is unavailable");
+        this.name = "ChannelResumeUnavailableError";
+        this.channel = channel;
+        this.resumeToken = resumeToken;
+    }
+}
+function validName(name) {
+    return /^[A-Za-z][A-Za-z0-9._:/-]{0,127}$/.test(name);
+}
+/** Define a typed channel name. Message types are erased; adapters own validation at their boundary. */
+export function defineChannel(name) {
+    if (!validName(name))
+        throw new TypeError("channel: name must be a bounded token");
+    return Object.freeze({ name });
+}
+class MemorySubscription {
+    channel;
+    maxQueue;
+    remove;
+    queue = [];
+    waiters = [];
+    isClosed = false;
+    reason;
+    lastToken;
+    abortSignal;
+    abortHandler;
+    constructor(channel, maxQueue, remove) {
+        this.channel = channel;
+        this.maxQueue = maxQueue;
+        this.remove = remove;
+    }
+    seed(events) {
+        if (events.length > this.maxQueue) {
+            throw new RangeError("channel: resume history exceeds subscriber queue bound");
+        }
+        this.queue.push(...events);
+    }
+    attachSignal(signal) {
+        if (signal === undefined || this.isClosed)
+            return;
+        const handler = () => this.close("aborted");
+        this.abortSignal = signal;
+        this.abortHandler = handler;
+        signal.addEventListener("abort", handler, { once: true });
+        // Check after registration as well: an abort can happen between the initial caller check and
+        // listener registration in host implementations. `close()` removes the listener again.
+        if (signal.aborted)
+            this.close("aborted");
+    }
+    get closed() {
+        return this.isClosed;
+    }
+    get closeReason() {
+        return this.reason;
+    }
+    get resumeToken() {
+        return this.lastToken;
+    }
+    push(event) {
+        if (this.isClosed)
+            return;
+        const waiter = this.waiters.shift();
+        if (waiter !== undefined) {
+            this.lastToken = event.resumeToken;
+            waiter({ done: false, value: event });
+            return;
+        }
+        if (this.queue.length >= this.maxQueue) {
+            this.close("backpressure");
+            return;
+        }
+        this.queue.push(event);
+    }
+    next() {
+        const event = this.queue.shift();
+        if (event !== undefined) {
+            this.lastToken = event.resumeToken;
+            return Promise.resolve({ done: false, value: event });
+        }
+        if (this.isClosed)
+            return Promise.resolve({ done: true, value: undefined });
+        return new Promise((resolve) => this.waiters.push(resolve));
+    }
+    return() {
+        this.close("closed");
+        return Promise.resolve({ done: true, value: undefined });
+    }
+    close(reason = "closed") {
+        if (this.isClosed)
+            return;
+        this.isClosed = true;
+        this.reason = reason;
+        this.queue.length = 0;
+        if (this.abortSignal !== undefined && this.abortHandler !== undefined) {
+            this.abortSignal.removeEventListener("abort", this.abortHandler);
+            this.abortSignal = undefined;
+            this.abortHandler = undefined;
+        }
+        this.remove();
+        for (const waiter of this.waiters.splice(0))
+            waiter({ done: true, value: undefined });
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}
+/** A bounded in-memory hub suitable for tests and local development, never for durable fan-out. */
+export function memoryChannelHub(options = {}) {
+    const maxQueue = options.maxQueue ?? 64;
+    if (!Number.isSafeInteger(maxQueue) || maxQueue < 1) {
+        throw new RangeError("channel: maxQueue must be a positive safe integer");
+    }
+    const historySize = options.historySize ?? maxQueue;
+    if (!Number.isSafeInteger(historySize) || historySize < 0) {
+        throw new RangeError("channel: historySize must be a non-negative safe integer");
+    }
+    const subscribers = new Map();
+    const sequences = new Map();
+    const history = new Map();
+    const tokenFor = (channel, sequence) => `${channel}:${sequence.toString(36)}`;
+    const sequenceOf = (channel, token) => {
+        const prefix = `${channel}:`;
+        if (!token.startsWith(prefix))
+            return undefined;
+        const digits = token.slice(prefix.length);
+        if (!/^[0-9a-z]+$/.test(digits))
+            return undefined;
+        const sequence = Number.parseInt(digits, 36);
+        return Number.isSafeInteger(sequence) && sequence > 0 ? sequence : undefined;
+    };
+    return {
+        subscribe(channel, subscriptionOptions = {}) {
+            const queue = subscriptionOptions.maxQueue ?? maxQueue;
+            if (!Number.isSafeInteger(queue) || queue < 1) {
+                throw new RangeError("channel: maxQueue must be a positive safe integer");
+            }
+            const currentSequence = sequences.get(channel.name) ?? 0;
+            const resumeFrom = subscriptionOptions.resumeFrom;
+            let replay = [];
+            if (resumeFrom !== undefined) {
+                const requestedSequence = sequenceOf(channel.name, resumeFrom);
+                const channelHistory = history.get(channel.name) ?? [];
+                const oldest = channelHistory[0]?.sequence;
+                const known = requestedSequence !== undefined &&
+                    requestedSequence <= currentSequence &&
+                    (requestedSequence === currentSequence ||
+                        channelHistory.some((event) => event.sequence === requestedSequence));
+                if (!known)
+                    throw new ChannelResumeUnavailableError(channel.name, resumeFrom);
+                replay = channelHistory.filter((event) => event.sequence > requestedSequence);
+                // Keep this explicit so a future history representation cannot silently truncate a resume.
+                if (oldest !== undefined && requestedSequence < oldest && replay.length === 0) {
+                    throw new ChannelResumeUnavailableError(channel.name, resumeFrom);
+                }
+                if (replay.length > queue) {
+                    throw new ChannelResumeUnavailableError(channel.name, resumeFrom);
+                }
+            }
+            let members = subscribers.get(channel.name);
+            if (members === undefined) {
+                members = new Set();
+                subscribers.set(channel.name, members);
+            }
+            let subscription;
+            const remove = () => {
+                members?.delete(subscription);
+                if (members?.size === 0)
+                    subscribers.delete(channel.name);
+            };
+            subscription = new MemorySubscription(channel.name, queue, remove);
+            subscription.seed(replay);
+            members.add(subscription);
+            subscription.attachSignal(subscriptionOptions.signal);
+            return subscription;
+        },
+        publish(channel, data) {
+            const previous = sequences.get(channel.name) ?? 0;
+            if (previous === Number.MAX_SAFE_INTEGER) {
+                throw new RangeError("channel: sequence space exhausted");
+            }
+            const sequence = previous + 1;
+            sequences.set(channel.name, sequence);
+            const event = {
+                sequence,
+                resumeToken: tokenFor(channel.name, sequence),
+                data,
+            };
+            if (historySize > 0) {
+                const channelHistory = history.get(channel.name) ?? [];
+                channelHistory.push(event);
+                if (channelHistory.length > historySize)
+                    channelHistory.shift();
+                history.set(channel.name, channelHistory);
+            }
+            for (const subscriber of subscribers.get(channel.name) ?? []) {
+                subscriber.push(event);
+            }
+            return event;
+        },
+    };
+}
+/** Adapt a channel subscription to a cancellable Web stream for SSE/HTTP adapters. */
+export function channelReadableStream(subscription) {
+    const iterator = subscription[Symbol.asyncIterator]();
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                const result = await iterator.next();
+                if (result.done)
+                    controller.close();
+                else
+                    controller.enqueue(result.value);
+            }
+            catch (error) {
+                controller.error(error);
+            }
+        },
+        cancel() {
+            subscription.close();
+        },
+    });
+}
+//# sourceMappingURL=channel.js.map

package/dist/channel.js.map

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

package/dist/data.d.ts

@@ -0,0 +1,117 @@
+/** Public, token-only data access contracts. Durable adapters and RLS policy enforcement stay outside
+ * this package; this subpath defines the typed seam they implement. */
+export declare const DATA_CAPABILITIES: Readonly<{
+    readonly read: "db.read";
+    readonly write: "db.write";
+}>;
+export type DataAccess = keyof typeof DATA_CAPABILITIES;
+export type DataCapability = (typeof DATA_CAPABILITIES)[DataAccess];
+export interface DataOperationSpec {
+    readonly access: DataAccess;
+    readonly input?: unknown;
+    readonly output?: unknown;
+}
+export type DataOperationMap = Readonly<Record<string, DataOperationSpec>>;
+export interface DataContract<Operations extends DataOperationMap = DataOperationMap> {
+    readonly version: string;
+    readonly operations: Operations;
+}
+/** Opaque request-local RLS (or equivalent data-policy) scope passed to an adapter. */
+export interface RlsScope {
+    /** Caller-owned scope token. The public seam never interprets, logs, or derives identity from it. */
+    readonly token: string;
+    /** Optional opaque digest for correlating a scope without exposing tenant or subject data. */
+    readonly digest?: string;
+}
+/** Backward-compatible name for the request scope carried by every data operation. */
+export type DataScope = RlsScope;
+export interface DataRequest<Operation extends string = string, Input = unknown> {
+    readonly operation: Operation;
+    readonly scope: DataScope;
+    readonly capability: DataCapability;
+    readonly input: Input;
+}
+export interface DataDrift {
+    readonly kind: "version" | "added" | "removed" | "access-changed";
+    readonly operation?: string;
+    readonly declaredAccess?: DataAccess;
+    readonly observedAccess?: DataAccess;
+    readonly declaredVersion?: string;
+    readonly observedVersion?: string;
+}
+type InputOf<Operation> = Operation extends {
+    readonly input: infer Input;
+} ? Input : never;
+type OutputOf<Operation> = Operation extends {
+    readonly output: infer Output;
+} ? Output : unknown;
+type CapabilityOf<Operation> = Operation extends {
+    readonly access: "read";
+} ? typeof DATA_CAPABILITIES.read : Operation extends {
+    readonly access: "write";
+} ? typeof DATA_CAPABILITIES.write : DataCapability;
+type InputField<Input> = [Input] extends [never] ? {
+    readonly input?: never;
+} : {
+    readonly input: Input;
+};
+export type DataInput<Contract extends DataContract, Operation extends keyof Contract["operations"] & string> = Contract["operations"][Operation] extends infer Definition ? InputOf<Definition> : never;
+export type DataOutput<Contract extends DataContract, Operation extends keyof Contract["operations"] & string> = Contract["operations"][Operation] extends infer Definition ? OutputOf<Definition> : unknown;
+export type DataRequestFor<Contract extends DataContract, Operation extends keyof Contract["operations"] & string> = {
+    readonly operation: Operation;
+    readonly scope: DataScope;
+    readonly capability: CapabilityOf<Contract["operations"][Operation]>;
+} & InputField<DataInput<Contract, Operation>>;
+export interface TypedDataPort<Contract extends DataContract> {
+    execute<Operation extends keyof Contract["operations"] & string>(request: DataRequestFor<Contract, Operation>): Promise<DataOutput<Contract, Operation>>;
+}
+/** Runtime capability beacon used by a request-bound data port. */
+export type DataCapabilityBeacon = (context: object, capability: DataCapability) => void;
+/** Options for the public request-bound data port wrapper. */
+export interface DataPortOptions {
+    /** Usually `useCapability` from `@nifrajs/core/capabilities`. */
+    readonly beacon?: DataCapabilityBeacon;
+}
+/** A data port bound to one request context; every operation emits capability evidence first. */
+export interface BoundDataPort<Contract extends DataContract> extends TypedDataPort<Contract> {
+}
+/** Public factory for wiring a private data adapter into Nifra's capability evidence chain. */
+export interface DataPort<Contract extends DataContract> {
+    for(context: object): BoundDataPort<Contract>;
+}
+/**
+ * Bind a private data adapter to request-local capability evidence.
+ *
+ * The adapter remains responsible for RLS enforcement and durable storage. This wrapper owns the
+ * framework-side proof boundary: it emits exactly the operation's typed `db.read`/`db.write` token
+ * before invoking the adapter, and refuses to run when no beacon is configured or the beacon denies
+ * the operation. The context is never copied into the request or retained by the port.
+ *
+ * The emitted token is derived from the **contract**, never from `request.capability`. The typed
+ * request narrows that field, but types are erased before this line runs, and a request assembled
+ * from decoded input would otherwise let a write operation announce itself as `db.read` - evidence
+ * that names the wrong capability is worse than no evidence, because the ledger looks satisfied. An
+ * unknown operation, or a declared capability that disagrees with the contract, fails closed.
+ */
+export declare function createDataPort<Contract extends DataContract>(contract: Contract, adapter: TypedDataPort<Contract>, options?: DataPortOptions): DataPort<Contract>;
+/** Create a bounded, opaque RLS/equivalent policy scope for a data adapter. */
+export declare function rlsScope(token: string, digest?: string): RlsScope;
+/** Backward-compatible constructor for {@link RlsScope}. */
+export declare function dataScope(token: string, digest?: string): DataScope;
+/** Define and freeze a token-only data contract. Input/output types are erased at runtime. */
+export declare function defineDataContract<const Operations extends DataOperationMap>(input: {
+    readonly version: string;
+    readonly operations: Operations;
+}): DataContract<Operations>;
+export interface DataContractSnapshot {
+    readonly version: string;
+    readonly operations: Readonly<Record<string, {
+        readonly access: DataAccess;
+    }>>;
+}
+/** Strip a contract to its token-only version/access snapshot for CI or adapter drift checks. */
+export declare function snapshotDataContract(contract: DataContract): DataContractSnapshot;
+/** Compare a declared contract with an adapter-observed token-only snapshot. */
+export declare function diffDataContract(declared: DataContract, observed: DataContractSnapshot | DataContract): readonly DataDrift[];
+export {};
+//# sourceMappingURL=data.d.ts.map

package/dist/data.d.ts.map

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

package/dist/data.js

@@ -0,0 +1,163 @@
+/** Public, token-only data access contracts. Durable adapters and RLS policy enforcement stay outside
+ * this package; this subpath defines the typed seam they implement. */
+export const DATA_CAPABILITIES = Object.freeze({
+    read: "db.read",
+    write: "db.write",
+});
+/**
+ * Bind a private data adapter to request-local capability evidence.
+ *
+ * The adapter remains responsible for RLS enforcement and durable storage. This wrapper owns the
+ * framework-side proof boundary: it emits exactly the operation's typed `db.read`/`db.write` token
+ * before invoking the adapter, and refuses to run when no beacon is configured or the beacon denies
+ * the operation. The context is never copied into the request or retained by the port.
+ *
+ * The emitted token is derived from the **contract**, never from `request.capability`. The typed
+ * request narrows that field, but types are erased before this line runs, and a request assembled
+ * from decoded input would otherwise let a write operation announce itself as `db.read` - evidence
+ * that names the wrong capability is worse than no evidence, because the ledger looks satisfied. An
+ * unknown operation, or a declared capability that disagrees with the contract, fails closed.
+ */
+export function createDataPort(contract, adapter, options = {}) {
+    if (contract === null || typeof contract !== "object" || contract.operations === undefined) {
+        throw new TypeError("data: contract must be a defineDataContract result");
+    }
+    if (adapter === null || typeof adapter !== "object" || typeof adapter.execute !== "function") {
+        throw new TypeError("data: adapter must implement execute(request)");
+    }
+    function bind(context) {
+        if (context === null || typeof context !== "object") {
+            throw new TypeError("data: context must be an object");
+        }
+        const beacon = options.beacon;
+        if (beacon === undefined) {
+            throw new Error("@nifrajs/core/data: for(context) needs a beacon - pass `beacon: useCapability` to createDataPort");
+        }
+        return Object.freeze({
+            execute(request) {
+                const declared = contract.operations[request.operation];
+                if (declared === undefined || !isDataAccess(declared.access)) {
+                    return Promise.reject(new TypeError(`data: ${String(request.operation)} is not declared by this contract`));
+                }
+                const capability = DATA_CAPABILITIES[declared.access];
+                if (request.capability !== capability) {
+                    return Promise.reject(new TypeError(`data: ${String(request.operation)} requires ${capability}`));
+                }
+                try {
+                    beacon(context, capability);
+                }
+                catch (error) {
+                    return Promise.reject(error);
+                }
+                return adapter.execute(request);
+            },
+        });
+    }
+    return Object.freeze({ for: bind });
+}
+function assertToken(value, label) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > 256 ||
+        hasControlCharacter(value)) {
+        throw new TypeError(`data: ${label} must be a bounded opaque token`);
+    }
+    return value;
+}
+function hasControlCharacter(value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code <= 31 || code === 127)
+            return true;
+    }
+    return false;
+}
+/** Create a bounded, opaque RLS/equivalent policy scope for a data adapter. */
+export function rlsScope(token, digest) {
+    const scope = {
+        token: assertToken(token, "scope token"),
+        ...(digest === undefined ? {} : { digest: assertToken(digest, "scope digest") }),
+    };
+    return Object.freeze(scope);
+}
+/** Backward-compatible constructor for {@link RlsScope}. */
+export function dataScope(token, digest) {
+    return rlsScope(token, digest);
+}
+function isDataAccess(value) {
+    return value === "read" || value === "write";
+}
+function validVersion(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= 128 &&
+        !hasControlCharacter(value));
+}
+function validOperationName(value) {
+    return /^[A-Za-z][A-Za-z0-9._-]{0,127}$/.test(value);
+}
+/** Define and freeze a token-only data contract. Input/output types are erased at runtime. */
+export function defineDataContract(input) {
+    if (!validVersion(input.version))
+        throw new TypeError("data: version must be a bounded token");
+    if (input.operations === null || typeof input.operations !== "object") {
+        throw new TypeError("data: operations must be an object");
+    }
+    const operations = {};
+    for (const [name, operation] of Object.entries(input.operations)) {
+        if (!validOperationName(name))
+            throw new TypeError(`data: invalid operation name ${name}`);
+        if (operation === null || typeof operation !== "object" || !isDataAccess(operation.access)) {
+            throw new TypeError(`data: ${name} must declare read or write access`);
+        }
+        // `input` and `output` are type witnesses only. Never retain runtime schemas, defaults, or
+        // caller-owned values in the public contract object; adapters receive only token metadata.
+        operations[name] = Object.freeze({ access: operation.access });
+    }
+    return Object.freeze({
+        version: input.version,
+        operations: Object.freeze(operations),
+    });
+}
+/** Strip a contract to its token-only version/access snapshot for CI or adapter drift checks. */
+export function snapshotDataContract(contract) {
+    const operations = {};
+    for (const [name, operation] of Object.entries(contract.operations)) {
+        if (isDataAccess(operation.access))
+            operations[name] = { access: operation.access };
+    }
+    return Object.freeze({ version: contract.version, operations: Object.freeze(operations) });
+}
+/** Compare a declared contract with an adapter-observed token-only snapshot. */
+export function diffDataContract(declared, observed) {
+    const left = snapshotDataContract(declared);
+    const right = "operations" in observed ? snapshotDataContract(observed) : observed;
+    const drift = [];
+    if (left.version !== right.version) {
+        drift.push({
+            kind: "version",
+            declaredVersion: left.version,
+            observedVersion: right.version,
+        });
+    }
+    for (const [name, operation] of Object.entries(left.operations)) {
+        const candidate = right.operations[name];
+        if (candidate === undefined) {
+            drift.push({ kind: "removed", operation: name });
+        }
+        else if (candidate.access !== operation.access) {
+            drift.push({
+                kind: "access-changed",
+                operation: name,
+                declaredAccess: operation.access,
+                observedAccess: candidate.access,
+            });
+        }
+    }
+    for (const [name] of Object.entries(right.operations)) {
+        if (left.operations[name] === undefined)
+            drift.push({ kind: "added", operation: name });
+    }
+    return Object.freeze(drift);
+}
+//# sourceMappingURL=data.js.map

package/dist/data.js.map

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

package/dist/index.d.ts

@@ -9,7 +9,7 @@
  * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and
  * `check:publish` asserts it equals `@nifrajs/core`'s package version.
  */
-export declare const VERSION: "2.9.0";
+export declare const VERSION: "2.10.0";
 export type Version = typeof VERSION;
 export * from "./server.js";
 //# sourceMappingURL=index.d.ts.map