@cavelang/scenario 0.29.0

package/dist/src/exact.js

@@ -0,0 +1,65 @@
+import { Exact } from '@cavelang/solver';
+import { ScenarioInputError } from "./error.js";
+const multiplier = {
+    K: 1000n,
+    M: 1000000n,
+    B: 1000000000n,
+    T: 1000000000000n
+};
+const hasMultiplier = (value) => Object.hasOwn(multiplier, value);
+const reduce = (numerator, denominator) => {
+    const divisor = (() => {
+        let left = numerator < 0n ? -numerator : numerator;
+        let right = denominator < 0n ? -denominator : denominator;
+        while (right !== 0n)
+            [left, right] = [right, left % right];
+        return left;
+    })();
+    const sign = denominator < 0n ? -1n : 1n;
+    return {
+        numerator: String((numerator / divisor) * sign),
+        denominator: String((denominator / divisor) * sign)
+    };
+};
+const multiply = (left, right) => reduce(BigInt(left.numerator) * BigInt(right.numerator), BigInt(left.denominator) * BigInt(right.denominator));
+export const add = (left, right) => reduce(BigInt(left.numerator) * BigInt(right.denominator) + BigInt(right.numerator) * BigInt(left.denominator), BigInt(left.denominator) * BigInt(right.denominator));
+export const compare = (left, right) => BigInt(left.numerator) * BigInt(right.denominator) < BigInt(right.numerator) * BigInt(left.denominator) ? -1 :
+    BigInt(left.numerator) * BigInt(right.denominator) > BigInt(right.numerator) * BigInt(left.denominator) ? 1 : 0;
+const rational = (value) => Exact.rational(value);
+/** Parses CAVE's exact scalar spelling without passing the digits through `number`. */
+export const parse = (authored, bindingId) => {
+    const approximate = authored.startsWith('~');
+    const body = approximate ? authored.slice(1) : authored;
+    const [head = '', ...tailParts] = body.trim().split(/\s+/);
+    const tail = tailParts.length === 0 ? undefined : tailParts.join(' ');
+    const match = /^([+-]?\d+(?:\.\d+)?)([A-Za-z%]*)$/.exec(head);
+    if (match === null || tailParts.length > 1) {
+        throw new ScenarioInputError('invalid-value', `expected a scalar number, received ${JSON.stringify(authored)}`, bindingId);
+    }
+    const digits = match[1];
+    const suffix = match[2] ?? '';
+    const factor = hasMultiplier(suffix) ? multiplier[suffix] : 1n;
+    const unit = hasMultiplier(suffix) ? tail : suffix === '' ? tail : suffix;
+    if (suffix !== '' && !hasMultiplier(suffix) && tail !== undefined) {
+        throw new ScenarioInputError('invalid-value', `cannot combine glued unit ${JSON.stringify(suffix)} with ${JSON.stringify(tail)}`, bindingId);
+    }
+    const base = rational(digits);
+    return {
+        exact: reduce(BigInt(base.numerator) * factor, BigInt(base.denominator)),
+        ...(unit === undefined ? {} : { unit }),
+        approximate
+    };
+};
+export const convert = (parsed, expectedUnit, conversions, bindingId) => {
+    if (expectedUnit === undefined || parsed.unit === expectedUnit)
+        return parsed;
+    if (parsed.unit === undefined) {
+        throw new ScenarioInputError('incompatible-unit', `expected unit ${JSON.stringify(expectedUnit)}, received a unitless value`, bindingId);
+    }
+    const conversion = conversions?.find(item => item.from === parsed.unit && item.to === expectedUnit);
+    if (conversion === undefined) {
+        throw new ScenarioInputError('incompatible-unit', `cannot convert ${JSON.stringify(parsed.unit)} to ${JSON.stringify(expectedUnit)} without an explicit conversion`, bindingId);
+    }
+    return { ...parsed, exact: multiply(parsed.exact, rational(conversion.factor)), unit: expectedUnit };
+};
+//# sourceMappingURL=exact.js.map

package/dist/src/exact.js.map

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

package/dist/src/explain.d.ts

