tracegrove 0.0.0-stage → 0.3.1

package/dist/core/coordination.js

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import { Conflict } from "./errors.js";
+const Key = z.string().min(1).max(256);
+const Counter = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const LeaseDuration = Counter.positive().max(300_000);
+const LeaseSchema = z.object({
+    attemptId: Key, workerId: Key, personaId: Key, generation: Counter.positive(),
+    expiresAt: Counter, reservedCents: Counter.positive(),
+    state: z.enum(['active', 'reconciling', 'released']),
+    effectIds: z.array(Key), cleanupProof: Key.nullable(),
+}).strict();
+export const CoordinationSnapshotSchema = z.object({
+    scopeId: Key, version: Counter, generation: Counter, budgetCents: Counter.positive(),
+    leases: z.array(LeaseSchema),
+}).strict().superRefine((snapshot, ctx) => {
+    const attempts = new Set();
+    const personas = new Set();
+    let reserved = BigInt(0);
+    for (const lease of snapshot.leases) {
+        if (attempts.has(lease.attemptId) || lease.generation > snapshot.generation ||
+            new Set(lease.effectIds).size !== lease.effectIds.length ||
+            (lease.state === 'released') !== (lease.cleanupProof !== null)) {
+            ctx.addIssue({ code: 'custom', message: 'Invalid coordination history' });
+        }
+        attempts.add(lease.attemptId);
+        if (lease.state !== 'released') {
+            if (personas.has(lease.personaId))
+                ctx.addIssue({ code: 'custom', message: 'Persona has multiple owners' });
+            personas.add(lease.personaId);
+        }
+        reserved += BigInt(lease.reservedCents);
+    }
+    if (reserved > BigInt(snapshot.budgetCents))
+        ctx.addIssue({ code: 'custom', message: 'Coordination budget exceeded' });
+});
+export const CoordinationCommandSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('reserve'), attemptId: Key, workerId: Key, personaId: Key,
+        reservedCents: Counter.positive(), ttlMs: LeaseDuration }).strict(),
+    z.object({ type: z.literal('heartbeat'), attemptId: Key, workerId: Key, generation: Counter.positive(),
+        ttlMs: LeaseDuration }).strict(),
+    z.object({ type: z.literal('effect'), attemptId: Key, workerId: Key, generation: Counter.positive(), effectId: Key }).strict(),
+    z.object({ type: z.literal('recover'), attemptId: Key, workerId: Key, ttlMs: LeaseDuration }).strict(),
+    z.object({ type: z.literal('release'), attemptId: Key, workerId: Key, generation: Counter.positive(), cleanupProof: Key }).strict(),
+]);
+/** Pure transition only. The trusted storage owner supplies time, CAS and cleanup proof admission. */
+export function transitionCoordination(raw, scopeId, expectedVersion, input, observedAt) {
+    const state = CoordinationSnapshotSchema.parse(raw);
+    const command = CoordinationCommandSchema.parse(input);
+    Counter.parse(observedAt);
+    if (state.scopeId !== scopeId || state.version !== expectedVersion)
+        throw new Conflict('Coordination scope or version changed');
+    if (state.version === Number.MAX_SAFE_INTEGER || state.generation === Number.MAX_SAFE_INTEGER)
+        throw new Conflict('Coordination counter exhausted');
+    const lease = state.leases.find(item => item.attemptId === command.attemptId);
+    if (command.type === 'reserve') {
+        if (lease)
+            throw new Conflict('Attempt already reserved; reconcile its existing reservation');
+        // Expiry alone cannot make a persona safe to reuse: cleanup must be independently admitted.
+        if (state.leases.some(item => item.personaId === command.personaId && item.state !== 'released'))
+            throw new Conflict('Persona requires reconciliation');
+        const spent = state.leases.reduce((sum, item) => sum + BigInt(item.reservedCents), BigInt(0));
+        if (spent + BigInt(command.reservedCents) > BigInt(state.budgetCents))
+            throw new Conflict('Shared coordination budget exhausted');
+        state.generation++;
+        state.leases.push({ attemptId: command.attemptId, workerId: command.workerId, personaId: command.personaId,
+            reservedCents: command.reservedCents, generation: state.generation, expiresAt: observedAt + command.ttlMs,
+            state: 'active', effectIds: [], cleanupProof: null });
+    }
+    else {
+        if (!lease || lease.state === 'released')
+            throw new Conflict('No active coordination lease');
+        if (command.type === 'recover') {
+            if (lease.expiresAt > observedAt)
+                throw new Conflict('Coordination lease has not expired');
+            state.generation++;
+            lease.generation = state.generation;
+            lease.workerId = command.workerId;
+            lease.state = 'reconciling';
+            lease.expiresAt = observedAt + command.ttlMs;
+            // Recovery admits cleanup/readback only. It never replays an uncertain effect.
+        }
+        else {
+            if (lease.workerId !== command.workerId || lease.generation !== command.generation)
+                throw new Conflict('Stale coordination fence');
+            if (lease.expiresAt <= observedAt)
+                throw new Conflict('Coordination lease expired; recover before continuing');
+            if (command.type === 'release') {
+                lease.state = 'released';
+                lease.cleanupProof = command.cleanupProof;
+            }
+            else {
+                if (command.type === 'heartbeat')
+                    lease.expiresAt = observedAt + command.ttlMs;
+                else {
+                    if (lease.state !== 'active')
+                        throw new Conflict('Coordination lease cannot admit effects');
+                    if (lease.effectIds.includes(command.effectId))
+                        throw new Conflict('Effect already admitted; reconcile its provider receipt');
+                    lease.effectIds.push(command.effectId);
+                }
+            }
+        }
+    }
+    state.version++;
+    return CoordinationSnapshotSchema.parse(state);
+}
+/** Not a distributed admission adapter: time, owner authentication and protected output fencing are adapter obligations. */
+export async function commitCoordination(store, scopeId, command) {
+    if (command.type === 'release')
+        throw new Conflict('Release requires the storage owner to admit an independent cleanup proof');
+    const { snapshot, observedAt } = await store.read(scopeId);
+    const current = CoordinationSnapshotSchema.parse(snapshot);
+    const next = transitionCoordination(current, scopeId, current.version, command, observedAt);
+    if (!await store.compareAndSwap(scopeId, current.version, next))
+        throw new Conflict('Coordination version changed; reload before admission');
+    return next;
+}
+//# sourceMappingURL=coordination.js.map

