@tangleai/outcomes 0.24.1

package/src/contract.js

@@ -0,0 +1,6 @@
+/** The portable operation contract; host authentication is supplied by handlers. */
+import { compileContract } from '@jarenjs/contract';
+import document from '../schemas/outcomes.contract.json' with { type: 'json' };
+export const outcomeContractDocument = document;
+export function createOutcomeContract() { return compileContract(document); }
+export { createOutcomeHandlers, OUTCOME_MODEL_OPERATIONS } from "./handlers.js";

package/src/domain.d.ts

@@ -0,0 +1,19 @@
+import type { OutcomeAdapter } from './adapters.ts';
+import type { Json } from './outcomes.contracts.gen.ts';
+export declare function domainValidator(schema: object): (value: unknown) => Json;
+export declare function adapterIdentity(id: string, schemas: OutcomeAdapter['schemas'], rules: Json): Promise<Readonly<{
+    revision: string;
+    id: string;
+    inputSchema: string;
+    outputSchema: string;
+    resolutionSchema: string;
+    artifactSchema: string;
+    scorerRevision: string;
+}>>;
+export declare function checkedAdapter(adapter: OutcomeAdapter): {
+    input: (value: unknown) => Json;
+    output: (value: unknown) => Json;
+    resolution: (value: unknown) => Json;
+    artifact(value: unknown): Json;
+};
+export declare const scoreUtility: (category: "success" | "partial" | "failure") => number;

package/src/domain.js

@@ -0,0 +1,45 @@
+/** Trusted adapter registration and schema validation share one boundary. */
+import { JarenValidator } from '@jarenjs/validate';
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { cloneJson, deepFreeze } from '@jarenjs/core/object';
+import { outcomeRevision } from "./identity.js";
+import { reject } from "./errors.js";
+export function domainValidator(schema) {
+    const validate = new JarenValidator({ collectErrors: true, unknownFormats: 'ignore' }).compile(schema);
+    return value => {
+        try {
+            canonicalizeJson(value);
+        }
+        catch {
+            reject('OUTC1001', 'Expected finite JSON domain data.');
+        }
+        if (!validate(value).valid)
+            reject('OUTC1001', 'Domain schema rejected the value.');
+        return deepFreeze(cloneJson(value));
+    };
+}
+export async function adapterIdentity(id, schemas, rules) {
+    const [inputSchema, outputSchema, resolutionSchema, artifactSchema, scorerRevision] = await Promise.all([
+        outcomeRevision(schemas.input), outcomeRevision(schemas.output), outcomeRevision(schemas.resolution),
+        outcomeRevision(schemas.artifact), outcomeRevision({ id, rules }),
+    ]);
+    const identity = { id, inputSchema, outputSchema, resolutionSchema, artifactSchema, scorerRevision };
+    return Object.freeze({ ...identity, revision: await outcomeRevision(identity) });
+}
+export function checkedAdapter(adapter) {
+    const input = domainValidator(adapter.schemas.input), output = domainValidator(adapter.schemas.output);
+    const resolution = domainValidator(adapter.schemas.resolution), artifact = domainValidator(adapter.schemas.artifact);
+    return {
+        input, output, resolution,
+        artifact(value) {
+            let payload = artifact(value);
+            if (adapter.normalizePayload)
+                payload = artifact(adapter.normalizePayload(payload));
+            const issues = adapter.validatePayload(payload);
+            if (issues.length)
+                reject('OUTC1010', issues.map(i => i.detail).join(' '));
+            return payload;
+        },
+    };
+}
+export const scoreUtility = (category) => category === 'success' ? 1 : category === 'partial' ? 0.5 : 0;

package/src/errors.d.ts

@@ -0,0 +1,23 @@
+/** Stable content failures shared by stores, services and wire handlers. */
+import type { Issue, Result, Json } from './outcomes.contracts.gen.ts';
+export type OutcomeIssue = Issue;
+export type OutcomeResult<T extends Json = Json> = {
+    ok: true;
+    value: T;
+    replayed: boolean;
+    writes: number;
+} | {
+    ok: false;
+    issues: Issue[];
+};
+export declare function issue(code: Issue['code'], detail: string, path?: string, retryable?: boolean): Issue;
+export declare const refuse: (code: Issue["code"], detail: string, path?: string, retryable?: boolean) => OutcomeResult;
+/** Internal transaction abort; caught at the supported content boundary. */
+export declare class OutcomeRefusal extends Error {
+    readonly issues: Issue[];
+    get code(): Issue['code'];
+    get docPath(): string;
+    constructor(issues: Issue[]);
+}
+export declare function reject(code: Issue['code'], detail: string, path?: string, retryable?: boolean): never;
+export declare function failure(error: unknown): Result;

package/src/errors.js

