@blokjs/shared 2.1.0 → 2.2.1

package/dist/GraphContracts.js

@@ -0,0 +1,333 @@
+import { z } from "zod";
+/** Version of the provider-neutral graph contract. */
+export const GRAPH_CONTRACT_VERSION = "1";
+export const GRAPH_RESULT_STATES = [
+    "fresh",
+    "stale",
+    "missing",
+    "truncated",
+    "partial",
+    "unsupported",
+    "conflict",
+];
+export const GRAPH_FRESHNESS_STATES = ["fresh", "stale", "unknown"];
+export const GRAPH_RELATION_KINDS = [
+    "defines",
+    "contains",
+    "calls",
+    "imports",
+    "exports",
+    "references",
+    "extends",
+    "implements",
+    "overrides",
+    "tests",
+];
+export const GRAPH_SYMBOL_KINDS = [
+    "file",
+    "module",
+    "namespace",
+    "class",
+    "interface",
+    "enum",
+    "function",
+    "method",
+    "property",
+    "variable",
+    "type",
+    "unknown",
+];
+export const GRAPH_SEARCH_KINDS = ["symbol", "file", "module", "text"];
+export const GRAPH_INDEX_SOURCES = ["authoritative", "uncommitted-overlay", "provider"];
+export const GRAPH_RELATION_DIRECTIONS = ["inbound", "outbound", "both"];
+export const GRAPH_MAX_STRING_LENGTH = 512;
+export const GRAPH_MAX_PATH_LENGTH = 1024;
+export const GRAPH_MAX_ITEMS = 500;
+export const GRAPH_MAX_FILES_PER_INDEX = 500;
+export const GRAPH_MAX_INDEX_BYTES = 16 * 1024 * 1024;
+export const GRAPH_MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+export const GRAPH_MAX_DEPTH = 32;
+const IDENTIFIER = /^[A-Za-z][A-Za-z0-9._:/-]{0,127}$/;
+const PATH = /^[^\0]{1,1024}$/;
+const DIGEST = /^(sha256):[0-9a-f]{64}$|^(sha512):[0-9a-f]{128}$/i;
+const identifier = z.string().min(1).max(128).regex(IDENTIFIER, "must be a bounded identifier");
+const boundedString = z.string().min(1).max(GRAPH_MAX_STRING_LENGTH);
+const path = z.string().min(1).max(GRAPH_MAX_PATH_LENGTH).regex(PATH, "must be a bounded path");
+const digest = z
+    .string()
+    .max(140)
+    .regex(DIGEST, "must be a sha256: or sha512: digest with the complete hexadecimal length")
+    .transform((value) => value.toLowerCase());
+const timestamp = z.string().min(1).max(64);
+export class GraphContractError extends Error {
+    errors;
+    constructor(errors) {
+        super(`Invalid graph contract: ${errors.join("; ")}`);
+        this.name = "GraphContractError";
+        this.errors = [...errors];
+    }
+}
+const repositoryIdentitySchema = z.object({
+    provider: identifier,
+    id: identifier,
+    revision: boundedString.optional(),
+});
+const worktreeSchema = z.object({
+    id: identifier,
+    branch: boundedString.optional(),
+    commit: boundedString.optional(),
+    dirty: z.boolean().optional(),
+    overlay: z.enum(["clean", "uncommitted", "unknown"]).optional(),
+});
+const contentHashesSchema = z.record(path, digest);
+const scopeSchema = z.object({
+    repository: repositoryIdentitySchema,
+    worktree: worktreeSchema.optional(),
+    commit: boundedString.optional(),
+    contentHashes: contentHashesSchema.optional(),
+});
+const positionSchema = z.object({
+    line: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    column: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
+});
+const rangeSchema = z.object({ start: positionSchema, end: positionSchema.optional() });
+const locationSchema = z.object({
+    path,
+    range: rangeSchema.optional(),
+    language: identifier.optional(),
+    contentHash: digest.optional(),
+});
+const provenanceSchema = z.object({
+    source: z.literal("derived-index"),
+    provider: identifier,
+    providerVersion: boundedString.optional(),
+    indexVersion: boundedString,
+    repository: repositoryIdentitySchema,
+    worktree: worktreeSchema.optional(),
+    commit: boundedString.optional(),
+    contentHash: digest.optional(),
+    path: path.optional(),
+    range: rangeSchema.optional(),
+    indexedAt: timestamp.optional(),
+});
+const freshnessSchema = z.object({
+    state: z.enum(GRAPH_FRESHNESS_STATES),
+    indexedAt: timestamp.optional(),
+    checkedAt: timestamp,
+    indexedCommit: boundedString.optional(),
+    observedCommit: boundedString.optional(),
+    indexedContentHash: digest.optional(),
+    observedContentHash: digest.optional(),
+    reason: boundedString.optional(),
+});
+const resultStatusSchema = z
+    .object({
+    primary: z.enum(GRAPH_RESULT_STATES),
+    states: z.array(z.enum(GRAPH_RESULT_STATES)).min(1).max(GRAPH_RESULT_STATES.length),
+    complete: z.boolean(),
+})
+    .superRefine((value, context) => {
+    if (!value.states.includes(value.primary)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["primary"], message: "primary must be listed in states" });
+    }
+    if (new Set(value.states).size !== value.states.length) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["states"], message: "states must be unique" });
+    }
+    const completeStates = value.states.every((state) => state === "fresh");
+    if (value.complete !== completeStates) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["complete"],
+            message: "complete is true only for a fresh result",
+        });
+    }
+});
+const errorSchema = z.object({
+    code: identifier,
+    category: z.enum([
+        "provider-unavailable",
+        "invalid-query",
+        "not-found",
+        "unsupported",
+        "stale",
+        "conflict",
+        "limit-exceeded",
+        "cancelled",
+        "index-failed",
+        "internal",
+    ]),
+    message: boundedString,
+    retryable: z.boolean(),
+    guidance: z.enum(["reread-authoritative-source", "retry", "narrow-query", "inspect-provider", "none"]),
+    path: path.optional(),
+});
+const symbolSchema = z.object({
+    id: identifier,
+    name: boundedString,
+    kind: z.enum(GRAPH_SYMBOL_KINDS),
+    location: locationSchema,
+    language: identifier.optional(),
+    signature: boundedString.optional(),
+    containerId: identifier.optional(),
+    exported: z.boolean().optional(),
+});
+const relationSchema = z.object({
+    id: identifier,
+    from: identifier,
+    to: identifier,
+    kind: z.enum(GRAPH_RELATION_KINDS),
+    location: locationSchema.optional(),
+});
+const searchHitSchema = z.object({
+    id: identifier,
+    kind: z.enum(GRAPH_SEARCH_KINDS),
+    name: boundedString,
+    score: z.number().finite().min(0).max(1),
+    symbol: symbolSchema.optional(),
+    location: locationSchema.optional(),
+});
+const requestLimit = z.number().int().positive().max(GRAPH_MAX_ITEMS).optional();
+export const GraphRepositoryIdentitySchema = repositoryIdentitySchema;
+export const GraphWorktreeIdentitySchema = worktreeSchema;
+export const GraphScopeSchema = scopeSchema;
+export const GraphRangeSchema = rangeSchema;
+export const GraphLocationSchema = locationSchema;
+export const GraphProvenanceSchema = provenanceSchema;
+export const GraphFreshnessSchema = freshnessSchema;
+export const GraphResultStatusSchema = resultStatusSchema;
+export const GraphErrorSchema = errorSchema;
+export const GraphSymbolSchema = symbolSchema;
+export const GraphRelationSchema = relationSchema;
+export const GraphSearchHitSchema = searchHitSchema;
+export const GraphSearchRequestSchema = z.object({
+    scope: scopeSchema,
+    query: boundedString,
+    kinds: z.array(z.enum(GRAPH_SEARCH_KINDS)).max(GRAPH_SEARCH_KINDS.length).optional(),
+    pathPrefix: path.optional(),
+    limit: requestLimit,
+    cursor: boundedString.optional(),
+});
+export const GraphSymbolRequestSchema = z
+    .object({
+    scope: scopeSchema,
+    symbolId: identifier.optional(),
+    name: boundedString.optional(),
+    path: path.optional(),
+    limit: requestLimit,
+})
+    .refine((value) => value.symbolId !== undefined || value.name !== undefined, "symbolId or name is required");
+export const GraphRelationRequestSchema = z.object({
+    scope: scopeSchema,
+    symbolId: identifier,
+    direction: z.enum(GRAPH_RELATION_DIRECTIONS).optional(),
+    kinds: z.array(z.enum(GRAPH_RELATION_KINDS)).max(GRAPH_RELATION_KINDS.length).optional(),
+    depth: z.number().int().positive().max(GRAPH_MAX_DEPTH).optional(),
+    limit: requestLimit,
+});
+export const GraphImpactRequestSchema = z.object({
+    scope: scopeSchema,
+    symbolId: identifier,
+    direction: z.enum(["inbound", "outbound"]).optional(),
+    relationKinds: z.array(z.enum(GRAPH_RELATION_KINDS)).max(GRAPH_RELATION_KINDS.length).optional(),
+    maxDepth: z.number().int().positive().max(GRAPH_MAX_DEPTH).optional(),
+    limit: requestLimit,
+});
+export const GraphFreshnessRequestSchema = z.object({
+    scope: scopeSchema,
+    paths: z.array(path).max(GRAPH_MAX_ITEMS).optional(),
+});
+export const GraphIndexFileSchema = z.object({
+    path,
+    contentHash: digest,
+    source: z.enum(GRAPH_INDEX_SOURCES).optional(),
+    language: identifier.optional(),
+    symbols: z.array(symbolSchema).max(GRAPH_MAX_ITEMS),
+    relations: z.array(relationSchema).max(GRAPH_MAX_ITEMS),
+});
+export const GraphIndexRequestSchema = z.object({
+    scope: scopeSchema,
+    files: z.array(GraphIndexFileSchema).min(1).max(GRAPH_MAX_FILES_PER_INDEX),
+    indexVersion: boundedString.optional(),
+    reason: z.enum(["initial", "changed-files", "branch-switch", "committed-patch", "manual"]).optional(),
+});
+export const AuthoritativeSourceReadRequestSchema = z.object({
+    scope: scopeSchema,
+    path,
+    expected: z
+        .object({ commit: boundedString.optional(), contentHash: digest.optional() })
+        .refine((value) => value.commit !== undefined || value.contentHash !== undefined, "an expected version is required")
+        .optional(),
+});
+export const AuthoritativeSourceSnapshotSchema = z.object({
+    scope: scopeSchema,
+    path,
+    contentHash: digest,
+    commit: boundedString.optional(),
+    bytes: z.number().int().nonnegative().max(GRAPH_MAX_INDEX_BYTES),
+    content: z.string().max(GRAPH_MAX_INDEX_BYTES),
+});
+const baseResponseSchema = z.object({
+    version: z.literal(GRAPH_CONTRACT_VERSION),
+    authority: z.literal("navigation-only"),
+    status: resultStatusSchema,
+    freshness: freshnessSchema,
+    provenance: provenanceSchema.optional(),
+    errors: z.array(errorSchema).max(GRAPH_MAX_ITEMS),
+    nextCursor: boundedString.optional(),
+});
+function assertRecordSize(value, label, maximum) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch {
+        throw new GraphContractError([`${label} must be JSON-serializable`]);
+    }
+    if (new TextEncoder().encode(serialized).byteLength > maximum) {
+        throw new GraphContractError([`${label} exceeds ${maximum} bytes`]);
+    }
+    return value;
+}
+function parse(schema, value, label) {
+    const result = schema.safeParse(value);
+    if (!result.success) {
+        throw new GraphContractError(result.error.issues.map((issue) => `${label}${issue.path.length > 0 ? `.${issue.path.join(".")}` : ""} ${issue.message}`));
+    }
+    return result.data;
+}
+export function parseGraphScope(value) {
+    return parse(scopeSchema, value, "graph scope");
+}
+export function parseGraphSearchRequest(value) {
+    return parse(GraphSearchRequestSchema, value, "graph search request");
+}
+export function parseGraphSymbolRequest(value) {
+    return parse(GraphSymbolRequestSchema, value, "graph symbol request");
+}
+export function parseGraphRelationRequest(value) {
+    return parse(GraphRelationRequestSchema, value, "graph relation request");
+}
+export function parseGraphImpactRequest(value) {
+    return parse(GraphImpactRequestSchema, value, "graph impact request");
+}
+export function parseGraphFreshnessRequest(value) {
+    return parse(GraphFreshnessRequestSchema, value, "graph freshness request");
+}
+export function parseGraphIndexRequest(value) {
+    return assertRecordSize(parse(GraphIndexRequestSchema, value, "graph index request"), "graph index request", GRAPH_MAX_INDEX_BYTES);
+}
+export function parseAuthoritativeSourceReadRequest(value) {
+    return parse(AuthoritativeSourceReadRequestSchema, value, "authoritative source read request");
+}
+export function parseGraphQueryResponse(itemSchema, value) {
+    return assertRecordSize(parse(baseResponseSchema.extend({ items: z.array(itemSchema).max(GRAPH_MAX_ITEMS) }), value, "graph query response"), "graph query response", GRAPH_MAX_RESPONSE_BYTES);
+}
+export function parseGraphIndexResponse(value) {
+    return assertRecordSize(parse(baseResponseSchema.omit({ nextCursor: true }).extend({
+        indexedFiles: z.array(path).max(GRAPH_MAX_FILES_PER_INDEX),
+        skippedFiles: z.array(path).max(GRAPH_MAX_FILES_PER_INDEX),
+    }), value, "graph index response"), "graph index response", GRAPH_MAX_RESPONSE_BYTES);
+}
+export function serializeGraphContract(value) {
+    return JSON.stringify(value);
+}