package/dist/core/coordination.js.map

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

package/dist/core/corpus.d.ts

@@ -0,0 +1,60 @@
+import type { z } from 'zod';
+import { CorpusManifest, WorkflowConfig, Suite, type Ref, type Scope, type SchemaVersion } from '../protocol/index.ts';
+export type LoadedDocument = {
+    ref: Ref;
+    schemaVersion: SchemaVersion;
+    value: unknown;
+    sourcePath: string;
+    sourceDigest: string;
+};
+/**
+ * Scope of the local actor: derived from the controller's process owner (or an explicit
+ * WORKFLOW_VERIFY_OWNER override). It is the requested scope on execution records only.
+ */
+export declare function localScope(): Scope;
+/**
+ * Scope stamped into reviewed authoring definitions when the file declares none. It is a
+ * constant so a definition's content digest is identical on every machine; a scope is never
+ * an access grant, and the controller derives real authority separately at admission.
+ */
+export declare const AUTHORING_SCOPE: Scope;
+export declare class CorpusStore {
+    readonly manifest: CorpusManifest;
+    private readonly byKey;
+    private readonly byIdRevision;
+    constructor(manifest: CorpusManifest, documents: LoadedDocument[]);
+    private add;
+    /** Exact ref lookup; verifies the stored bytes still hash to the requested digest. */
+    get(ref: Ref): LoadedDocument;
+    getAs<T extends z.ZodType<unknown>>(schema: T, ref: Ref): z.infer<T>;
+    has(ref: Ref): boolean;
+    documents(): LoadedDocument[];
+    findById(id: string): LoadedDocument[];
+}
+export type LoadedProject = {
+    root: string;
+    configPath: string;
+    config: WorkflowConfig;
+    configDigest: string;
+    suite: Suite;
+    suiteCases: Array<{
+        ref: Ref;
+        required: boolean;
+    }>;
+    corpus: CorpusStore;
+    /** Maps a project-relative file path to the frozen ref it produced. */
+    fileRefs: Map<string, Ref>;
+};
+export declare class ProjectLoader {
+    readonly root: string;
+    private readonly loaded;
+    private readonly loading;
+    private readonly scope;
+    constructor(root: string, scope?: Scope);
+    /** Load a referenced document, freezing nested `$file` references first. */
+    loadDocument(absPath: string): LoadedDocument;
+    private resolveFileRefs;
+    refFor(absPath: string): Ref;
+    documents(): LoadedDocument[];
+}
+export declare function loadProject(configPath: string, scope?: Scope): LoadedProject;