@@ -0,0 +1,5 @@
+import { Explain } from '@cavelang/solver';
+import type { Definition, InputRecord } from './model.ts';
+/** Convert a frozen scenario binding into solver-neutral run provenance. */
+export declare const explanationContext: (definition: Definition, record: InputRecord) => Explain.Context;
+//# sourceMappingURL=explain.d.ts.map

package/dist/src/explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../src/explain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAC1C,OAAO,KAAK,EAAW,UAAU,EAAE,WAAW,EAAS,MAAM,YAAY,CAAA;AAoCzE,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,GAAI,YAAY,UAAU,EAAE,QAAQ,WAAW,KAAG,OAAO,CAAC,OA6BxF,CAAA"}

package/dist/src/explain.js

@@ -0,0 +1,59 @@
+import { Explain } from '@cavelang/solver';
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const unique = (values) => [...new Set(values)].sort(compareText);
+const authored = (value) => {
+    switch (value.kind) {
+        case 'boolean': return value.value;
+        case 'integer': return value.authored ?? value.value;
+        case 'number': return value.authored ?? `${value.value.numerator}/${value.value.denominator}`;
+        case 'enum': return value.value;
+        case 'text': return value.value;
+    }
+};
+const authoredValue = (value) => value === undefined ? undefined : Array.isArray(value) ? value.map(authored) : authored(value);
+const bindingInput = (binding, result) => {
+    const evidence = result.candidates.flatMap(candidate => candidate.evidence);
+    const value = result.value;
+    const authoredInput = authoredValue(value);
+    return {
+        id: result.id,
+        query: binding.query,
+        ...(value === undefined ? {} : { value: value }),
+        ...(authoredInput === undefined ? {} : { authoredValue: authoredInput }),
+        evidenceRowIds: unique(evidence.flatMap(item => item.origin === 'belief' ? item.rowIds : [])),
+        scenarioClaimIds: unique(evidence.flatMap(item => item.origin === 'scenario' ? item.claimIds : []))
+    };
+};
+/** Convert a frozen scenario binding into solver-neutral run provenance. */
+export const explanationContext = (definition, record) => {
+    if (record.scenarioId !== definition.id) {
+        throw new TypeError(`scenario record ${JSON.stringify(record.scenarioId)} does not match ${JSON.stringify(definition.id)}`);
+    }
+    if (record.modelDigest !== definition.modelDigest) {
+        throw new TypeError(`scenario record model digest does not match its definition`);
+    }
+    const definitions = new Map(definition.bindings.map(binding => [binding.id, binding]));
+    const inputs = record.bindings.map(result => {
+        const binding = definitions.get(result.id);
+        if (binding === undefined)
+            throw new TypeError(`scenario record contains unknown binding ${JSON.stringify(result.id)}`);
+        return bindingInput(binding, result);
+    });
+    return {
+        modelDigest: record.modelDigest,
+        scenario: {
+            id: record.scenarioId,
+            inputDigest: record.digest,
+            overlayDigest: record.overlay.digest
+        },
+        snapshot: {
+            transactionTime: record.snapshot.transactionTime,
+            ...(record.snapshot.at === undefined ? {} : { validTime: record.snapshot.at }),
+            aliases: record.snapshot.aliases,
+            resolution: record.snapshot.resolution,
+            minimumConfidence: record.snapshot.minimumConfidence
+        },
+        inputs
+    };
+};
+//# sourceMappingURL=explain.js.map

package/dist/src/explain.js.map

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

package/dist/src/index.d.ts

@@ -0,0 +1,7 @@
+/** Typed, replayable CAVE snapshot bindings for decision and solver inputs. */
+export { bind, run } from './bind.ts';
+export { explanationContext } from './explain.ts';
+export { ScenarioInputError } from './error.ts';
+export * as Model from './model.ts';
+export * as Record from './record.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AACrC,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA"}

package/dist/src/index.js

@@ -0,0 +1,7 @@
+/** Typed, replayable CAVE snapshot bindings for decision and solver inputs. */
+export { bind, run } from "./bind.js";
+export { explanationContext } from "./explain.js";
+export { ScenarioInputError } from "./error.js";
+export * as Model from "./model.js";
+export * as Record from "./record.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AACrC,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA"}

package/dist/src/model.d.ts

