@nifrajs/core 1.10.0 → 1.11.0

package/dist/ledger.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Effect ledger: a per-request, append-only, ordered record of side-effect intents and outcomes.
+ *
+ * Every owned effect seam (a repository write, an external call, an email send) records one entry via
+ * the `useCapability` beacon. The entry type is deliberately **token-only**: capability ids, phase,
+ * an adapter/resource token, dimensionless cost counters, an optional keyed digest, and an error code.
+ * There is no free-form payload field — request bodies, rows, and values cannot enter the ledger, so
+ * redaction holds by construction rather than by filtering. The sealed ledger carries the **route
+ * pattern** (`/users/:id`), never the concrete URL, so path parameters cannot leak either.
+ *
+ * The ledger is the substrate that audit, replay, reconciliation, and cost accounting read.
+ * This module ships the primitive: the entry contract, a bounded per-request ledger with an optional
+ * tamper-evident hash chain, a sink seam, an in-memory sink, and a keyed digest helper. Durable,
+ * encrypted, or retention-managed sinks implement the same {@link LedgerSink} seam externally.
+ */
+/** Lifecycle phase of one effect. `intent` precedes execution; the rest describe its outcome. */
+export type EffectPhase = "intent" | "committed" | "failed" | "compensated";
+/**
+ * Dimensionless resource counters (`{ ms: 12, calls: 1, bytes: 512 }`). Counters carry *how much
+ * resource* an effect consumed; mapping counters to money/pricing is deliberately out of scope here.
+ */
+export type EffectCost = Readonly<Record<string, number>>;
+/** Caller-supplied fields for one entry. Everything else (`seq`, `at`) is assigned by the ledger. */
+export interface EffectEntryInput {
+    /** Capability token (`db.write`, `payments.charge`). Must be a valid capability id. */
+    readonly capability: string;
+    /** Default `"intent"`. Record `committed`/`failed`/`compensated` only after the outcome is known. */
+    readonly phase?: EffectPhase;
+    /** Adapter/resource token (`repo:orders`, `provider:payments`). A token — never a value or a row. */
+    readonly target?: string;
+    /** Dimensionless counters; see {@link EffectCost}. At most {@link MAX_COST_AXES} axes. */
+    readonly cost?: EffectCost;
+    /** Optional keyed-HMAC digest of the effect payload (see {@link computeEffectDigest}); hex, 64 chars. */
+    readonly digest?: string;
+    /** Outcome error as a bounded token code — never a message, never a stack. */
+    readonly error?: {
+        readonly code: string;
+    };
+}
+/** One recorded effect. Frozen; token-only by construction (no payload field exists). */
+export interface EffectEntry {
+    /** Monotonic position within the request (0-based). The replay/simulation order. */
+    readonly seq: number;
+    /** Milliseconds from the ledger's (injectable) clock at append time. */
+    readonly at: number;
+    readonly capability: string;
+    readonly phase: EffectPhase;
+    readonly target?: string;
+    readonly cost?: EffectCost;
+    readonly digest?: string;
+    readonly error?: {
+        readonly code: string;
+    };
+}
+/** Tamper-evidence over the route identity, declarations, and sealed entries. */
+export interface EffectChain {
+    /** `hashes[i]` = SHA-256(hex) over (`hashes[i-1]` + canonical entry `i`). */
+    readonly hashes: readonly string[];
+    /** Last entry hash, or the route-header hash for an empty ledger. Anchor/sign this externally. */
+    readonly head: string;
+}
+/** The immutable result of sealing a request's ledger. Token-only; safe to hand to any sink. */
+export interface SealedEffectLedger {
+    readonly method: string;
+    /** The registered route pattern (`/users/:id`) — never the concrete request URL. */
+    readonly path: string;
+    readonly entries: readonly EffectEntry[];
+    /** The route's declared capability tokens — the runtime-enforcement view: recorded ⊆ declared is
+     * guaranteed by the beacon, and `declared` minus the recorded ids is the unused declaration set. */
+    readonly declared: readonly string[];
+    /** Present when the ledger was created with `chain: true`. */
+    readonly chain?: EffectChain;
+}
+/**
+ * Receives each sealed ledger once per request (only when it has entries). Implementations must not
+ * assume a payload: the ledger is token-only. A durable/tenant-scoped sink lives behind this seam.
+ */
+export type LedgerSink = (ledger: SealedEffectLedger) => void | Promise<void>;
+/** Thrown by `append` when the per-request entry bound is exceeded. Fails the request closed. */
+export declare class EffectLedgerOverflowError extends Error {
+    readonly maxEntries: number;
+    constructor(maxEntries: number);
+}
+/** Thrown by `append` after `seal()` — e.g. an effect attempted while streaming a response body. */
+export declare class EffectLedgerSealedError extends Error {
+    constructor();
+}
+/** Per-request ledger. `append` is synchronous (hot-path safe); `seal` is idempotent and async. */
+export interface RequestLedger {
+    /** Validate, freeze, and record one entry. Throws on invalid input, overflow, or after seal. */
+    append(input: EffectEntryInput): EffectEntry;
+    /** Entries recorded so far (frozen snapshot view). */
+    entries(): readonly EffectEntry[];
+    readonly size: number;
+    readonly sealed: boolean;
+    /** Finalize the ledger (computing the chain when enabled). Idempotent — always the same result. */
+    seal(): Promise<SealedEffectLedger>;
+}
+export interface CreateRequestLedgerOptions {
+    /** HTTP method of the matched route. */
+    readonly method: string;
+    /** The registered route pattern — callers must never pass the concrete request URL. */
+    readonly path: string;
+    /** The route's declared capability tokens, surfaced verbatim on the sealed ledger. Default `[]`. */
+    readonly declared?: readonly string[];
+    /** Entry bound; exceeding it throws {@link EffectLedgerOverflowError}. Default {@link DEFAULT_MAX_ENTRIES}. */
+    readonly maxEntries?: number;
+    /** Compute the tamper-evident hash chain at seal. Default false. */
+    readonly chain?: boolean;
+    /** Injectable monotonic clock (ms) for deterministic tests. Default `performance.now`. */
+    readonly clock?: () => number;
+}
+/** Per-request entry bound. Generous for real handlers, small enough to stop a runaway loop. */
+export declare const DEFAULT_MAX_ENTRIES = 1000;
+/** Most cost axes one entry may carry. */
+export declare const MAX_COST_AXES = 8;
+/** Create a bounded per-request ledger. The server wires one per capability-declaring route. */
+export declare function createRequestLedger(options: CreateRequestLedgerOptions): RequestLedger;
+export interface MemoryLedgerSinkOptions {
+    /** Retain at most this many sealed ledgers (oldest evicted first). Default 1000. */
+    readonly maxLedgers?: number;
+}
+export interface MemoryLedgerSink {
+    readonly sink: LedgerSink;
+    /** Sealed ledgers received so far, oldest first. */
+    readonly ledgers: readonly SealedEffectLedger[];
+    clear(): void;
+}
+/** Bounded in-memory sink for tests and local development. Token-only, like every sink. */
+export declare function createMemoryLedgerSink(options?: MemoryLedgerSinkOptions): MemoryLedgerSink;
+/** Minimum digest key material. A short key would make the keyed digest brute-forceable. */
+export declare const MIN_DIGEST_KEY_BYTES = 16;
+/** Fresh random digest key (32 bytes). Per-process by default — persist one externally to correlate across restarts. */
+export declare function randomEffectDigestKey(): Uint8Array;
+/**
+ * Keyed HMAC-SHA-256 digest (hex) of an effect payload, for replay/reconciliation matching without
+ * storing the payload. Keyed on purpose: a bare hash of low-entropy data (an email, a flag) is
+ * brute-forceable and would itself leak. Digest the **whole** effect payload, never a single field.
+ */
+export declare function computeEffectDigest(key: Uint8Array | CryptoKey, payload: Uint8Array): Promise<string>;
+/** Framework wiring: attach a per-request ledger to a handler context. Not for application code. */
+export declare function attachEffectLedger(context: object, ledger: RequestLedger): void;
+/** The request's effect ledger, when the server enabled one for this route. Read-only access. */
+export declare function effectLedgerOf(context: object): RequestLedger | undefined;
+/** Server-level effect ledger configuration (see `server({ effectLedger })`). */
+export interface EffectLedgerOptions {
+    /** Receives each request's sealed ledger (only when it recorded entries). */
+    readonly sink: LedgerSink;
+    /** Per-request entry bound. Default {@link DEFAULT_MAX_ENTRIES}. */
+    readonly maxEntries?: number;
+    /** Compute the tamper-evident hash chain at seal. Default false. */
+    readonly chain?: boolean;
+}
+//# sourceMappingURL=ledger.d.ts.map