package/dist/core/corpus.js

@@ -0,0 +1,216 @@
+/**
+ * Project corpus: human-readable YAML/JSON authoring files beside the product source.
+ * `{ $file: './path' }` placeholders become frozen Refs of the loaded, validated, hashed
+ * document. The resolver publishes a frozen CorpusManifest; indexes are rebuildable.
+ */
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { userInfo } from 'node:os';
+import { parse as parseYaml } from 'yaml';
+import { CorpusManifest, RefSchema, SCHEMA_REGISTRY, SchemaViolation, WorkflowConfig, Suite, freeze, parseAs, refKey, sameDigest, selfDigest, sha256Hex, validateDocument, } from "../protocol/index.js";
+/**
+ * Scope of the local actor: derived from the controller's process owner (or an explicit
+ * WORKFLOW_VERIFY_OWNER override). It is the requested scope on execution records only.
+ */
+export function localScope() {
+    let user = process.env.WORKFLOW_VERIFY_OWNER ?? '';
+    if (!user) {
+        try {
+            user = userInfo().username;
+        }
+        catch {
+            user = 'local';
+        }
+    }
+    user = user.replace(/[^A-Za-z0-9._-]/g, '_') || 'local';
+    return { ownerId: `local:${user}`, tenantId: null, visibility: 'owner_private' };
+}
+/**
+ * Scope stamped into reviewed authoring definitions when the file declares none. It is a
+ * constant so a definition's content digest is identical on every machine; a scope is never
+ * an access grant, and the controller derives real authority separately at admission.
+ */
+export const AUTHORING_SCOPE = { ownerId: 'authoring', tenantId: null, visibility: 'owner_private' };
+export class CorpusStore {
+    manifest;
+    byKey = new Map();
+    byIdRevision = new Map();
+    constructor(manifest, documents) {
+        this.manifest = manifest;
+        for (const doc of documents)
+            this.add(doc);
+    }
+    add(doc) {
+        const key = refKey(doc.ref);
+        const idRev = `${doc.ref.id}@${doc.ref.revision}`;
+        const existing = this.byIdRevision.get(idRev);
+        if (existing && !sameDigest(existing.ref.digest, doc.ref.digest)) {
+            throw new SchemaViolation('corpus', [`conflicting definitions for ${idRev}: ${existing.sourcePath} and ${doc.sourcePath}`]);
+        }
+        this.byKey.set(key, doc);
+        this.byIdRevision.set(idRev, doc);
+    }
+    /** Exact ref lookup; verifies the stored bytes still hash to the requested digest. */
+    get(ref) {
+        const doc = this.byKey.get(refKey(ref));
+        if (!doc)
+            throw new SchemaViolation('corpus', [`unresolved ref ${refKey(ref)}`]);
+        const recomputed = selfDigest(doc.value);
+        if (!sameDigest(recomputed, ref.digest))
+            throw new SchemaViolation('corpus', [`digest mismatch for ${refKey(ref)}`]);
+        return doc;
+    }
+    getAs(schema, ref) {
+        const doc = this.get(ref);
+        return parseAs(schema, doc.value, `${doc.schemaVersion} ${ref.id}`);
+    }
+    has(ref) {
+        return this.byKey.has(refKey(ref));
+    }
+    documents() {
+        return [...this.byKey.values()];
+    }
+    findById(id) {
+        return this.documents().filter((doc) => doc.ref.id === id);
+    }
+}
+function readStructured(path) {
+    const text = readFileSync(path, 'utf8');
+    if (path.endsWith('.json'))
+        return JSON.parse(text);
+    return parseYaml(text, { strict: true });
+}
+function safeJoin(root, base, rel) {
+    if (!rel.startsWith('./') && !rel.startsWith('../'))
+        throw new SchemaViolation('corpus', [`file reference must be relative (./ or ../): ${rel}`]);
+    const abs = resolve(base, rel);
+    const relToRoot = relative(root, abs);
+    if (relToRoot.startsWith('..') || isAbsolute(relToRoot)) {
+        throw new SchemaViolation('corpus', [`file reference escapes project root: ${rel}`]);
+    }
+    return abs;
+}
+export class ProjectLoader {
+    root;
+    loaded = new Map();
+    loading = new Set();
+    scope;
+    constructor(root, scope) {
+        this.root = root;
+        this.scope = scope ?? AUTHORING_SCOPE;
+    }
+    /** Load a referenced document, freezing nested `$file` references first. */
+    loadDocument(absPath) {
+        const key = resolve(absPath);
+        const cached = this.loaded.get(key);
+        if (cached)
+            return cached;
+        if (this.loading.has(key))
+            throw new SchemaViolation('corpus', [`reference cycle through ${relative(this.root, key)}`]);
+        if (!existsSync(key) || !statSync(key).isFile())
+            throw new SchemaViolation('corpus', [`missing file ${relative(this.root, key)}`]);
+        this.loading.add(key);
+        try {
+            const raw = readStructured(key);
+            const resolved = this.resolveFileRefs(raw, dirname(key));
+            if (resolved && typeof resolved === 'object' && !Array.isArray(resolved)) {
+                const obj = resolved;
+                if (!('scope' in obj))
+                    obj.scope = this.scope;
+                if (obj.ref && typeof obj.ref === 'object' && !('digest' in obj.ref)) {
+                    // placeholder digest for validation; replaced by freeze below
+                    obj.ref.digest = { algorithm: 'sha256', hex: '0'.repeat(64) };
+                }
+            }
+            const { schemaVersion, value } = validateDocument(resolved);
+            const frozen = freeze(value);
+            // Re-validate the frozen value (same schema) to keep the typed value authoritative.
+            const final = parseAs(SCHEMA_REGISTRY[schemaVersion], frozen, schemaVersion);
+            const doc = {
+                ref: parseAs(RefSchema, final.ref, 'ref'),
+                schemaVersion,
+                value: final,
+                sourcePath: relative(this.root, key).split(sep).join('/'),
+                sourceDigest: sha256Hex(readFileSync(key)),
+            };
+            this.loaded.set(key, doc);
+            return doc;
+        }
+        finally {
+            this.loading.delete(key);
+        }
+    }
+    resolveFileRefs(value, base) {
+        if (Array.isArray(value))
+            return value.map((item) => this.resolveFileRefs(item, base));
+        if (value && typeof value === 'object') {
+            const obj = value;
+            const keys = Object.keys(obj);
+            if (keys.length === 1 && keys[0] === '$file' && typeof obj.$file === 'string') {
+                const doc = this.loadDocument(safeJoin(this.root, base, obj.$file));
+                return { ...doc.ref };
+            }
+            const out = {};
+            for (const [k, v] of Object.entries(obj))
+                out[k] = this.resolveFileRefs(v, base);
+            return out;
+        }
+        return value;
+    }
+    refFor(absPath) {
+        return this.loadDocument(absPath).ref;
+    }
+    documents() {
+        return [...this.loaded.values()];
+    }
+}
+export function loadProject(configPath, scope) {
+    const abs = resolve(configPath);
+    const root = dirname(abs);
+    const rawConfig = readStructured(abs);
+    const config = parseAs(WorkflowConfig, rawConfig, 'workflow.config/v1');
+    const loader = new ProjectLoader(root, scope);
+    const suitePath = safeJoin(root, root, config.suiteRef);
+    const suite = parseAs(Suite, readStructured(suitePath), 'workflow.suite/v1');
+    const suiteCases = suite.cases.map((entry) => ({ ref: loader.refFor(safeJoin(root, dirname(suitePath), entry.caseRef)), required: entry.required }));
+    // Load every file the config names so the frozen manifest covers the executable closure.
+    const fileRefs = new Map();
+    const pathsToLoad = [config.executionHostRef, config.intelligencePolicyRef];
+    if (config.sourceSetRef)
+        pathsToLoad.push(config.sourceSetRef);
+    if (config.sourceSelectionRef)
+        pathsToLoad.push(config.sourceSelectionRef);
+    for (const profile of Object.values(config.profiles)) {
+        pathsToLoad.push(profile.environmentPlanRef, profile.personaRef, profile.fidelityProfileRef, profile.runnerRef);
+        if (profile.hostPlanRef)
+            pathsToLoad.push(profile.hostPlanRef);
+        if (profile.fixturePlanRef)
+            pathsToLoad.push(profile.fixturePlanRef);
+    }
+    for (const rel of pathsToLoad)
+        fileRefs.set(rel, loader.refFor(safeJoin(root, root, rel)));
+    for (const entry of suite.cases)
+        fileRefs.set(join(dirname(config.suiteRef), entry.caseRef).replace(/^(?!\.)/, './'), loader.refFor(safeJoin(root, dirname(suitePath), entry.caseRef)));
+    const documents = loader.documents();
+    const manifestBase = {
+        schemaVersion: 'workflow.corpus/v1',
+        ref: { id: `${config.project}.corpus`, revision: '1', digest: { algorithm: 'sha256', hex: '0'.repeat(64) } },
+        scope: scope ?? AUTHORING_SCOPE,
+        projectId: config.project,
+        members: documents
+            .map((doc) => ({ ref: doc.ref, schemaVersion: doc.schemaVersion, sourcePath: doc.sourcePath, sourceDigest: doc.sourceDigest }))
+            .sort((a, b) => (a.sourcePath < b.sourcePath ? -1 : 1)),
+    };
+    const manifest = parseAs(CorpusManifest, freeze(manifestBase), 'workflow.corpus/v1');
+    return {
+        root,
+        configPath: abs,
+        config,
+        configDigest: sha256Hex(readFileSync(abs)),
+        suite,
+        suiteCases,
+        corpus: new CorpusStore(manifest, documents),
+        fileRefs,
+    };
+}
+//# sourceMappingURL=corpus.js.map