@@ -0,0 +1,11 @@
+export function issue(code, detail, path = '', retryable = false) { return { code, path, detail, retryable }; }
+export const refuse = (code, detail, path = '', retryable = false) => ({ ok: false, issues: [issue(code, detail, path, retryable)] });
+/** Internal transaction abort; caught at the supported content boundary. */
+export class OutcomeRefusal extends Error {
+    issues;
+    get code() { return this.issues[0].code; }
+    get docPath() { return this.issues[0].path; }
+    constructor(issues) { super(issues[0]?.detail ?? 'outcome refused'); this.issues = issues; }
+}
+export function reject(code, detail, path = '', retryable = false) { throw new OutcomeRefusal([issue(code, detail, path, retryable)]); }
+export function failure(error) { return error instanceof OutcomeRefusal ? { ok: false, issues: error.issues } : refuse('OUTC1015', 'The storage operation failed before publication.', '', true); }

package/src/evaluation.d.ts

@@ -0,0 +1,49 @@
+import type { ServiceContext } from './service-context.ts';
+import type { OutcomeTransaction } from './store.ts';
+import type { ArtifactVersion, EvaluateCommand, EvaluationRegistration, Evaluation, CaseResult, Issue, Operation, Json } from './outcomes.contracts.gen.ts';
+export declare const RETROSPECTIVE_RULES: Readonly<{
+    revision: "outcome-retrospective/v1";
+    utility: {
+        success: number;
+        partial: number;
+        failure: number;
+    };
+    strictPairedImprovement: true;
+    noDomainRegression: true;
+    completeCoverage: true;
+}>;
+export declare const outcomeGatePolicyId: (policy: Json) => Promise<string>;
+export declare function reserveEvaluation(context: ServiceContext, c: EvaluateCommand, op: Operation): Promise<{
+    version: ArtifactVersion;
+    reflection: import("./outcomes.contracts.gen.ts").Reflection;
+    training: {
+        score: import("./outcomes.contracts.gen.ts").Score;
+        decision: import("./outcomes.contracts.gen.ts").Decision;
+        resolution: import("./outcomes.contracts.gen.ts").Resolution;
+        contentDigest: string;
+    }[];
+}>;
+export declare function prepareEvaluation(context: ServiceContext, c: EvaluateCommand, op: Operation): Promise<{
+    registration: EvaluationRegistration;
+    version: ArtifactVersion;
+    reflection: import("./outcomes.contracts.gen.ts").Reflection;
+    training: {
+        score: import("./outcomes.contracts.gen.ts").Score;
+        decision: import("./outcomes.contracts.gen.ts").Decision;
+        resolution: import("./outcomes.contracts.gen.ts").Resolution;
+        contentDigest: string;
+    }[];
+}>;
+export declare function pairedResults(context: ServiceContext, version: ArtifactVersion, registration: EvaluationRegistration, baseline: Json): Promise<{
+    rows: CaseResult[];
+    issues: Issue[];
+}>;
+export declare function baselinePayload(tx: OutcomeTransaction, context: ServiceContext, version: ArtifactVersion): Promise<Json>;
+export declare function commitEvaluation(tx: OutcomeTransaction, context: ServiceContext, c: EvaluateCommand, data: Awaited<ReturnType<typeof prepareEvaluation>>): Promise<{
+    evaluationId: string;
+    eligible: boolean;
+    issues: Json;
+    caseReportId: string;
+}>;
+/** Recompute from retained independent bytes at the authority boundary. */
+export declare function checkedEvaluation(tx: OutcomeTransaction, context: ServiceContext, version: ArtifactVersion, evaluation: Evaluation): Promise<EvaluationRegistration>;

package/src/evaluation.js