package/dist/InteractionContracts.d.ts

@@ -0,0 +1,76 @@
+import type { InteractionSuspension, PolicyDecision, PolicyRequest } from "./PolicyContracts.js";
+export declare const INTERACTION_VERSION: "1";
+/** The maximum UTF-8 size of an answer or any nested answer value. */
+export declare const INTERACTION_MAX_PAYLOAD_BYTES: number;
+/** Limits protect persistence and control-plane consumers from pathological JSON. */
+export declare const INTERACTION_MAX_PAYLOAD_DEPTH = 8;
+export declare const INTERACTION_MAX_PAYLOAD_ITEMS = 256;
+export declare const INTERACTION_MAX_STRING_LENGTH: number;
+export declare const INTERACTION_MAX_LINEAGE_DEPTH = 32;
+export declare const INTERACTION_MAX_LINEAGE_PATH = 32;
+export declare const INTERACTION_REDACTED_VALUE: "[REDACTED]";
+export type InteractionStatus = "pending" | "answered" | "denied" | "expired" | "cancelled";
+/** JSON-only values accepted at the durable interaction boundary. */
+export type InteractionPayload = string | number | boolean | null | readonly InteractionPayload[] | Readonly<{
+    [key: string]: InteractionPayload;
+}>;
+export declare class InteractionContractError extends Error {
+    readonly code = "INTERACTION_INVALID";
+    constructor(message: string);
+}
+export interface InteractionRecord {
+    readonly version: typeof INTERACTION_VERSION;
+    readonly id: string;
+    readonly request: PolicyRequest;
+    readonly decision: PolicyDecision;
+    readonly status: InteractionStatus;
+    readonly createdAt: string;
+    readonly expiresAt: string;
+    readonly sequence: number;
+    readonly answer?: InteractionPayload;
+    readonly answeredBy?: string;
+    readonly answeredAt?: string;
+    /** Set when the answered record is atomically claimed for resumption. */
+    readonly claimedBy?: string;
+    readonly claimedAt?: string;
+    /** Reference to the suspended run/cursor; persisted separately from trace state. */
+    readonly suspension?: InteractionSuspension;
+}
+export interface InteractionAnswer {
+    readonly id: string;
+    readonly principalId: string;
+    readonly answer?: InteractionPayload;
+    readonly deny?: boolean;
+    readonly sequence: number;
+}
+export interface InteractionStore {
+    create(request: PolicyRequest, decision: PolicyDecision, opts?: {
+        expiresAt?: string;
+    }): Promise<InteractionRecord>;
+    get(id: string): Promise<InteractionRecord | undefined>;
+    answer(answer: InteractionAnswer): Promise<InteractionRecord>;
+    /**
+     * Atomically consume an answered interaction for one resume attempt.
+     * Implementations must compare both the principal and expected sequence
+     * in the same transaction as the claim.
+     */
+    claim(id: string, principalId: string, sequence: number): Promise<InteractionRecord>;
+    cancel(id: string, principalId: string, sequence: number): Promise<InteractionRecord>;
+    expire(now?: string): Promise<readonly InteractionRecord[]>;
+}
+/** Validate and clone a JSON-only interaction payload. */
+export declare function parseInteractionPayload(value: unknown, path?: string): InteractionPayload;
+/** Validate an answer received from an untrusted control-plane caller. */
+export declare function parseInteractionAnswer(value: unknown): InteractionAnswer;
+/** Make a bounded, JSON-safe snapshot for records and observability sinks. */
+export declare function redactInteractionPayload(value: InteractionPayload): InteractionPayload;
+/** Redact and bound provider-controlled text such as rule IDs and reasons. */
+export declare function redactInteractionString(value: string): string;
+/** Remove non-persistable runtime state and redact policy metadata for a record. */
+export declare function redactInteractionRequest(request: PolicyRequest): PolicyRequest;
+/** Bound and redact provider-controlled decision text before persistence. */
+export declare function redactInteractionDecision(decision: PolicyDecision): PolicyDecision;
+/** Return an isolated, deeply immutable snapshot suitable for a store/API. */
+export declare function immutableInteractionSnapshot<T>(value: T): T;
+/** Canonical comparison for duplicate answers with different object key order. */
+export declare function fingerprintInteractionPayload(value: InteractionPayload | undefined): string;