package/dist/core/corpus.js.map

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

package/dist/core/deadline.d.ts

@@ -0,0 +1,12 @@
+/** Every operation receives a deadline bounded by the remaining budget; AbortSignal propagates. */
+export declare class Deadline {
+    readonly at: number;
+    constructor(at: number);
+    static in(ms: number, parent?: Deadline): Deadline;
+    remainingMs(): number;
+    expired(): boolean;
+    /** Child deadline never exceeds the parent. */
+    child(ms: number): Deadline;
+    signal(parent?: AbortSignal): AbortSignal;
+}
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/core/deadline.js

@@ -0,0 +1,38 @@
+/** Every operation receives a deadline bounded by the remaining budget; AbortSignal propagates. */
+export class Deadline {
+    at;
+    constructor(at) {
+        this.at = at;
+    }
+    static in(ms, parent) {
+        const at = Date.now() + ms;
+        return new Deadline(parent ? Math.min(parent.at, at) : at);
+    }
+    remainingMs() {
+        return Math.max(0, this.at - Date.now());
+    }
+    expired() {
+        return this.remainingMs() === 0;
+    }
+    /** Child deadline never exceeds the parent. */
+    child(ms) {
+        return Deadline.in(ms, this);
+    }
+    signal(parent) {
+        const remaining = this.remainingMs();
+        const timeout = remaining === 0
+            ? AbortSignal.abort(new DOMException('deadline exceeded', 'TimeoutError'))
+            : AbortSignal.timeout(remaining);
+        return parent ? AbortSignal.any([parent, timeout]) : timeout;
+    }
+}
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason ?? new Error('aborted'));
+        const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(); }, ms);
+        const onAbort = () => { clearTimeout(timer); reject(signal?.reason ?? new Error('aborted')); };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=deadline.js.map