@@ -0,0 +1,174 @@
+/** One-use held-out registrations and independently recomputed paired gates. */
+import { equalsJson } from '@jarenjs/core/object';
+import { checkShape, checkTime, jsonBytes } from "./schema.js";
+import { outcomeRevision } from "./identity.js";
+import { issue, reject, OutcomeRefusal } from "./errors.js";
+import { scoreUtility } from "./domain.js";
+import { headFor, semantic, unique, putRecord } from "./persistence.js";
+import { recordOf, seal, asJson } from "./service-context.js";
+import { trainingRecords } from "./refinement.js";
+import { verifiedSource } from "./resolution.js";
+import { assertHead, eligibilityIssues } from "./transitions.js";
+export const RETROSPECTIVE_RULES = Object.freeze({ revision: 'outcome-retrospective/v1', utility: { success: 1, partial: 0.5, failure: 0 }, strictPairedImprovement: true, noDomainRegression: true, completeCoverage: true });
+export const outcomeGatePolicyId = (policy) => outcomeRevision({ rules: RETROSPECTIVE_RULES, policy });
+export async function reserveEvaluation(context, c, op) {
+    return context.atomic().transaction(async (tx) => {
+        const previous = await semantic(tx, c.scopeId, 'evaluation', c.input.versionId);
+        if (previous)
+            reject('OUTC1007', `The evaluation stage is already complete: ${previous}.`);
+        const version = await recordOf(tx, c.input.versionId, c.scopeId, c.artifactKey, 'artifactVersion');
+        if (version.policyId !== context.policyId)
+            reject('OUTC1008', 'Candidate policy differs from its host.');
+        const reflection = await recordOf(tx, version.reflectionId, c.scopeId, c.artifactKey, 'reflection');
+        const training = await trainingRecords(tx, context, c.artifactKey, reflection.scoreIds, version.recordedAt);
+        if (!equalsJson(version.adapter, training[0].decision.adapter))
+            reject('OUTC1008', 'Candidate adapter differs from its training.');
+        assertHead(await headFor(tx, c.scopeId, c.artifactKey), version.expectedHead);
+        const slotKey = [c.artifactKey, c.input.slotId];
+        const owner = await semantic(tx, c.scopeId, 'evaluationSlotOwner', slotKey);
+        if (owner && owner !== op.id)
+            reject('OUTC1011', 'The held-out slot has already been reserved.');
+        const candidateOwner = await semantic(tx, c.scopeId, 'evaluationCandidateOwner', version.id);
+        if (candidateOwner && candidateOwner !== op.id)
+            reject('OUTC1011', 'The candidate already has an evaluation reservation.');
+        let changes = 0;
+        if (!owner) {
+            await unique(tx, c.scopeId, 'evaluationSlotOwner', slotKey, op.id);
+            changes++;
+        }
+        if (!candidateOwner) {
+            await unique(tx, c.scopeId, 'evaluationCandidateOwner', version.id, op.id);
+            changes++;
+        }
+        if (changes) {
+            const current = await tx.get('operations', op.id);
+            if (!current || current.attempt !== op.attempt)
+                reject('OUTC1019', 'Evaluation reservation changed.');
+            await tx.put('operations', { ...current, preparationWrites: current.preparationWrites + changes + 1 });
+        }
+        return { version, reflection, training };
+    });
+}
+export async function prepareEvaluation(context, c, op) {
+    const data = await reserveEvaluation(context, c, op);
+    // An existing registration is the retained exact corpus after a retry.
+    const retained = await context.atomic().transaction(async (tx) => {
+        const id = await semantic(tx, c.scopeId, 'evaluationRegistration', data.version.id);
+        return id ? recordOf(tx, id, c.scopeId, c.artifactKey, 'evaluationRegistration') : null;
+    });
+    if (retained)
+        return { ...data, registration: retained };
+    if (!context.evaluationSlot)
+        reject('OUTC1011', 'A trusted held-out registration provider is required.');
+    const raw = await context.evaluationSlot(c.input.slotId, data.version.id, context.scope);
+    let slot;
+    try {
+        slot = checkShape('evaluationSlot', raw);
+    }
+    catch {
+        reject('OUTC1011', 'The host supplied an invalid or missing held-out registration.');
+    }
+    if (slot.slotId !== c.input.slotId || slot.versionId !== data.version.id || !equalsJson(slot.expectedHead, data.version.expectedHead) || !equalsJson([...slot.trainingScoreIds].sort(), data.reflection.scoreIds) || slot.gatePolicyId !== context.gatePolicyId)
+        reject('OUTC1011', 'Held-out registration bindings differ.');
+    if (jsonBytes(asJson(slot)) > 262144)
+        reject('OUTC1011', 'Held-out registration exceeds 262,144 canonical UTF-8 bytes.');
+    const trainingIds = new Set(data.training.map(t => t.decision.decisionKey)), trainingDigests = new Set(data.training.map(t => t.contentDigest));
+    const content = new Set(), names = new Set();
+    for (const item of slot.cases) {
+        if (names.has(item.id) || trainingIds.has(item.id))
+            reject('OUTC1011', 'Training and held-out case ids must be disjoint and unique.');
+        names.add(item.id);
+        const source = await verifiedSource(context, { sourceId: item.source.sourceId, digest: item.source.digest }, '0000-01-01T00:00:00.000Z', c.at);
+        if (source.decisionId !== null || !equalsJson(source, item.source))
+            reject('OUTC1006', 'Held-out evidence snapshot differs from its independent source.');
+        const digest = await outcomeRevision({ domain: item.domain, input: item.input, outcome: source.payload });
+        if (content.has(digest) || trainingDigests.has(digest))
+            reject('OUTC1011', 'Training and held-out content must be disjoint and unique.');
+        content.add(digest);
+    }
+    const registration = await context.atomic().transaction(async (tx) => {
+        const current = await tx.get('operations', op.id);
+        if (!current || current.attempt !== op.attempt)
+            reject('OUTC1019', 'Evaluation attempt changed.');
+        for (const digest of content) {
+            const used = await semantic(tx, c.scopeId, 'heldOutContent', digest);
+            if (used && used !== data.version.id)
+                reject('OUTC1011', 'Previously consumed held-out content cannot be renamed or reused.');
+        }
+        const registration = await seal('evaluationRegistration', c.scopeId, c.artifactKey, c.at, slot);
+        await putRecord(tx, registration);
+        await unique(tx, c.scopeId, 'evaluationRegistration', data.version.id, registration.id);
+        for (const digest of content)
+            await unique(tx, c.scopeId, 'heldOutContent', digest, data.version.id);
+        await tx.put('operations', { ...current, preparationWrites: current.preparationWrites + 4 + content.size });
+        return registration;
+    });
+    return { ...data, registration };
+}
+export async function pairedResults(context, version, registration, baseline) {
+    const { adapter, domain } = context.adapter(version.adapter), rows = [], issues = [];
+    for (const c of registration.cases) {
+        try {
+            const input = domain.input(c.input), actual = domain.resolution(c.source.payload);
+            const output = domain.output(adapter.interpret(input, version.payload)), baselineOutput = domain.output(adapter.interpret(input, baseline));
+            const category = checkShape('category', adapter.score(output, actual).outcome), baselineCategory = checkShape('category', adapter.score(baselineOutput, actual).outcome);
+            rows.push({ id: c.id, contentDigest: await outcomeRevision({ domain: c.domain, input: c.input, outcome: c.source.payload }), output, baselineOutput, category, baselineCategory, utility: scoreUtility(category), baselineUtility: scoreUtility(baselineCategory) });
+        }
+        catch {
+            issues.push(issue('OUTC1011', `Held-out case could not be scored: ${c.id}.`));
+        }
+    }
+    return { rows, issues };
+}
+export async function baselinePayload(tx, context, version) {
+    if (version.parentVersionId === null)
+        return context.adapter(version.adapter).adapter.staticPayload;
+    const parent = await recordOf(tx, version.parentVersionId, version.scopeId, version.artifactKey, 'artifactVersion');
+    if (!equalsJson(parent.adapter, version.adapter) || parent.policyId !== version.policyId)
+        reject('OUTC1008', 'Evaluation parent adapter or policy differs.');
+    return parent.payload;
+}
+export async function commitEvaluation(tx, context, c, data) {
+    const exists = await semantic(tx, c.scopeId, 'evaluation', data.version.id);
+    if (exists)
+        reject('OUTC1007', `The evaluation stage is already complete: ${exists}.`);
+    const { rows, issues } = await pairedResults(context, data.version, data.registration, await baselinePayload(tx, context, data.version));
+    const base = { versionId: data.version.id, registrationId: data.registration.id, expectedHead: data.version.expectedHead, trainingScoreIds: data.reflection.scoreIds, caseResults: rows,
+        caseReportId: await outcomeRevision(rows), evaluatorRevision: data.registration.evaluatorRevision, gatePolicyId: data.registration.gatePolicyId,
+        eligible: false, issues, meanDelta: rows.length === data.registration.cases.length ? rows.reduce((n, c) => n + c.utility - c.baselineUtility, 0) / rows.length : null,
+        physicalRequests: 0, cost: 0,
+    };
+    const provisional = await seal('evaluation', c.scopeId, c.artifactKey, c.at, base);
+    const gates = eligibilityIssues(provisional, data.registration, data.version);
+    const evaluation = await seal('evaluation', c.scopeId, c.artifactKey, c.at, { ...base, issues: gates, eligible: gates.length === 0 });
+    await putRecord(tx, evaluation);
+    await unique(tx, c.scopeId, 'evaluation', data.version.id, evaluation.id);
+    return { evaluationId: evaluation.id, eligible: evaluation.eligible, issues: asJson(evaluation.issues), caseReportId: evaluation.caseReportId };
+}
+/** Recompute from retained independent bytes at the authority boundary. */
+export async function checkedEvaluation(tx, context, version, evaluation) {
+    const registration = await recordOf(tx, evaluation.registrationId, version.scopeId, version.artifactKey, 'evaluationRegistration');
+    const reflection = await recordOf(tx, version.reflectionId, version.scopeId, version.artifactKey, 'reflection');
+    const training = await trainingRecords(tx, context, version.artifactKey, reflection.scoreIds, version.recordedAt);
+    if (version.policyId !== context.policyId || await outcomeRevision(version.policy) !== version.policyId || version.payloadSchema !== version.adapter.artifactSchema || !equalsJson(version.adapter, training[0].decision.adapter) || registration.gatePolicyId !== context.gatePolicyId || !equalsJson(evaluation.trainingScoreIds, reflection.scoreIds) || !equalsJson(registration.trainingScoreIds, reflection.scoreIds) || !equalsJson(version.expectedHead, registration.expectedHead))
+        reject('OUTC1008', 'Checked artifact identity bindings differ.');
+    const baseline = await baselinePayload(tx, context, version);
+    context.adapter(version.adapter).domain.artifact(version.payload);
+    const actual = await pairedResults(context, version, registration, baseline);
+    if (actual.issues.length || !equalsJson(actual.rows, evaluation.caseResults) || await outcomeRevision(actual.rows) !== evaluation.caseReportId)
+        reject('OUTC1011', 'Retrospective result bytes do not reproduce.');
+    const trainingContent = new Set(training.map(t => t.contentDigest)), trainingIds = new Set(training.map(t => t.decision.decisionKey));
+    const content = new Set();
+    for (const c of registration.cases) {
+        const { digest, ...bytes } = c.source;
+        checkTime(c.source.observedAt);
+        const hash = await outcomeRevision({ domain: c.domain, input: c.input, outcome: c.source.payload });
+        if (await outcomeRevision(bytes) !== digest || c.source.scopeId !== context.scopeId || c.source.subject !== context.scope.subject || c.source.decisionId !== null || content.has(hash) || trainingContent.has(hash) || trainingIds.has(c.id))
+            reject('OUTC1011', 'Retained held-out evidence is not disjoint or valid.');
+        content.add(hash);
+    }
+    const issues = eligibilityIssues(evaluation, registration, version);
+    if (!evaluation.eligible || issues.length)
+        throw new OutcomeRefusal(issues.length ? issues : [issue('OUTC1011', 'The evaluation is ineligible.')]);
+    return registration;
+}