package/dist/InteractionContracts.js

@@ -0,0 +1,218 @@
+export const INTERACTION_VERSION = "1";
+/** The maximum UTF-8 size of an answer or any nested answer value. */
+export const INTERACTION_MAX_PAYLOAD_BYTES = 64 * 1024;
+/** Limits protect persistence and control-plane consumers from pathological JSON. */
+export const INTERACTION_MAX_PAYLOAD_DEPTH = 8;
+export const INTERACTION_MAX_PAYLOAD_ITEMS = 256;
+export const INTERACTION_MAX_STRING_LENGTH = 8 * 1024;
+export const INTERACTION_MAX_LINEAGE_DEPTH = 32;
+export const INTERACTION_MAX_LINEAGE_PATH = 32;
+export const INTERACTION_REDACTED_VALUE = "[REDACTED]";
+export class InteractionContractError extends Error {
+    code = "INTERACTION_INVALID";
+    constructor(message) {
+        super(message);
+        this.name = "InteractionContractError";
+    }
+}
+const SENSITIVE_KEY = /(?:pass(?:word|code)?|secret|token|api[-_]?key|authorization|cookie|credential|private[-_]?key|session)/i;
+const SENSITIVE_TEXT = /(?:bearer\s+|\b(?:pass(?:word|code)?|secret|token|api[-_]?key|authorization|cookie|credential|private[-_]?key)\b\s*[:=]?)/i;
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function byteLength(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
+function fail(path, message) {
+    throw new InteractionContractError(`${path} ${message}`);
+}
+function validatePayload(value, path, seen, depth) {
+    if (depth > INTERACTION_MAX_PAYLOAD_DEPTH)
+        fail(path, `exceeds maximum depth of ${INTERACTION_MAX_PAYLOAD_DEPTH}`);
+    if (value === null)
+        return value;
+    if (typeof value === "string") {
+        if (value.length > INTERACTION_MAX_STRING_LENGTH)
+            fail(path, "contains an oversized string");
+        return value;
+    }
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            fail(path, "must contain only finite numbers");
+        return value;
+    }
+    if (typeof value !== "object")
+        fail(path, "must be JSON-serializable");
+    if (seen.has(value))
+        fail(path, "must not contain circular references");
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            if (value.length > INTERACTION_MAX_PAYLOAD_ITEMS)
+                fail(path, "contains too many items");
+            return value.map((item, index) => validatePayload(item, `${path}[${index}]`, seen, depth + 1));
+        }
+        if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+            fail(path, "must contain only plain objects");
+        const keys = Object.keys(value);
+        if (keys.length > INTERACTION_MAX_PAYLOAD_ITEMS)
+            fail(path, "contains too many fields");
+        const output = {};
+        const objectValue = value;
+        for (const key of keys)
+            output[key] = validatePayload(objectValue[key], `${path}.${key}`, seen, depth + 1);
+        return output;
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+/** Validate and clone a JSON-only interaction payload. */
+export function parseInteractionPayload(value, path = "interaction payload") {
+    const parsed = validatePayload(value, path, new WeakSet(), 0);
+    let serialized;
+    try {
+        serialized = JSON.stringify(parsed);
+    }
+    catch {
+        throw new InteractionContractError(`${path} must be JSON-serializable`);
+    }
+    if (byteLength(serialized) > INTERACTION_MAX_PAYLOAD_BYTES)
+        throw new InteractionContractError(`${path} exceeds ${INTERACTION_MAX_PAYLOAD_BYTES} bytes`);
+    return parsed;
+}
+function boundedIdentifier(value, path) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 256)
+        fail(path, "must be a non-empty string of at most 256 characters");
+    return value;
+}
+function parseAttribution(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value))
+        fail("interaction attribution", "must be an object");
+    const rootId = boundedIdentifier(value.rootId, "interaction attribution.rootId");
+    const depth = value.depth;
+    if (typeof depth !== "number" || !Number.isSafeInteger(depth) || depth < 0 || depth > INTERACTION_MAX_LINEAGE_DEPTH)
+        fail("interaction attribution.depth", `must be an integer from 0 to ${INTERACTION_MAX_LINEAGE_DEPTH}`);
+    const result = { rootId, depth };
+    for (const key of ["parentId", "branchId"]) {
+        if (value[key] !== undefined)
+            result[key] = boundedIdentifier(value[key], `interaction attribution.${key}`);
+    }
+    const branchIndex = value.branchIndex;
+    if (branchIndex !== undefined) {
+        if (typeof branchIndex !== "number" || !Number.isSafeInteger(branchIndex) || branchIndex < 0)
+            fail("interaction attribution.branchIndex", "must be a non-negative safe integer");
+        result.branchIndex = branchIndex;
+    }
+    if (value.branchPath !== undefined) {
+        if (!Array.isArray(value.branchPath) || value.branchPath.length > INTERACTION_MAX_LINEAGE_PATH)
+            fail("interaction attribution.branchPath", `must contain at most ${INTERACTION_MAX_LINEAGE_PATH} labels`);
+        result.branchPath = value.branchPath.map((item, index) => boundedIdentifier(item, `interaction attribution.branchPath[${index}]`));
+    }
+    return result;
+}
+/** Validate an answer received from an untrusted control-plane caller. */
+export function parseInteractionAnswer(value) {
+    if (!isRecord(value))
+        throw new InteractionContractError("interaction answer must be an object");
+    const id = boundedIdentifier(value.id, "interaction answer.id");
+    const principalId = boundedIdentifier(value.principalId, "interaction answer.principalId");
+    const sequence = value.sequence;
+    if (typeof sequence !== "number" || !Number.isSafeInteger(sequence) || sequence < 0)
+        fail("interaction answer.sequence", "must be a non-negative safe integer");
+    if (value.deny !== undefined && typeof value.deny !== "boolean")
+        fail("interaction answer.deny", "must be a boolean");
+    const answer = value.answer === undefined ? undefined : parseInteractionPayload(value.answer, "interaction answer.answer");
+    return {
+        id,
+        principalId,
+        sequence,
+        ...(answer === undefined ? {} : { answer }),
+        ...(value.deny === undefined ? {} : { deny: value.deny }),
+    };
+}
+function redactText(value) {
+    return SENSITIVE_TEXT.test(value) ? INTERACTION_REDACTED_VALUE : value.slice(0, INTERACTION_MAX_STRING_LENGTH);
+}
+/** Make a bounded, JSON-safe snapshot for records and observability sinks. */
+export function redactInteractionPayload(value) {
+    if (typeof value === "string")
+        return redactText(value);
+    if (value === null || typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => redactInteractionPayload(item));
+    const output = {};
+    for (const [key, item] of Object.entries(value)) {
+        output[key] = SENSITIVE_KEY.test(key) ? INTERACTION_REDACTED_VALUE : redactInteractionPayload(item);
+    }
+    return output;
+}
+/** Redact and bound provider-controlled text such as rule IDs and reasons. */
+export function redactInteractionString(value) {
+    return redactText(value);
+}
+function redactFragments(fragments) {
+    const result = {};
+    for (const [key, value] of Object.entries(fragments)) {
+        result[key] =
+            SENSITIVE_KEY.test(key) || (typeof value === "string" && SENSITIVE_TEXT.test(value))
+                ? INTERACTION_REDACTED_VALUE
+                : value;
+    }
+    return result;
+}
+/** Remove non-persistable runtime state and redact policy metadata for a record. */
+export function redactInteractionRequest(request) {
+    const attribution = parseAttribution(request.attribution);
+    const { signal: _signal, ...persistable } = request;
+    return {
+        ...persistable,
+        ...(attribution ? { attribution } : {}),
+        scope: { ...request.scope, fragments: redactFragments(request.scope.fragments) },
+        layers: request.layers.map((layer) => ({ ...layer })),
+    };
+}
+/** Bound and redact provider-controlled decision text before persistence. */
+export function redactInteractionDecision(decision) {
+    return {
+        ...decision,
+        id: boundedIdentifier(decision.id, "interaction decision.id"),
+        policyVersion: boundedIdentifier(decision.policyVersion, "interaction decision.policyVersion"),
+        reasonCode: redactText(boundedIdentifier(decision.reasonCode, "interaction decision.reasonCode")),
+        ...(decision.reason === undefined
+            ? {}
+            : { reason: redactText(decision.reason.slice(0, INTERACTION_MAX_STRING_LENGTH)) }),
+    };
+}
+/** Return an isolated, deeply immutable snapshot suitable for a store/API. */
+export function immutableInteractionSnapshot(value) {
+    const snapshot = structuredClone(value);
+    const freeze = (item) => {
+        if (item === null || typeof item !== "object" || Object.isFrozen(item))
+            return;
+        for (const child of Object.values(item))
+            freeze(child);
+        Object.freeze(item);
+    };
+    freeze(snapshot);
+    return snapshot;
+}
+/** Canonical comparison for duplicate answers with different object key order. */
+export function fingerprintInteractionPayload(value) {
+    if (value === undefined)
+        return "undefined";
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(fingerprintInteractionPayload).join(",")}]`;
+    const objectValue = value;
+    return `{${Object.keys(objectValue)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${fingerprintInteractionPayload(objectValue[key])}`)
+        .join(",")}}`;
+}