package/dist/core/deadline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deadline.js","sourceRoot":"","sources":["../../src/core/deadline.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,MAAM,OAAO,QAAQ;IACV,EAAE,CAAS;IACpB,YAAY,EAAU;QACpB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IACD,MAAM,CAAC,EAAE,CAAC,EAAU,EAAE,MAAiB;QACrC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;QAC3B,OAAO,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,WAAW;QACT,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO;QACL,OAAO,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IACD,+CAA+C;IAC/C,KAAK,CAAC,EAAU;QACd,OAAO,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC;IACD,MAAM,CAAC,MAAoB;QACzB,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,SAAS,KAAK,CAAC;YAC7B,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,mBAAmB,EAAE,cAAc,CAAC,CAAC;YAC1E,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACnC,OAAO,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAC/D,CAAC;CACF;AAED,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,MAAoB;IACpD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,MAAM,EAAE,OAAO;YAAE,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;QAC1E,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,GAAG,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAClG,MAAM,OAAO,GAAG,GAAG,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/F,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/core/deliveryJournal.d.ts

@@ -0,0 +1,37 @@
+import { type Ref, type Scope } from '../protocol/index.ts';
+import { LocalLedger } from './ledger.ts';
+type Intent = {
+    ref: Ref;
+    scope: Scope;
+};
+export type DeliveryState<P, A extends object> = {
+    prepared: P;
+    attempts: number;
+    acknowledgement: A | null;
+    version: number;
+};
+export interface DeliveryCodec<P extends Intent, A extends object> {
+    prepared(raw: unknown): P;
+    acknowledgement(raw: unknown): A;
+    checkAcknowledgement(prepared: P, acknowledgement: A): void;
+}
+/** Shared local outbox mechanics. Host-specific authorization remains outside this journal. */
+export declare class LocalDeliveryJournal<P extends Intent, A extends object> {
+    private readonly ledger;
+    private readonly events;
+    private readonly codec;
+    private readonly scope;
+    private readonly inFlight;
+    constructor(ledger: LocalLedger, scope: Scope, events: {
+        prepared: string;
+        attempted: string;
+        acknowledged: string;
+    }, codec: DeliveryCodec<P, A>);
+    read(id: string): DeliveryState<P, A> | null;
+    prepare(raw: P): DeliveryState<P, A>;
+    attempt(id: string): DeliveryState<P, A>;
+    acknowledge(id: string, expectedVersion: number, raw: unknown): DeliveryState<P, A>;
+    private require;
+    whileIdle<T>(id: string, operation: () => Promise<T>): Promise<T>;
+}
+export {};

