@tangleai/outcomes 0.24.1

package/src/service.js

@@ -0,0 +1,159 @@
+/** Explicit lifecycle commands. External host work runs outside transactions. */
+import { historyPage, inspectRecord } from "./history.js";
+import { equalsJson } from '@jarenjs/core/object';
+import { checkShape, checkTime } from "./schema.js";
+import { failure, reject } from "./errors.js";
+import { keyId } from "./identity.js";
+import { beginOperation, finishOperation } from "./operations.js";
+import { readRecord, putRecord, unique, headFor } from "./persistence.js";
+import { makeContext, asJson, recordOf, requireNew, seal } from "./service-context.js";
+import { prepareResolution, commitResolution } from "./resolution.js";
+import { prepareScore, commitScore } from "./scoring.js";
+import { prepareProjection, commitProjection } from "./projection.js";
+import { reflectionContext, commitReflection } from "./refinement.js";
+import { prepareEvaluation, commitEvaluation } from "./evaluation.js";
+import { commitApproval, commitActivation, checkedHead } from "./promotion.js";
+import { modelProposal, prepareReconciliation, commitReconciliation } from "./proposal-operation.js";
+const liveReflections = new WeakMap();
+export async function createOutcomeService(options) {
+    const context = await makeContext(options);
+    function boundary(shape, value) {
+        const c = checkShape(shape, value);
+        if (c.scopeId !== context.scopeId)
+            reject('OUTC1003', 'Request scope differs from its host.');
+        context.atomic();
+        return c;
+    }
+    async function mutate(name, raw, prepare, commit) {
+        try {
+            const c = boundary(`${name}Command`, raw);
+            checkTime(c.at);
+            if ((name === 'approve' && !context.principal.approve) || (name === 'reconcile' && !context.principal.reconcile))
+                reject('OUTC1012', 'The host principal lacks this capability.');
+            const reservation = await beginOperation(context.store, name, c);
+            if (reservation.replay)
+                return reservation.replay;
+            let data;
+            try {
+                data = await prepare(c, reservation.operation);
+            }
+            catch (error) {
+                return await finishOperation(context.store, reservation.operation, c.at, async () => { throw error; });
+            }
+            return await finishOperation(context.store, reservation.operation, c.at, tx => commit(tx, c, data));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    }
+    return Object.freeze({
+        scopeId: context.scopeId,
+        policyId: context.policyId,
+        gatePolicyId: context.gatePolicyId,
+        create: (raw) => mutate('create', raw, async (c) => {
+            const i = c.input;
+            checkTime(i.cutoffAt);
+            checkTime(i.decidedAt);
+            if (i.expectedResolutionAt !== null)
+                checkTime(i.expectedResolutionAt);
+            if (i.cutoffAt > i.decidedAt || c.at < i.decidedAt || (i.expectedResolutionAt !== null && i.expectedResolutionAt < i.decidedAt))
+                reject('OUTC1001', 'Decision chronology is invalid.');
+            const { domain } = context.adapter(i.adapter);
+            domain.input(i.input);
+            domain.output(i.output);
+            domain.artifact(i.staticPayload);
+            await context.configuration(i.configuration);
+            await context.authorization([...new Set(i.memoryIds)].sort());
+        }, async (tx, c) => {
+            const i = c.input, { adapter, domain } = context.adapter(i.adapter);
+            await requireNew(tx, c.scopeId, 'decision', i.decisionKey);
+            if (!equalsJson(domain.artifact(i.staticPayload), domain.artifact(adapter.staticPayload)))
+                reject('OUTC1008', 'Static baseline differs from the registered adapter.');
+            if (i.usedVersionId !== null) {
+                const checked = await checkedHead(tx, context, c.artifactKey);
+                const version = await recordOf(tx, i.usedVersionId, c.scopeId, c.artifactKey, 'artifactVersion');
+                const head = await headFor(tx, c.scopeId, c.artifactKey);
+                if (head.versionId !== version.id || !equalsJson(version.adapter, i.adapter))
+                    reject('OUTC1013', 'Decision did not use the current checked artifact.');
+                if (!equalsJson(domain.output(adapter.interpret(i.input, checked.payload)), i.output))
+                    reject('OUTC1008', 'Decision output does not reproduce with its checked artifact.');
+            }
+            const decision = await seal('decision', c.scopeId, c.artifactKey, c.at, { ...i, scope: context.scope });
+            await putRecord(tx, decision);
+            await unique(tx, c.scopeId, 'decision', i.decisionKey, decision.id);
+            return { decisionId: decision.id };
+        }),
+        resolve: (raw) => mutate('resolve', raw, c => prepareResolution(context, c), (tx, c, data) => commitResolution(tx, context, c, data)),
+        score: (raw) => mutate('score', raw, c => prepareScore(context, c), (tx, c, data) => commitScore(tx, context, c, data)),
+        project: (raw) => mutate('project', raw, c => prepareProjection(context, c), (tx, c, data) => commitProjection(tx, context, c, data)),
+        async reflect(raw) {
+            let activeId;
+            let active = liveReflections.get(context.store);
+            if (!active) {
+                active = new Set();
+                liveReflections.set(context.store, active);
+            }
+            try {
+                const c = boundary('reflectCommand', raw);
+                checkTime(c.at);
+                const requestId = await keyId(c.scopeId, 'request', c.requestKey);
+                if (active.has(requestId))
+                    reject('OUTC1019', 'This proposal is already in progress in this host.');
+                activeId = requestId;
+                active.add(requestId);
+                const reservation = await beginOperation(context.store, 'reflect', c, context.policy);
+                if (reservation.replay)
+                    return reservation.replay;
+                try {
+                    const saved = reservation.operation.output === null ? null : checkShape('preparedModelOutput', reservation.operation.output);
+                    const data = await reflectionContext(context, c, saved?.head);
+                    const input = c.input.configuration.kind === 'scripted' ? c.input : await modelProposal(context, c, reservation.operation, data);
+                    return await finishOperation(context.store, reservation.operation, c.at, tx => commitReflection(tx, context, c, reservation.operation, data, input));
+                }
+                catch (error) {
+                    return await finishOperation(context.store, reservation.operation, c.at, async () => { throw error; });
+                }
+            }
+            catch (error) {
+                return failure(error);
+            }
+            finally {
+                if (activeId)
+                    active.delete(activeId);
+            }
+        },
+        evaluate: (raw) => mutate('evaluate', raw, (c, op) => prepareEvaluation(context, c, op), (tx, c, data) => commitEvaluation(tx, context, c, data)),
+        approve: (raw) => mutate('approve', raw, async (_c, op) => op, (tx, c, op) => commitApproval(tx, context, c, op)),
+        promote: (raw) => mutate('promote', raw, async () => { }, (tx, c) => commitActivation(tx, context, c, 'promote')),
+        rollback: (raw) => mutate('rollback', raw, async () => { }, (tx, c) => commitActivation(tx, context, c, 'rollback')),
+        reconcile: (raw) => mutate('reconcile', raw, c => prepareReconciliation(context, c), (tx, c, data) => commitReconciliation(tx, context, c, data)),
+        async injectChecked(raw) {
+            try {
+                const c = boundary('injectCommand', raw);
+                return { ok: true, value: await context.atomic().transaction(tx => checkedHead(tx, context, c.artifactKey)), writes: 0, replayed: false };
+            }
+            catch (error) {
+                return failure(error);
+            }
+        },
+        async history(raw) {
+            try {
+                const c = boundary('historyCommand', raw);
+                return { ok: true, value: asJson(await historyPage(context, c)), writes: 0, replayed: false };
+            }
+            catch (error) {
+                return failure(error);
+            }
+        },
+        async inspect(raw) {
+            try {
+                const c = boundary('inspectCommand', raw);
+                const value = await inspectRecord(context, c);
+                return { ok: true, value: asJson(value), writes: 0, replayed: false };
+            }
+            catch (error) {
+                return failure(error);
+            }
+        },
+    });
+}

package/src/store.d.ts

@@ -0,0 +1,42 @@
+import type { MemoryStore } from '@tangleai/memory/store';
+import type { MemoryUnit } from '@tangleai/core/schemas/memory';
+import type { StoredRecord, HeadRow, KeyRow, Operation } from './outcomes.contracts.gen.ts';
+export interface Tables {
+    records: StoredRecord;
+    keys: KeyRow;
+    heads: HeadRow;
+    operations: Operation;
+    memories: MemoryUnit;
+}
+export interface Query {
+    scopeId?: string;
+    artifactKey?: string;
+    kind?: string;
+    after?: number;
+    upper?: number;
+    limit?: number;
+    reservedOnly?: boolean;
+}
+export interface OutcomeTransaction {
+    get<K extends keyof Tables>(table: K, id: string): Promise<Tables[K] | undefined>;
+    put<K extends keyof Tables>(table: K, value: Tables[K]): Promise<void>;
+    delete<K extends keyof Tables>(table: K, id: string): Promise<void>;
+    query<K extends keyof Tables>(table: K, query: Query): Promise<Tables[K][]>;
+}
+/** Trusted persistence extension; never a wire operation. All changes must roll back on throw. */
+export interface OutcomePersistence {
+    transaction<T>(task: (view: OutcomeTransaction) => Promise<T>): Promise<T>;
+}
+export interface OutcomeStore {
+    readonly memories: MemoryStore;
+    readonly atomic: true;
+}
+export declare function checkedMemory(value: unknown): MemoryUnit;
+/** Package-internal access; not exported as a public subpath. */
+export declare function persistenceFor(store: OutcomeStore): OutcomePersistence;
+export declare function createOutcomeStoreAdapter(persistence: OutcomePersistence): OutcomeStore;
+export interface MemoryOutcomeStoreOptions {
+    memories?: readonly MemoryUnit[];
+    applyProbe?: (step: string) => void;
+}
+export declare function createMemoryOutcomeStore(options?: MemoryOutcomeStoreOptions): OutcomeStore;

package/src/store.js

@@ -0,0 +1,70 @@
+/** Opaque atomic store handles. The trusted adapter is injected at construction. */
+import { cloneJson } from '@jarenjs/core/object';
+import { JarenValidator } from '@jarenjs/validate';
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { MEMORY_UNIT_SCHEMA, MEMORY_RELATION_SCHEMA } from '@tangleai/core/schemas/memory';
+import { reject } from "./errors.js";
+const backends = new WeakMap();
+const memoryValidator = new JarenValidator({ collectErrors: true, unknownFormats: 'ignore' });
+memoryValidator.addSchema(MEMORY_RELATION_SCHEMA);
+const validateMemory = memoryValidator.compile(MEMORY_UNIT_SCHEMA);
+export function checkedMemory(value) {
+    try {
+        canonicalizeJson(value);
+    }
+    catch {
+        reject('OUTC1001', 'Memory must be finite JSON.');
+    }
+    if (!validateMemory(value).valid)
+        reject('OUTC1001', 'Memory schema rejected the value.');
+    return cloneJson(value);
+}
+/** Package-internal access; not exported as a public subpath. */
+export function persistenceFor(store) {
+    const p = backends.get(store);
+    if (!p)
+        throw new TypeError('Use an atomic outcome store factory.');
+    return p;
+}
+export function createOutcomeStoreAdapter(persistence) {
+    if (typeof persistence?.transaction !== 'function')
+        throw new TypeError('An atomic transaction adapter is required.');
+    const store = Object.freeze({ atomic: true, memories: {
+            get: (id) => persistence.transaction(tx => tx.get('memories', id)),
+            put: async (unit) => { const valid = checkedMemory(unit); await persistence.transaction(tx => tx.put('memories', valid)); },
+            delete: (id) => persistence.transaction(tx => tx.delete('memories', id)),
+            list: () => persistence.transaction(tx => tx.query('memories', {})),
+        } });
+    backends.set(store, persistence);
+    return store;
+}
+export function createMemoryOutcomeStore(options = {}) {
+    let state = { records: new Map(), keys: new Map(), heads: new Map(), operations: new Map(), memories: new Map() };
+    for (const m of options.memories ?? [])
+        state.memories.set(m.id, checkedMemory(m));
+    let pending = Promise.resolve();
+    const persistence = { transaction(task) {
+            const result = pending.then(async () => {
+                const staged = Object.fromEntries(Object.entries(state).map(([k, v]) => [k, new Map([...v].map(([id, value]) => [id, cloneJson(value)]))]));
+                const view = {
+                    async get(table, id) { return cloneJson(staged[table].get(id)); },
+                    async put(table, value) { staged[table].set(value.id, cloneJson(value)); options.applyProbe?.(`put:${table}`); },
+                    async delete(table, id) { staged[table].delete(id); options.applyProbe?.(`delete:${table}`); },
+                    async query(table, q) {
+                        let rows = [...staged[table].values()].filter(v => { const r = v; return (!q.reservedOnly || r.capacityReserved === true) && (q.scopeId === undefined || r.scopeId === q.scopeId) && (q.artifactKey === undefined || r.artifactKey === q.artifactKey) && (q.kind === undefined || r.kind === q.kind) && (q.after === undefined || Number(r.seq) > q.after) && (q.upper === undefined || Number(r.seq) <= q.upper); });
+                        rows.sort((a, b) => { const x = a, y = b; return Number(x.seq ?? 0) - Number(y.seq ?? 0) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0); });
+                        if (q.limit !== undefined)
+                            rows = rows.slice(0, q.limit);
+                        return cloneJson(rows);
+                    },
+                };
+                const value = await task(view);
+                options.applyProbe?.('commit');
+                state = staged;
+                return value;
+            });
+            pending = result.then(() => undefined, () => undefined);
+            return result;
+        } };
+    return createOutcomeStoreAdapter(persistence);
+}