package/dist/ledger.d.ts.map

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

package/dist/ledger.js

@@ -0,0 +1,271 @@
+/**
+ * Effect ledger: a per-request, append-only, ordered record of side-effect intents and outcomes.
+ *
+ * Every owned effect seam (a repository write, an external call, an email send) records one entry via
+ * the `useCapability` beacon. The entry type is deliberately **token-only**: capability ids, phase,
+ * an adapter/resource token, dimensionless cost counters, an optional keyed digest, and an error code.
+ * There is no free-form payload field — request bodies, rows, and values cannot enter the ledger, so
+ * redaction holds by construction rather than by filtering. The sealed ledger carries the **route
+ * pattern** (`/users/:id`), never the concrete URL, so path parameters cannot leak either.
+ *
+ * The ledger is the substrate that audit, replay, reconciliation, and cost accounting read.
+ * This module ships the primitive: the entry contract, a bounded per-request ledger with an optional
+ * tamper-evident hash chain, a sink seam, an in-memory sink, and a keyed digest helper. Durable,
+ * encrypted, or retention-managed sinks implement the same {@link LedgerSink} seam externally.
+ */
+import { validCapabilityId } from "./internal/capability-runtime.js";
+const EFFECT_PHASES = new Set(["intent", "committed", "failed", "compensated"]);
+/** Thrown by `append` when the per-request entry bound is exceeded. Fails the request closed. */
+export class EffectLedgerOverflowError extends Error {
+    maxEntries;
+    constructor(maxEntries) {
+        super(`effect ledger overflow: more than ${maxEntries} entries in one request`);
+        this.maxEntries = maxEntries;
+        this.name = "EffectLedgerOverflowError";
+    }
+}
+/** Thrown by `append` after `seal()` — e.g. an effect attempted while streaming a response body. */
+export class EffectLedgerSealedError extends Error {
+    constructor() {
+        super("effect ledger is sealed: effects cannot be recorded after the response settles");
+        this.name = "EffectLedgerSealedError";
+    }
+}
+/** Per-request entry bound. Generous for real handlers, small enough to stop a runaway loop. */
+export const DEFAULT_MAX_ENTRIES = 1_000;
+/** Most cost axes one entry may carry. */
+export const MAX_COST_AXES = 8;
+const TARGET_MAX_LENGTH = 128;
+const ERROR_CODE = /^[a-z][a-z0-9_.-]{0,63}$/;
+const DIGEST_HEX = /^[0-9a-f]{64}$/;
+function printableToken(value, maxLength) {
+    if (value.length === 0 || value.length > maxLength)
+        return false;
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code < 33 || code > 126)
+            return false;
+    }
+    return true;
+}
+function validateCost(cost) {
+    const keys = Object.keys(cost);
+    if (keys.length > MAX_COST_AXES) {
+        throw new TypeError(`effect ledger: cost carries more than ${MAX_COST_AXES} axes`);
+    }
+    for (const key of keys) {
+        if (!validCapabilityId(key)) {
+            throw new TypeError(`effect ledger: invalid cost axis ${JSON.stringify(key)}`);
+        }
+        const value = cost[key];
+        if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+            throw new TypeError(`effect ledger: cost axis ${key} must be a finite non-negative number`);
+        }
+    }
+    return Object.freeze({ ...cost });
+}
+const defaultClock = () => performance.now();
+class BoundedRequestLedger {
+    items = [];
+    method;
+    path;
+    declared;
+    maxEntries;
+    chain;
+    clock;
+    sealResult;
+    constructor(options) {
+        if (!printableToken(options.method, 16) || !options.path.startsWith("/")) {
+            throw new TypeError("effect ledger: method/path must be a route pattern");
+        }
+        const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+            throw new TypeError("effect ledger: maxEntries must be a positive safe integer");
+        }
+        const declared = options.declared ?? [];
+        for (const id of declared) {
+            if (!validCapabilityId(id)) {
+                throw new TypeError(`effect ledger: invalid declared capability ${JSON.stringify(id)}`);
+            }
+        }
+        this.method = options.method.toUpperCase();
+        this.path = options.path;
+        this.declared = Object.freeze([...declared]);
+        this.maxEntries = maxEntries;
+        this.chain = options.chain ?? false;
+        this.clock = options.clock ?? defaultClock;
+    }
+    get size() {
+        return this.items.length;
+    }
+    get sealed() {
+        return this.sealResult !== undefined;
+    }
+    append(input) {
+        if (this.sealResult !== undefined)
+            throw new EffectLedgerSealedError();
+        if (this.items.length >= this.maxEntries)
+            throw new EffectLedgerOverflowError(this.maxEntries);
+        if (!validCapabilityId(input.capability)) {
+            throw new TypeError(`effect ledger: invalid capability ${JSON.stringify(input.capability)}`);
+        }
+        const phase = input.phase ?? "intent";
+        if (!EFFECT_PHASES.has(phase)) {
+            throw new TypeError(`effect ledger: invalid phase ${JSON.stringify(phase)}`);
+        }
+        if (input.target !== undefined && !printableToken(input.target, TARGET_MAX_LENGTH)) {
+            throw new TypeError("effect ledger: target must be a bounded printable token");
+        }
+        if (input.digest !== undefined && !DIGEST_HEX.test(input.digest)) {
+            throw new TypeError("effect ledger: digest must be 64 lowercase hex characters");
+        }
+        if (input.error !== undefined && !ERROR_CODE.test(input.error.code)) {
+            throw new TypeError("effect ledger: error code must be a bounded lowercase token");
+        }
+        // Only the known token fields are copied — a stray `payload`-like property never survives append.
+        const at = this.clock();
+        if (!Number.isFinite(at) || at < 0) {
+            throw new TypeError("effect ledger: clock must return a finite non-negative number");
+        }
+        const entry = Object.freeze({
+            seq: this.items.length,
+            at,
+            capability: input.capability,
+            phase,
+            ...(input.target !== undefined ? { target: input.target } : {}),
+            ...(input.cost !== undefined ? { cost: validateCost(input.cost) } : {}),
+            ...(input.digest !== undefined ? { digest: input.digest } : {}),
+            ...(input.error !== undefined ? { error: Object.freeze({ code: input.error.code }) } : {}),
+        });
+        this.items.push(entry);
+        return entry;
+    }
+    entries() {
+        return Object.freeze([...this.items]);
+    }
+    seal() {
+        this.sealResult ??= this.sealOnce();
+        return this.sealResult;
+    }
+    async sealOnce() {
+        const entries = Object.freeze([...this.items]);
+        const base = {
+            method: this.method,
+            path: this.path,
+            entries,
+            declared: this.declared,
+        };
+        if (!this.chain)
+            return Object.freeze(base);
+        const hashes = [];
+        // Seed the chain with the route identity and declared authority. Otherwise an anchored entry
+        // chain could be copied onto a different route/declaration without changing its head.
+        let previous = await sha256Hex(JSON.stringify({ method: this.method, path: this.path, declared: [...this.declared].sort() }));
+        for (const entry of entries) {
+            previous = await sha256Hex(`${previous}${canonicalEntry(entry)}`);
+            hashes.push(previous);
+        }
+        return Object.freeze({
+            ...base,
+            chain: Object.freeze({ hashes: Object.freeze(hashes), head: previous }),
+        });
+    }
+}
+/** Create a bounded per-request ledger. The server wires one per capability-declaring route. */
+export function createRequestLedger(options) {
+    return new BoundedRequestLedger(options);
+}
+/** Canonical, key-ordered serialization of one entry — the hash-chain input. */
+function canonicalEntry(entry) {
+    const cost = entry.cost === undefined
+        ? ""
+        : `,"cost":{${Object.keys(entry.cost)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${JSON.stringify(entry.cost[key])}`)
+            .join(",")}}`;
+    return (`{"seq":${entry.seq},"at":${JSON.stringify(entry.at)},"capability":${JSON.stringify(entry.capability)},"phase":${JSON.stringify(entry.phase)}` +
+        `${entry.target !== undefined ? `,"target":${JSON.stringify(entry.target)}` : ""}` +
+        cost +
+        `${entry.digest !== undefined ? `,"digest":${JSON.stringify(entry.digest)}` : ""}` +
+        `${entry.error !== undefined ? `,"error":${JSON.stringify(entry.error.code)}` : ""}}`);
+}
+const encoder = new TextEncoder();
+async function sha256Hex(value) {
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(value)));
+    let hex = "";
+    for (let index = 0; index < digest.length; index++) {
+        hex += digest[index].toString(16).padStart(2, "0");
+    }
+    return hex;
+}
+/** Bounded in-memory sink for tests and local development. Token-only, like every sink. */
+export function createMemoryLedgerSink(options = {}) {
+    const maxLedgers = options.maxLedgers ?? 1_000;
+    if (!Number.isSafeInteger(maxLedgers) || maxLedgers < 1) {
+        throw new TypeError("effect ledger: maxLedgers must be a positive safe integer");
+    }
+    const ledgers = [];
+    return {
+        sink: (ledger) => {
+            ledgers.push(ledger);
+            if (ledgers.length > maxLedgers)
+                ledgers.shift();
+        },
+        get ledgers() {
+            return Object.freeze([...ledgers]);
+        },
+        clear: () => {
+            ledgers.length = 0;
+        },
+    };
+}
+/** Minimum digest key material. A short key would make the keyed digest brute-forceable. */
+export const MIN_DIGEST_KEY_BYTES = 16;
+/** Fresh random digest key (32 bytes). Per-process by default — persist one externally to correlate across restarts. */
+export function randomEffectDigestKey() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return bytes;
+}
+/**
+ * Keyed HMAC-SHA-256 digest (hex) of an effect payload, for replay/reconciliation matching without
+ * storing the payload. Keyed on purpose: a bare hash of low-entropy data (an email, a flag) is
+ * brute-forceable and would itself leak. Digest the **whole** effect payload, never a single field.
+ */
+export async function computeEffectDigest(key, payload) {
+    let cryptoKey;
+    if (key instanceof Uint8Array) {
+        if (key.byteLength < MIN_DIGEST_KEY_BYTES) {
+            throw new TypeError(`effect ledger: digest key must be at least ${MIN_DIGEST_KEY_BYTES} bytes`);
+        }
+        cryptoKey = await crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    }
+    else {
+        const algorithm = key.algorithm;
+        if (algorithm.name !== "HMAC" ||
+            algorithm.hash?.name !== "SHA-256" ||
+            typeof algorithm.length !== "number" ||
+            algorithm.length < MIN_DIGEST_KEY_BYTES * 8 ||
+            !key.usages.includes("sign")) {
+            throw new TypeError("effect ledger: CryptoKey must be an HMAC-SHA-256 signing key of at least 128 bits");
+        }
+        cryptoKey = key;
+    }
+    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", cryptoKey, payload));
+    let hex = "";
+    for (let index = 0; index < mac.length; index++) {
+        hex += mac[index].toString(16).padStart(2, "0");
+    }
+    return hex;
+}
+const EFFECT_LEDGER = Symbol("nifra.effect.ledger");
+/** Framework wiring: attach a per-request ledger to a handler context. Not for application code. */
+export function attachEffectLedger(context, ledger) {
+    ;
+    context[EFFECT_LEDGER] = ledger;
+}
+/** The request's effect ledger, when the server enabled one for this route. Read-only access. */
+export function effectLedgerOf(context) {
+    return context[EFFECT_LEDGER];
+}
+//# sourceMappingURL=ledger.js.map

package/dist/ledger.js.map

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

package/dist/manifest.d.ts

@@ -0,0 +1,81 @@
+/** Deterministic, signed route manifest: contract × assurance × capabilities × classification. */
+import type { AssuranceReport } from "./assurance.js";
+import type { CapabilityAssuranceReport } from "./capabilities.js";
+import { type ResponseClassification } from "./classification.js";
+import { type DiffSeverity, type RouteChange, type RouteSnapshotSchema } from "./diff.js";
+export interface NifraManifestAssurance {
+    readonly rule?: string;
+    readonly evidence: readonly {
+        readonly id: string;
+        readonly source: string;
+    }[];
+}
+export interface NifraManifestCapabilities {
+    readonly declared: readonly string[];
+    readonly evidenced: readonly string[];
+    readonly unproven: readonly string[];
+    readonly covered: boolean;
+}
+export interface NifraManifestRoute {
+    readonly method: string;
+    readonly path: string;
+    readonly schema?: RouteSnapshotSchema;
+    readonly assurance?: NifraManifestAssurance;
+    readonly capabilities?: NifraManifestCapabilities;
+    readonly classification?: ResponseClassification;
+}
+export interface NifraManifest {
+    readonly manifestVersion: 1;
+    readonly routes: readonly NifraManifestRoute[];
+    /** SHA-256 hex of the canonical manifest body (`manifestVersion` + `routes`). */
+    readonly contentHash: string;
+}
+export interface NifraManifestSigner {
+    readonly algorithm: "Ed25519";
+    readonly keyId: string;
+    sign(payload: Uint8Array): ArrayBuffer | Uint8Array | Promise<ArrayBuffer | Uint8Array>;
+}
+export interface NifraManifestSignature {
+    readonly nifraManifestSignature: 1;
+    readonly algorithm: "Ed25519";
+    readonly keyId: string;
+    readonly contentHash: string;
+    /** Base64url Ed25519 signature over the canonical manifest body. */
+    readonly signature: string;
+}
+export interface BuildNifraManifestInput {
+    readonly source: unknown;
+    readonly assurance?: AssuranceReport;
+    readonly capabilities?: CapabilityAssuranceReport;
+}
+/** Canonical bytes are stable across runtime, object-key order, and route registration order. */
+export declare function canonicalManifest(manifest: Pick<NifraManifest, "manifestVersion" | "routes">): string;
+/** Byte-stable artifact serialization (including `contentHash`). */
+export declare function serializeNifraManifest(manifest: NifraManifest): string;
+/** Byte-stable serialization for the detached signature sidecar. */
+export declare function serializeNifraManifestSignature(signature: NifraManifestSignature): string;
+/** Parse the detached sidecar before selecting its operator-controlled public key. */
+export declare function parseNifraManifestSignature(content: string, source?: string): NifraManifestSignature;
+/** Build one fail-closed, deterministic manifest from already-evaluated assurance reports. */
+export declare function buildNifraManifest(input: BuildNifraManifestInput): Promise<NifraManifest>;
+/** Sign without handling private keys: the operator-supplied signer may call KMS/HSM/local WebCrypto. */
+export declare function signNifraManifest(manifest: NifraManifest, signer: NifraManifestSigner): Promise<NifraManifestSignature>;
+/** Verify the hash first, then the detached Ed25519 signature. Malformed/tampered input returns false. */
+export declare function verifyNifraManifestSignature(manifest: NifraManifest, signature: NifraManifestSignature, publicKey: CryptoKey): Promise<boolean>;
+/** Parse and hash-verify an emitted manifest before it is trusted by diff/codegen tooling. */
+export declare function parseNifraManifest(content: string, source?: string): Promise<NifraManifest>;
+export interface NifraManifestChange {
+    readonly severity: DiffSeverity;
+    readonly method: string;
+    readonly path: string;
+    readonly section: RouteChange["section"] | "assurance" | "capabilities" | "classification";
+    readonly field?: string;
+    readonly message: string;
+}
+export interface NifraManifestDiff {
+    readonly changes: readonly NifraManifestChange[];
+    readonly hasBreaking: boolean;
+}
+/** Contract changes reuse the route-diff engine; governance changes fail closed on expanded risk. */
+export declare function diffNifraManifests(before: NifraManifest, after: NifraManifest): NifraManifestDiff;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

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