package/dist/core/deliveryJournal.js

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+import { IsoDateTime, ScopeSchema, sameScope, verifySelfDigest } from "../protocol/index.js";
+import { Conflict } from "./errors.js";
+import { LocalLedger } from "./ledger.js";
+import { nowIso } from "./clock.js";
+const Attempt = z.object({ attempt: z.number().int().positive().max(1000), startedAt: IsoDateTime }).strict();
+const Accepted = z.object({ acknowledgement: z.unknown(), acknowledgedAt: IsoDateTime }).strict();
+/** Shared local outbox mechanics. Host-specific authorization remains outside this journal. */
+export class LocalDeliveryJournal {
+    ledger;
+    events;
+    codec;
+    scope;
+    inFlight = new Set();
+    constructor(ledger, scope, events, codec) {
+        this.ledger = ledger;
+        this.events = events;
+        this.codec = codec;
+        this.scope = ScopeSchema.parse(scope);
+    }
+    read(id) {
+        const entries = this.ledger.history(id);
+        if (!entries.length)
+            return null;
+        if (entries.length > 1002)
+            throw new Conflict('Delivery history exceeds its bounded retry limit');
+        const prepared = this.codec.prepared(entries[0].data);
+        if (entries[0].type !== this.events.prepared || prepared.ref.id !== id || !sameScope(prepared.scope, this.scope) || !verifySelfDigest(prepared))
+            throw new Conflict('Delivery intent is inconsistent or foreign');
+        let attempts = 0;
+        let acknowledgement = null;
+        for (const entry of entries.slice(1)) {
+            if (acknowledgement !== null)
+                throw new Conflict('Delivery history changed after acknowledgement');
+            if (entry.type === this.events.attempted) {
+                if (Attempt.parse(entry.data).attempt !== ++attempts)
+                    throw new Conflict('Delivery attempt sequence is inconsistent');
+            }
+            else if (entry.type === this.events.acknowledged && attempts > 0) {
+                acknowledgement = this.codec.acknowledgement(Accepted.parse(entry.data).acknowledgement);
+                this.codec.checkAcknowledgement(prepared, acknowledgement);
+            }
+            else
+                throw new Conflict('Unexpected delivery journal entry');
+        }
+        return { prepared, attempts, acknowledgement, version: entries.length };
+    }
+    prepare(raw) {
+        const prepared = this.codec.prepared(raw);
+        if (!sameScope(prepared.scope, this.scope) || !verifySelfDigest(prepared))
+            throw new Conflict('Invalid delivery intent');
+        this.ledger.append(prepared.ref.id, 0, this.events.prepared, prepared);
+        return this.read(prepared.ref.id);
+    }
+    attempt(id) {
+        const state = this.require(id);
+        if (state.acknowledgement !== null || state.attempts >= 1000)
+            throw new Conflict('Delivery is acknowledged or its retry limit was reached');
+        this.ledger.append(id, state.version, this.events.attempted, Attempt.parse({ attempt: state.attempts + 1, startedAt: nowIso() }));
+        return this.require(id);
+    }
+    acknowledge(id, expectedVersion, raw) {
+        const state = this.require(id);
+        const acknowledgement = this.codec.acknowledgement(raw);
+        if (!state.attempts || state.acknowledgement !== null)
+            throw new Conflict('Delivery has no outstanding attempt');
+        this.codec.checkAcknowledgement(state.prepared, acknowledgement);
+        this.ledger.append(id, expectedVersion, this.events.acknowledged, { acknowledgement, acknowledgedAt: nowIso() });
+        return this.require(id);
+    }
+    require(id) { const state = this.read(id); if (!state)
+        throw new Conflict('No prepared delivery for this result'); return state; }
+    async whileIdle(id, operation) {
+        if (this.inFlight.has(id))
+            throw new Conflict('Delivery is already in flight');
+        this.inFlight.add(id);
+        try {
+            return await operation();
+        }
+        finally {
+            this.inFlight.delete(id);
+        }
+    }
+}
+//# sourceMappingURL=deliveryJournal.js.map

package/dist/core/deliveryJournal.js.map

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

package/dist/core/environmentPreflight.d.ts

@@ -0,0 +1,14 @@
+/** Read-only, experimental preflight. A ready report is never an execution/authorization token. */
+import { PortableEnvironmentIntent, PortableEnvironmentProfile, PortablePreflightReport, type PortableProbeRequest, type Ref } from '../protocol/index.ts';
+export type PortableEnvironmentPorts = {
+    /** Trusted registry lookup; no network/auth setup or project-code evaluation. */
+    resolveProfile(ref: Ref, signal: AbortSignal): Promise<unknown>;
+    /** Inspect existing host capabilities/access metadata only. Never launch, seed, reset, install, fetch a secret value or change grants. */
+    probe(request: PortableProbeRequest, context: PortableEnvironmentIntent, signal: AbortSignal): Promise<unknown>;
+};
+export declare function portableProbeRequests(profile: PortableEnvironmentProfile, intent: PortableEnvironmentIntent): PortableProbeRequest[];
+/** Host ports must check actual enforceability, not merely whether a configuration declares a policy. */
+export declare function preflightPortableEnvironment(intentValue: unknown, ports: PortableEnvironmentPorts, options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<PortablePreflightReport>;