package/src/handlers.d.ts

@@ -0,0 +1,15 @@
+/** One dispatch table over the direct service; no transport-owned business ledger. */
+import type { Handler, RequestContext } from '@jarenjs/contract/http';
+import type { OutcomeService } from './service.ts';
+export declare const OUTCOME_MODEL_OPERATIONS: readonly string[];
+export interface OutcomeHandlerBinding {
+    /** Constructed with this authenticated host's principal and registry. */
+    service: OutcomeService;
+    /** Host scope access policy, evaluated before every read, write and replay. */
+    allowScope(scopeId: string, context: RequestContext): boolean | Promise<boolean>;
+}
+export interface OutcomeHandlerOptions {
+    /** A closure for local calls, or a resolver of already authenticated HTTP ctx.host. */
+    resolveHost(context: RequestContext): OutcomeHandlerBinding | undefined | Promise<OutcomeHandlerBinding | undefined>;
+}
+export declare function createOutcomeHandlers(options: OutcomeHandlerOptions): Record<string, Handler>;

package/src/handlers.js

@@ -0,0 +1,18 @@
+import { refuse } from "./errors.js";
+const methods = {
+    'outcomes.create': 'create', 'outcomes.resolve': 'resolve', 'outcomes.score': 'score',
+    'outcomes.project': 'project', 'outcomes.reflect': 'reflect', 'outcomes.evaluate': 'evaluate',
+    'outcomes.approve': 'approve', 'outcomes.promote': 'promote', 'outcomes.rollback': 'rollback',
+    'outcomes.inject': 'injectChecked', 'outcomes.inspect': 'inspect', 'outcomes.history': 'history',
+    'outcomes.reconcile': 'reconcile',
+};
+export const OUTCOME_MODEL_OPERATIONS = Object.freeze(Object.keys(methods).filter(id => id !== 'outcomes.approve' && id !== 'outcomes.reconcile'));
+export function createOutcomeHandlers(options) {
+    return Object.fromEntries(Object.entries(methods).map(([id, method]) => [id, async (input, context) => {
+            const binding = await options.resolveHost(context);
+            const scopeId = input?.scopeId;
+            if (!binding || typeof scopeId !== 'string' || !await binding.allowScope(scopeId, context))
+                return refuse('OUTC1003', 'The authenticated host refused scope access.');
+            return await binding.service[method](input);
+        }]));
+}