@@ -0,0 +1,141 @@
+import type { Model } from '@cavelang/solver';
+export declare const schema: "cave.scenario/inputs@1";
+export type Snapshot = {
+    /** Transaction-time boundary. Omit to freeze the current store head. */
+    readonly asOf?: string;
+    /** Valid-time instant passed to CAVE-Q. */
+    readonly at?: string;
+    readonly aliases: 'exact' | 'closure';
+    readonly resolution: 'coexisting' | 'winner';
+    readonly minimumConfidence: number;
+};
+export type Conversion = {
+    readonly from: string;
+    readonly to: string;
+    /** Exact `to` units per one `from` unit. */
+    readonly factor: Model.Rational;
+};
+export type Expected = {
+    readonly kind: 'boolean';
+    readonly trueValue?: string;
+    readonly falseValue?: string;
+} | {
+    readonly kind: 'integer';
+    readonly unit?: string;
+    readonly conversions?: readonly Conversion[];
+} | {
+    readonly kind: 'number';
+    readonly unit?: string;
+    readonly conversions?: readonly Conversion[];
+} | {
+    readonly kind: 'enum';
+    readonly values: readonly string[];
+} | {
+    readonly kind: 'text';
+};
+export type MissingPolicy = 'reject' | 'omit' | 'empty';
+export type Policies = {
+    readonly missing: MissingPolicy;
+    readonly contested: 'reject' | 'allow';
+    readonly retracted: 'reject' | 'exclude' | 'include';
+    readonly unresolved: 'reject' | 'allow';
+};
+type CommonBinding = {
+    readonly id: string;
+    readonly query: string;
+    /** CAVE-Q variable to bind. Omit only for Boolean existence inputs. */
+    readonly select?: string;
+    readonly expected: Expected;
+    readonly scenarioOverride: boolean;
+    readonly policies: Policies;
+};
+export type Binding = CommonBinding & ({
+    readonly cardinality: 'one';
+} | {
+    readonly cardinality: 'optional';
+} | {
+    readonly cardinality: 'many';
+    readonly reduce: 'all' | 'min' | 'max' | 'sum';
+});
+export type Definition = {
+    readonly id: string;
+    /** Digest of the portable model or evaluator receiving these inputs. */
+    readonly modelDigest: string;
+    readonly snapshot: Snapshot;
+    readonly overlay?: string;
+    readonly bindings: readonly Binding[];
+};
+export type ExactNumber = {
+    readonly numerator: string;
+    readonly denominator: string;
+};
+export type Uncertainty = {
+    readonly authored: string;
+    readonly exact: ExactNumber;
+    readonly unit?: string;
+    readonly sigmaLevel: number;
+};
+export type Value = {
+    readonly kind: 'boolean';
+    readonly value: boolean;
+} | {
+    readonly kind: 'integer';
+    readonly value: string;
+    readonly unit?: string;
+    readonly authored?: string;
+    readonly approximate: boolean;
+    readonly uncertainty?: Uncertainty;
+} | {
+    readonly kind: 'number';
+    readonly value: ExactNumber;
+    readonly unit?: string;
+    readonly authored?: string;
+    readonly approximate: boolean;
+    readonly uncertainty?: Uncertainty;
+} | {
+    readonly kind: 'enum';
+    readonly value: string;
+} | {
+    readonly kind: 'text';
+    readonly value: string;
+};
+export type Evidence = {
+    readonly origin: 'belief';
+    readonly rowIds: readonly string[];
+} | {
+    readonly origin: 'scenario';
+    readonly claimIds: readonly string[];
+};
+export type Candidate = {
+    readonly value: Value;
+    readonly confidence: number;
+    readonly evidence: readonly Evidence[];
+};
+export type BindingResult = {
+    readonly id: string;
+    readonly candidates: readonly Candidate[];
+    readonly value?: Value | readonly Value[];
+};
+export type FrozenSnapshot = Snapshot & {
+    /** Exact newest base row visible at `asOf`, or null for an empty snapshot. */
+    readonly transactionTime: string | null;
+};
+export type InputRecord = {
+    readonly schema: typeof schema;
+    readonly scenarioId: string;
+    readonly modelDigest: string;
+    readonly digest: string;
+    readonly snapshot: FrozenSnapshot;
+    readonly overlay: {
+        readonly digest: string;
+        readonly source: string;
+        readonly claimIds: readonly string[];
+    };
+    readonly values: Readonly<Record<string, Value | readonly Value[]>>;
+    readonly bindings: readonly BindingResult[];
+    readonly supportingRowIds: readonly string[];
+    readonly scenarioClaimIds: readonly string[];
+};
+export type t = InputRecord;
+export {};
+//# sourceMappingURL=model.d.ts.map