package/src/transitions.d.ts

@@ -0,0 +1,7 @@
+import type { Head, ArtifactVersion, Evaluation, EvaluationRegistration, Approval, Issue } from './outcomes.contracts.gen.ts';
+export declare const EMPTY_HEAD: Readonly<Head>;
+export declare function assertHead(actual: Head, expected: Head): void;
+export declare function planHeadTransition(actual: Head, expected: Head, target: string): Head;
+export declare function assertCapacity(retained: number, reserved: number, maximum: number): void;
+export declare function eligibilityIssues(e: Evaluation, r: EvaluationRegistration, v: ArtifactVersion): Issue[];
+export declare function planPromotion(actual: Head, v: ArtifactVersion, e: Evaluation, r: EvaluationRegistration, a: Approval): Head;

package/src/transitions.js

@@ -0,0 +1,56 @@
+/** Pure outcome transition guards; adapters do not define their own state machine. */
+import { equalsJson } from '@jarenjs/core/object';
+import { issue, reject, OutcomeRefusal } from "./errors.js";
+import { scoreUtility } from "./domain.js";
+export const EMPTY_HEAD = Object.freeze({ versionId: null, revision: 0 });
+export function assertHead(actual, expected) {
+    if (!equalsJson(actual, expected))
+        reject('OUTC1013', 'The expected head version or revision is stale.', '/expectedHead');
+}
+export function planHeadTransition(actual, expected, target) { assertHead(actual, expected); return { versionId: target, revision: actual.revision + 1 }; }
+export function assertCapacity(retained, reserved, maximum) {
+    if (retained + reserved >= maximum)
+        reject('OUTC1014', 'Artifact version capacity is exhausted.');
+}
+export function eligibilityIssues(e, r, v) {
+    const errors = [...e.issues];
+    const add = (detail) => errors.push(issue('OUTC1011', detail));
+    if (e.versionId !== v.id || r.versionId !== v.id || e.registrationId !== r.id || e.gatePolicyId !== r.gatePolicyId || e.evaluatorRevision !== r.evaluatorRevision || !equalsJson(e.expectedHead, r.expectedHead))
+        add('Evaluation identity bindings differ.');
+    if (v.issues.length)
+        errors.push(...v.issues);
+    if (!equalsJson(v.expectedHead, r.expectedHead) || v.parentVersionId !== r.expectedHead.versionId || !equalsJson(e.trainingScoreIds, r.trainingScoreIds))
+        add('Parent or training bindings differ.');
+    if (!r.cases.length || e.caseResults.length !== r.cases.length || new Set(e.caseResults.map(c => c.id)).size !== r.cases.length || !equalsJson(e.caseResults.map(c => c.id).sort(), r.cases.map(c => c.id).sort()))
+        add('Evaluation coverage is incomplete.');
+    const n = e.caseResults.length, delta = n ? e.caseResults.reduce((s, c) => s + c.utility - c.baselineUtility, 0) / n : null;
+    if (delta === null || delta <= 0 || e.meanDelta !== delta)
+        add('Paired held-out utility did not strictly improve.');
+    if (e.physicalRequests > r.maxPhysicalRequests)
+        add('The registered call bound was exceeded.');
+    if (r.maxCost !== null && (e.cost === null || e.cost > r.maxCost))
+        add('Known cost within the registered monetary bound is required.');
+    if (e.caseResults.some(c => c.utility !== scoreUtility(c.category) || c.baselineUtility !== scoreUtility(c.baselineCategory)))
+        add('Case utility differs from its scored category.');
+    for (const domain of new Set(r.cases.map(c => c.domain))) {
+        const ids = new Set(r.cases.filter(c => c.domain === domain).map(c => c.id));
+        if (e.caseResults.filter(c => ids.has(c.id)).reduce((s, c) => s + c.utility - c.baselineUtility, 0) < 0)
+            add('A registered domain regressed.');
+    }
+    return errors;
+}
+export function planPromotion(actual, v, e, r, a) {
+    if (new Set([v.scopeId, e.scopeId, r.scopeId, a.scopeId]).size !== 1 || new Set([v.artifactKey, e.artifactKey, r.artifactKey, a.artifactKey]).size !== 1)
+        reject('OUTC1003', 'Promotion records cross scope or lineage.');
+    assertHead(actual, a.expectedHead);
+    if (a.action !== 'promote' || a.versionId !== v.id || a.evaluationId !== e.id || a.gatePolicyId !== e.gatePolicyId || !equalsJson(a.expectedHead, e.expectedHead))
+        reject('OUTC1012', 'Approval does not bind this promotion.');
+    if (v.parentVersionId !== actual.versionId)
+        reject('OUTC1013', 'The candidate parent is stale.');
+    const issues = eligibilityIssues(e, r, v);
+    if (issues.length)
+        throw new OutcomeRefusal(issues);
+    if (!e.eligible)
+        reject('OUTC1011', 'The evaluation is ineligible.');
+    return planHeadTransition(actual, a.expectedHead, v.id);
+}