package/src/history.d.ts

@@ -0,0 +1,4 @@
+import type { ServiceContext } from './service-context.ts';
+import type { HistoryCommand, HistoryPage, InspectCommand, Inspection, OutcomeRecord } from './outcomes.contracts.gen.ts';
+export declare function historyPage(context: ServiceContext, command: HistoryCommand): Promise<HistoryPage>;
+export declare function inspectRecord(context: ServiceContext, command: InspectCommand): Promise<OutcomeRecord | Inspection>;

package/src/history.js

@@ -0,0 +1,56 @@
+/** Snapshot-bounded audit paging and finite immutable ancestry inspection. */
+import { checkShape } from "./schema.js";
+import { keyId, outcomeRevision } from "./identity.js";
+import { readRecord } from "./persistence.js";
+import { reject } from "./errors.js";
+export async function historyPage(context, command) {
+    return context.atomic().transaction(async (tx) => {
+        const { scopeId, artifactKey, input } = command;
+        const sequenceId = await keyId(scopeId, 'sequence', null);
+        const sequence = await tx.get('keys', sequenceId);
+        const current = sequence?.value ?? 0;
+        if (!Number.isSafeInteger(current) || Number(current) < 0 || (sequence && (sequence.id !== sequenceId || sequence.scopeId !== scopeId)))
+            reject('OUTC1002', 'Audit sequence is corrupted.');
+        const filterId = await outcomeRevision({ scopeId, artifactKey, revision: 'outcome-history/v1', kind: 'all' });
+        const cursor = input.cursor;
+        if (cursor && (cursor.scopeId !== scopeId || cursor.artifactKey !== artifactKey || cursor.filterId !== filterId))
+            reject('OUTC1003', 'Cursor scope or filter differs.');
+        const upper = cursor?.upper ?? Number(current), after = cursor?.after ?? 0;
+        if (after > upper || upper > Number(current))
+            reject('OUTC1001', 'Cursor sequence is invalid.');
+        const pageSize = input.pageSize ?? 50;
+        const rows = await tx.query('records', { scopeId, artifactKey, after, upper, limit: pageSize + 1 });
+        const entries = [];
+        let previous = after;
+        for (const row of rows.slice(0, pageSize)) {
+            checkShape('storedRecord', row);
+            if (row.seq <= previous || row.seq > upper)
+                reject('OUTC1002', 'Audit ordering is corrupted.');
+            entries.push({ sequence: row.seq, record: await readRecord(tx, row.id, scopeId, artifactKey) });
+            previous = row.seq;
+        }
+        return { entries, upper, cursor: rows.length > pageSize ? { scopeId, artifactKey, filterId, after: previous, upper } : null };
+    });
+}
+export async function inspectRecord(context, command) {
+    return context.atomic().transaction(async (tx) => {
+        const record = await readRecord(tx, command.input.id, command.scopeId, command.artifactKey);
+        if (!command.input.includeLineage)
+            return record;
+        const lineage = [], visited = new Set();
+        let next = record.kind === 'artifactVersion' ? record.id : null;
+        while (next !== null) {
+            if (visited.has(next) || lineage.length >= context.policy.maxVersions)
+                reject('OUTC1002', 'Artifact ancestry cycles or exceeds its retained bound.');
+            visited.add(next);
+            const version = await readRecord(tx, next, command.scopeId, command.artifactKey);
+            if (version.kind !== 'artifactVersion')
+                reject('OUTC1002', 'Artifact ancestry points to another record kind.');
+            if (record.kind === 'artifactVersion' && (version.policyId !== record.policyId || version.adapter.revision !== record.adapter.revision || version.payloadSchema !== record.payloadSchema))
+                reject('OUTC1002', 'Artifact ancestry revisions differ.');
+            lineage.push(version);
+            next = version.parentVersionId;
+        }
+        return { record, lineage };
+    });
+}