package/dist/src/model.d.ts.map

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

package/dist/src/model.js

@@ -0,0 +1,2 @@
+export const schema = 'cave.scenario/inputs@1';
+//# sourceMappingURL=model.js.map

package/dist/src/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/model.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,MAAM,GAAG,wBAAiC,CAAA"}

package/dist/src/record.d.ts

@@ -0,0 +1,100 @@
+import type { Explain } from '@cavelang/solver';
+import type { Store } from '@cavelang/store';
+import type { InputRecord } from './model.ts';
+export declare const resultSchema: "cave.scenario/result@1";
+export declare const evaluationSchema: "cave.scenario/evaluation@1";
+export declare const recommendationSchema: "cave.scenario/recommendation@1";
+export declare const decisionSchema: "cave.scenario/decision@1";
+export declare const actionSchema: "cave.scenario/action@1";
+export declare const externalEffectSchema: "cave.scenario/external-effect@1";
+export type Result = {
+    readonly schema: typeof resultSchema;
+    /** Stable caller-supplied identity. Reusing it with different content is an error. */
+    readonly id: string;
+    readonly report: Explain.Report;
+};
+/** Ordinary external-evaluator result over one frozen scenario input record. */
+export type Evaluation = {
+    readonly schema: typeof evaluationSchema;
+    readonly id: string;
+    readonly inputs: InputRecord;
+    readonly evaluator: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly output: Explain.Json;
+};
+export type ResultArtifact = Result | Evaluation;
+export type Recommendation = {
+    readonly schema: typeof recommendationSchema;
+    readonly id: string;
+    readonly resultId: string;
+    readonly value: Explain.Json;
+    readonly rationale?: string;
+    readonly authoredBy?: string;
+};
+export type Decision = {
+    readonly schema: typeof decisionSchema;
+    readonly id: string;
+    readonly resultId: string;
+    readonly recommendationId?: string;
+    readonly selected: Explain.Json;
+    readonly decidedBy: string;
+    readonly rationale?: string;
+};
+/** Audit record only. Creating it never invokes an action or external hook. */
+export type Action = {
+    readonly schema: typeof actionSchema;
+    readonly id: string;
+    readonly decisionId: string;
+    readonly name: string;
+    readonly parameters: Explain.Json;
+    readonly status: 'validated' | 'executed' | 'failed';
+    readonly message?: string;
+};
+/** Audit record only. External effects remain owned by governed action execution. */
+export type ExternalEffect = {
+    readonly schema: typeof externalEffectSchema;
+    readonly id: string;
+    readonly actionId: string;
+    readonly kind: string;
+    readonly status: 'succeeded' | 'failed' | 'unknown';
+    readonly details?: Explain.Json;
+};
+export type Artifact = ResultArtifact | Recommendation | Decision | Action | ExternalEffect;
+export type Kind = 'result' | 'recommendation' | 'decision' | 'action' | 'external-effect';
+export type RecordOutcome = {
+    readonly status: 'recorded' | 'existing';
+    readonly rowId: string;
+    readonly artifact: Artifact;
+};
+export type ReplayExpectation = {
+    readonly modelDigest: string;
+    readonly backend?: {
+        readonly name: string;
+        readonly version: string;
+    };
+};
+export type Replay = {
+    readonly artifact: Result;
+    readonly compatible: boolean;
+    readonly reasons: readonly string[];
+};
+export declare class RecordConflictError extends Error {
+    constructor(kind: Kind, id: string);
+}
+export declare class MissingRecordError extends Error {
+    constructor(kind: Kind, id: string);
+}
+export declare const result: (store: Store, artifact: ResultArtifact) => RecordOutcome;
+export declare const recommendation: (store: Store, artifact: Recommendation) => RecordOutcome;
+export declare const decision: (store: Store, artifact: Decision) => RecordOutcome;
+export declare const action: (store: Store, artifact: Action) => RecordOutcome;
+export declare const externalEffect: (store: Store, artifact: ExternalEffect) => RecordOutcome;
+export declare const read: <T extends Artifact>(store: Store, kind: Kind, id: string) => T;
+/**
+ * Reads an immutable result without re-running it. Compatibility is explicit:
+ * a different model or backend version is reported, never silently upgraded.
+ */
+export declare const replay: (store: Store, id: string, expected: ReplayExpectation) => Replay;
+//# sourceMappingURL=record.d.ts.map

package/dist/src/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/record.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAG/C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,eAAO,MAAM,YAAY,EAAG,wBAAiC,CAAA;AAC7D,eAAO,MAAM,gBAAgB,EAAG,4BAAqC,CAAA;AACrE,eAAO,MAAM,oBAAoB,EAAG,gCAAyC,CAAA;AAC7E,eAAO,MAAM,cAAc,EAAG,0BAAmC,CAAA;AACjE,eAAO,MAAM,YAAY,EAAG,wBAAiC,CAAA;AAC7D,eAAO,MAAM,oBAAoB,EAAG,iCAA0C,CAAA;AAE9E,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,MAAM,EAAE,OAAO,YAAY,CAAA;IACpC,sFAAsF;IACtF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAA;CAChC,CAAA;AAED,gFAAgF;AAChF,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,gBAAgB,CAAA;IACxC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KACzB,CAAA;IACD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAA;CAC9B,CAAA;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,UAAU,CAAA;AAEhD,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,oBAAoB,CAAA;IAC5C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAA;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,MAAM,EAAE,OAAO,cAAc,CAAA;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED,+EAA+E;AAC/E,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,MAAM,EAAE,OAAO,YAAY,CAAA;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,QAAQ,CAAA;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B,CAAA;AAED,qFAAqF;AACrF,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,oBAAoB,CAAA;IAC5C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAA;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAA;CAChC,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,cAAc,GAAG,QAAQ,GAAG,MAAM,GAAG,cAAc,CAAA;AAC3F,MAAM,MAAM,IAAI,GAAG,QAAQ,GAAG,gBAAgB,GAAG,UAAU,GAAG,QAAQ,GAAG,iBAAiB,CAAA;AAE1F,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAAA;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE;QACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KACzB,CAAA;CACF,CAAA;AAED,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC,CAAA;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM;CAInC;AAED,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM;CAInC;AA8HD,eAAO,MAAM,MAAM,GAAI,OAAO,KAAK,EAAE,UAAU,cAAc,KAAG,aAa5D,CAAA;AAEJ,eAAO,MAAM,cAAc,GAAI,OAAO,KAAK,EAAE,UAAU,cAAc,KAAG,aAC8B,CAAA;AAEtG,eAAO,MAAM,QAAQ,GAAI,OAAO,KAAK,EAAE,UAAU,QAAQ,KAAG,aASxD,CAAA;AAEJ,eAAO,MAAM,MAAM,GAAI,OAAO,KAAK,EAAE,UAAU,MAAM,KAAG,aAC4C,CAAA;AAEpG,eAAO,MAAM,cAAc,GAAI,OAAO,KAAK,EAAE,UAAU,cAAc,KAAG,aACsB,CAAA;AAE9F,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,QAAQ,EAAE,OAAO,KAAK,EAAE,MAAM,IAAI,EAAE,IAAI,MAAM,KAAG,CAC7C,CAAA;AAEnC;;;GAGG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,KAAK,EAAE,IAAI,MAAM,EAAE,UAAU,iBAAiB,KAAG,MAoB9E,CAAA"}

package/dist/src/record.js