package/src/identity.d.ts

@@ -0,0 +1,9 @@
+/** Immutable addresses include every semantic field, except the address itself. */
+import { canonicalSha256 } from '@jarenjs/json/canonical';
+import type { OutcomeRecord, Json } from './outcomes.contracts.gen.ts';
+export declare const outcomeRevision: typeof canonicalSha256;
+export declare function scopeIdOf(value: unknown): Promise<string>;
+export declare function recordIdOf(value: Omit<OutcomeRecord, 'id'> | OutcomeRecord): Promise<string>;
+export declare function validateRecord(value: unknown): Promise<OutcomeRecord>;
+export declare function sealRecord(value: unknown): Promise<OutcomeRecord>;
+export declare const keyId: (scopeId: string, kind: string, value: Json) => Promise<string>;

package/src/identity.js

@@ -0,0 +1,17 @@
+/** Immutable addresses include every semantic field, except the address itself. */
+import { canonicalSha256 } from '@jarenjs/json/canonical';
+import { checkRecordShape, checkShape } from "./schema.js";
+import { reject } from "./errors.js";
+export const outcomeRevision = canonicalSha256;
+export async function scopeIdOf(value) { return canonicalSha256(checkShape('scope', value)); }
+export async function recordIdOf(value) { const { id: _, ...data } = value; return canonicalSha256(data); }
+export async function validateRecord(value) {
+    const r = checkRecordShape(value);
+    if (await recordIdOf(r) !== r.id)
+        reject('OUTC1002', 'Immutable record bytes do not match their id.');
+    if (r.kind === 'decision' && await scopeIdOf(r.scope) !== r.scopeId)
+        reject('OUTC1003', 'Decision scope does not match its id.');
+    return r;
+}
+export async function sealRecord(value) { const data = value; const id = await canonicalSha256(data); return validateRecord({ ...data, id }); }
+export const keyId = (scopeId, kind, value) => canonicalSha256({ scopeId, kind, value });

package/src/index.d.ts

@@ -0,0 +1,15 @@
+/** Evidenced decision records and atomic, host-injected persistence. */
+export { outcomesSchema, DEFAULT_OUTCOME_POLICY } from './schema.ts';
+export { scopeIdOf, recordIdOf, validateRecord, outcomeRevision } from './identity.ts';
+export { createMemoryOutcomeStore, createOutcomeStoreAdapter } from './store.ts';
+export type { OutcomeStore, OutcomePersistence, OutcomeTransaction, Tables, Query, MemoryOutcomeStoreOptions } from './store.ts';
+export type { OutcomeAdapter, EvidenceResolver, EvaluationSlot, OutcomeHost, OutcomePrincipal, OutcomeProposer } from './adapters.ts';
+export type { OutcomeResult, OutcomeIssue } from './errors.ts';
+export { EMPTY_HEAD, planHeadTransition, assertCapacity, planPromotion, eligibilityIssues } from './transitions.ts';
+export type * from './outcomes.contracts.gen.ts';
+export { createOutcomeService } from './service.ts';
+export type { OutcomeService, OutcomeServiceOptions } from './service.ts';
+export { changedLeafPaths, preparePayload } from './refinement.ts';
+export { outcomeGatePolicyId, RETROSPECTIVE_RULES } from './evaluation.ts';
+export { createOutcomeContract, outcomeContractDocument, createOutcomeHandlers, OUTCOME_MODEL_OPERATIONS } from './contract.ts';
+export type { OutcomeHandlerOptions, OutcomeHandlerBinding } from './handlers.ts';

package/src/index.js

@@ -0,0 +1,9 @@
+/** Evidenced decision records and atomic, host-injected persistence. */
+export { outcomesSchema, DEFAULT_OUTCOME_POLICY } from "./schema.js";
+export { scopeIdOf, recordIdOf, validateRecord, outcomeRevision } from "./identity.js";
+export { createMemoryOutcomeStore, createOutcomeStoreAdapter } from "./store.js";
+export { EMPTY_HEAD, planHeadTransition, assertCapacity, planPromotion, eligibilityIssues } from "./transitions.js";
+export { createOutcomeService } from "./service.js";
+export { changedLeafPaths, preparePayload } from "./refinement.js";
+export { outcomeGatePolicyId, RETROSPECTIVE_RULES } from "./evaluation.js";
+export { createOutcomeContract, outcomeContractDocument, createOutcomeHandlers, OUTCOME_MODEL_OPERATIONS } from "./contract.js";

package/src/operations.d.ts

@@ -0,0 +1,16 @@
+/** Request identity, capacity reservations and terminal replay belong to one owner. */
+import type { OutcomeStore, OutcomeTransaction } from './store.ts';
+import type { Json, Operation, Result, Policy } from './outcomes.contracts.gen.ts';
+export interface OperationCommand {
+    scopeId: string;
+    artifactKey: string;
+    requestKey: string;
+    at: string;
+    input: unknown;
+}
+export declare function beginOperation(store: OutcomeStore, name: string, command: OperationCommand, policy?: Policy): Promise<{
+    operation: Operation;
+    replay?: Result;
+}>;
+export declare function recordAttempt(tx: OutcomeTransaction, op: Operation, stage: 'reserved' | 'dispatched' | 'ready' | 'retryable' | 'uncertain' | 'refused' | 'completed' | 'reconciled', at: string, details: Json): Promise<string>;
+export declare function finishOperation(store: OutcomeStore, op: Operation, at: string, apply: (tx: OutcomeTransaction) => Promise<Json>): Promise<Result>;

package/src/operations.js