@@ -0,0 +1,189 @@
+import { Buffer } from 'node:buffer';
+import { Key } from '@cavelang/core';
+import { canonicalizeText } from '@cavelang/canonical';
+export const resultSchema = 'cave.scenario/result@1';
+export const evaluationSchema = 'cave.scenario/evaluation@1';
+export const recommendationSchema = 'cave.scenario/recommendation@1';
+export const decisionSchema = 'cave.scenario/decision@1';
+export const actionSchema = 'cave.scenario/action@1';
+export const externalEffectSchema = 'cave.scenario/external-effect@1';
+export class RecordConflictError extends Error {
+    constructor(kind, id) {
+        super(`${kind} ${JSON.stringify(id)} is already recorded with different content`);
+        this.name = 'RecordConflictError';
+    }
+}
+export class MissingRecordError extends Error {
+    constructor(kind, id) {
+        super(`${kind} ${JSON.stringify(id)} is not recorded`);
+        this.name = 'MissingRecordError';
+    }
+}
+const kindOf = (artifact) => {
+    switch (artifact.schema) {
+        case resultSchema: return 'result';
+        case evaluationSchema: return 'result';
+        case recommendationSchema: return 'recommendation';
+        case decisionSchema: return 'decision';
+        case actionSchema: return 'action';
+        case externalEffectSchema: return 'external-effect';
+    }
+};
+const prefix = {
+    result: 'scenario-result',
+    recommendation: 'scenario-recommendation',
+    decision: 'scenario-decision',
+    action: 'scenario-action',
+    'external-effect': 'scenario-effect'
+};
+const source = {
+    result: 'scenario/result',
+    recommendation: 'scenario/recommendation',
+    decision: 'scenario/decision',
+    action: 'scenario/action',
+    'external-effect': 'scenario/external-effect'
+};
+const entity = (kind, id) => {
+    if (id === '')
+        throw new TypeError(`${kind} id must not be empty`);
+    return `${prefix[kind]}/${id}`;
+};
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const canonicalJson = (value) => {
+    const normalize = (item, path) => {
+        if (item === null || typeof item === 'string' || typeof item === 'boolean')
+            return item;
+        if (typeof item === 'number') {
+            if (!Number.isFinite(item))
+                throw new TypeError(`${path} must be finite`);
+            return item;
+        }
+        if (Array.isArray(item))
+            return item.map((entry, index) => normalize(entry, `${path}[${index}]`));
+        if (typeof item === 'object') {
+            return Object.fromEntries(Object.entries(item)
+                .filter(([, entry]) => entry !== undefined)
+                .sort(([left], [right]) => compareText(left, right))
+                .map(([key, entry]) => [key, normalize(entry, `${path}.${key}`)]));
+        }
+        throw new TypeError(`${path} is not JSON`);
+    };
+    return JSON.stringify(normalize(value, 'artifact'));
+};
+const encode = (artifact) => Buffer.from(canonicalJson(artifact), 'utf8').toString('base64url');
+const decode = (payload) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new TypeError('recorded scenario artifact is not valid base64url JSON');
+    }
+    if (typeof parsed !== 'object' || parsed === null || typeof parsed.schema !== 'string') {
+        throw new TypeError('recorded scenario artifact has no schema');
+    }
+    const schema = parsed.schema;
+    if (![resultSchema, evaluationSchema, recommendationSchema, decisionSchema, actionSchema, externalEffectSchema].includes(schema)) {
+        throw new TypeError(`unsupported recorded scenario artifact schema ${JSON.stringify(schema)}`);
+    }
+    return parsed;
+};
+const line = (kind, id, payload) => `${entity(kind, id)} HAS artifact: \`${payload}\` @src:${source[kind]}`;
+const claimOf = (store, kind, id, payload) => {
+    const parsed = canonicalizeText(line(kind, id, payload), store.registry());
+    const claim = parsed.claims[0]?.claim;
+    if (parsed.problems.length > 0 || claim === undefined) {
+        const detail = parsed.problems.map(problem => `line ${problem.line}: ${problem.message}`).join('; ');
+        throw new TypeError(`invalid ${kind} identity ${JSON.stringify(id)}${detail === '' ? '' : `: ${detail}`}`);
+    }
+    return { parsed, claim };
+};
+const currentPayload = (store, kind, id) => {
+    // The payload is excluded from an attribute claim key, so an empty
+    // placeholder locates the one append-only series for this artifact ID.
+    const { claim } = claimOf(store, kind, id, '');
+    const row = store.currentBelief(Key.of(claim));
+    if (row === undefined || row.conf === 0)
+        return undefined;
+    const stored = store.toClaim(row);
+    if (stored.payload.kind !== 'attribute' || stored.payload.attribute !== 'artifact' || stored.payload.value.kind !== 'code') {
+        throw new TypeError(`${kind} ${JSON.stringify(id)} has an invalid stored representation`);
+    }
+    return { payload: stored.payload.value.raw, rowId: row.id };
+};
+const requireRecord = (store, kind, id) => {
+    const found = currentPayload(store, kind, id);
+    if (found === undefined)
+        throw new MissingRecordError(kind, id);
+    const artifact = decode(found.payload);
+    if (kindOf(artifact) !== kind || artifact.id !== id) {
+        throw new TypeError(`${kind} ${JSON.stringify(id)} has mismatched stored identity`);
+    }
+    return artifact;
+};
+const append = (store, artifact, validate) => store.transaction(() => {
+    validate();
+    const kind = kindOf(artifact);
+    const payload = encode(artifact);
+    const existing = currentPayload(store, kind, artifact.id);
+    if (existing !== undefined) {
+        if (existing.payload !== payload)
+            throw new RecordConflictError(kind, artifact.id);
+        return { status: 'existing', rowId: existing.rowId, artifact };
+    }
+    const { parsed } = claimOf(store, kind, artifact.id, payload);
+    const inserted = store.insertResult(parsed);
+    return { status: 'recorded', rowId: inserted.ids[0], artifact };
+});
+export const result = (store, artifact) => append(store, artifact, () => {
+    if (artifact.schema === resultSchema && artifact.report.schema !== 'cave.solver/explanation@1') {
+        throw new TypeError(`unsupported solver explanation schema ${JSON.stringify(artifact.report.schema)}`);
+    }
+    if (artifact.schema === evaluationSchema) {
+        if (artifact.inputs.schema !== 'cave.scenario/inputs@1') {
+            throw new TypeError(`unsupported scenario input schema ${JSON.stringify(artifact.inputs.schema)}`);
+        }
+        if (artifact.evaluator.name === '' || artifact.evaluator.version === '') {
+            throw new TypeError('scenario evaluator name and version must not be empty');
+        }
+    }
+});
+export const recommendation = (store, artifact) => append(store, artifact, () => { requireRecord(store, 'result', artifact.resultId); });
+export const decision = (store, artifact) => append(store, artifact, () => {
+    requireRecord(store, 'result', artifact.resultId);
+    if (artifact.recommendationId !== undefined) {
+        const proposal = requireRecord(store, 'recommendation', artifact.recommendationId);
+        if (proposal.resultId !== artifact.resultId) {
+            throw new TypeError(`recommendation ${JSON.stringify(artifact.recommendationId)} belongs to another result`);
+        }
+    }
+});
+export const action = (store, artifact) => append(store, artifact, () => { requireRecord(store, 'decision', artifact.decisionId); });
+export const externalEffect = (store, artifact) => append(store, artifact, () => { requireRecord(store, 'action', artifact.actionId); });
+export const read = (store, kind, id) => requireRecord(store, kind, id);
+/**
+ * Reads an immutable result without re-running it. Compatibility is explicit:
+ * a different model or backend version is reported, never silently upgraded.
+ */
+export const replay = (store, id, expected) => {
+    const found = requireRecord(store, 'result', id);
+    if (found.schema !== resultSchema) {
+        throw new TypeError(`result ${JSON.stringify(id)} is an external evaluation, not a solver result`);
+    }
+    const artifact = found;
+    const reasons = [];
+    if (artifact.report.run.modelDigest !== expected.modelDigest) {
+        reasons.push(`model digest ${artifact.report.run.modelDigest} does not match ${expected.modelDigest}`);
+    }
+    if (expected.backend !== undefined) {
+        const actual = artifact.report.run.backend;
+        if (actual.name !== expected.backend.name) {
+            reasons.push(`solver backend ${actual.name} does not match ${expected.backend.name}`);
+        }
+        if (actual.version !== expected.backend.version) {
+            reasons.push(`solver version ${actual.version} does not match ${expected.backend.version}`);
+        }
+    }
+    return { artifact, compatible: reasons.length === 0, reasons };
+};
+//# sourceMappingURL=record.js.map