@@ -0,0 +1,108 @@
+import { persistenceFor } from "./store.js";
+import { keyId, outcomeRevision, sealRecord } from "./identity.js";
+import { replay, complete, putRecord, unique } from "./persistence.js";
+import { assertCapacity } from "./transitions.js";
+import { checkTime } from "./schema.js";
+import { reject, OutcomeRefusal, refuse } from "./errors.js";
+export async function beginOperation(store, name, command, policy) {
+    checkTime(command.at);
+    const id = await keyId(command.scopeId, 'request', command.requestKey), inputDigest = await outcomeRevision({ name, command });
+    let created;
+    try {
+        return await persistenceFor(store).transaction(async (tx) => {
+            const old = await tx.get('operations', id);
+            if (old) {
+                const result = await replay(tx, old, inputDigest);
+                if (result)
+                    return { operation: old, replay: result };
+                if (old.state === 'reserved')
+                    reject('OUTC1019', 'The operation is already in progress.');
+                if (old.state === 'ready')
+                    return { operation: old };
+            }
+            if (policy && !(old?.capacityReserved)) {
+                const versions = await tx.query('records', { scopeId: command.scopeId, artifactKey: command.artifactKey, kind: 'artifactVersion', limit: policy.maxVersions + 1 });
+                const reservations = await tx.query('operations', { scopeId: command.scopeId, artifactKey: command.artifactKey, reservedOnly: true, limit: policy.maxVersions + 1 });
+                assertCapacity(versions.length, reservations.length, policy.maxVersions);
+            }
+            const operation = { id, scopeId: command.scopeId, artifactKey: command.artifactKey, requestKey: command.requestKey, operation: name, inputDigest, state: old?.output !== null && old?.output !== undefined ? 'ready' : 'reserved', receiptId: null, output: old?.output ?? null, capacityReserved: policy !== undefined, attempt: (old?.attempt ?? 0) + 1, preparationWrites: (old?.preparationWrites ?? 0) + 4 };
+            created = operation;
+            const reservationId = await recordAttempt(tx, operation, 'reserved', command.at, { operation: name, requestKey: command.requestKey });
+            await unique(tx, command.scopeId, 'reservationReceipt', [operation.id, operation.attempt], reservationId);
+            await tx.put('operations', operation);
+            return { operation };
+        });
+    }
+    catch (error) {
+        if (error instanceof OutcomeRefusal)
+            throw error;
+        if (created)
+            return { operation: created, replay: await recoverOperation(store, created, command.at, true) };
+        throw error;
+    }
+}
+export async function recordAttempt(tx, op, stage, at, details) {
+    const record = await sealRecord({ schemaVersion: 1, kind: 'attemptEvent', scopeId: op.scopeId, artifactKey: op.artifactKey, recordedAt: at, requestId: op.id, stage, inputDigest: op.inputDigest, details: { attempt: op.attempt, value: details } });
+    await putRecord(tx, record);
+    return record.id;
+}
+async function recoverOperation(store, op, at, allowAbsent = false) {
+    try {
+        return await persistenceFor(store).transaction(async (tx) => {
+            const current = await tx.get('operations', op.id);
+            if (!current)
+                return allowAbsent ? refuse('OUTC1015', 'The reservation rolled back; retry the same request.', '', true) : refuse('OUTC1002', 'Operation reservation disappeared.');
+            if (current.state === 'completed')
+                return (await replay(tx, current, op.inputDigest));
+            if (current.attempt !== op.attempt)
+                return refuse('OUTC1019', 'A different attempt owns this operation.');
+            const state = current.state === 'dispatched' || current.state === 'uncertain' ? 'uncertain' : 'retryable';
+            await recordAttempt(tx, current, state, at, { code: state === 'uncertain' ? 'OUTC1017' : 'OUTC1015' });
+            await tx.put('operations', { ...current, state, preparationWrites: current.preparationWrites + 3 });
+            return state === 'uncertain' ? refuse('OUTC1017', 'External completion is uncertain; reconcile before retry.') : refuse('OUTC1015', 'The transaction rolled back; retry the same request.', '', true);
+        });
+    }
+    catch {
+        return refuse('OUTC1017', 'Commit acknowledgement and recovery are unavailable.');
+    }
+}
+export async function finishOperation(store, op, at, apply) {
+    try {
+        return await persistenceFor(store).transaction(async (raw) => {
+            const current = await raw.get('operations', op.id);
+            if (!current)
+                reject('OUTC1002', 'Operation reservation disappeared.');
+            const old = await replay(raw, current, op.inputDigest);
+            if (old)
+                return old;
+            if (current.attempt !== op.attempt)
+                reject('OUTC1019', 'A different attempt owns this operation.');
+            let writes = 0;
+            const tx = { ...raw, async put(table, value) { await raw.put(table, value); writes++; }, async delete(table, id) { await raw.delete(table, id); writes++; } };
+            const value = await apply(tx);
+            const result = { ok: true, value, replayed: false, writes: writes + current.preparationWrites + 3 };
+            await complete(tx, current, result, at);
+            return result;
+        });
+    }
+    catch (error) {
+        if (error instanceof OutcomeRefusal && !error.issues.some(i => i.retryable || i.code === 'OUTC1017')) {
+            const result = { ok: false, issues: error.issues };
+            try {
+                return await persistenceFor(store).transaction(async (tx) => {
+                    const current = await tx.get('operations', op.id);
+                    if (!current || current.attempt !== op.attempt)
+                        return refuse('OUTC1019', 'A different attempt owns this operation.');
+                    if (current.state === 'completed')
+                        return (await replay(tx, current, op.inputDigest));
+                    await complete(tx, current, result, at);
+                    return result;
+                });
+            }
+            catch {
+                return recoverOperation(store, op, at);
+            }
+        }
+        return recoverOperation(store, op, at);
+    }
+}