@parcha/agentrun-pi 0.1.0-beta.1 → 0.1.0-beta.3

package/dist/types.d.ts

@@ -48,6 +48,9 @@ export interface PiToolDefinition<TArgs = unknown, TDetails = unknown> {
     label: string;
     description: string;
     parameters: object;
+    /** Optional JSON Schema for a direct workflow call's return value. Host tools
+     * normally return {content, details}; this describes that whole envelope. */
+    resultSchema?: Record<string, unknown>;
     executionMode?: "sequential" | "parallel";
     execute(toolCallId: string, params: TArgs, signal: AbortSignal | undefined, onUpdate: ((result: PiToolResult<TDetails>) => void) | undefined, context: unknown): Promise<PiToolResult<TDetails>>;
 }

package/dist/workflow-inspector.d.ts

@@ -0,0 +1,47 @@
+import type { ExtensionContext, Theme } from '@earendil-works/pi-coding-agent';
+import { type Component } from '@earendil-works/pi-tui';
+/** Structural view contract: the inspector never executes or changes a workflow. */
+export interface InspectorView {
+    title: string;
+    digest: string;
+    status: string;
+    summary: string[];
+    nodes: {
+        path: string;
+        label: string;
+        kind: string;
+        status: string;
+        summary: string;
+        details: string[];
+    }[];
+    output?: string[];
+    readOnly?: boolean;
+}
+export type InspectorAction = 'run' | 'save' | 'load' | 'input' | 'history' | 'stop' | 'edit';
+/** Exported for deterministic rendering/navigation tests, without a terminal or model. */
+export declare class WorkflowInspector implements Component {
+    private readonly getView;
+    private readonly theme;
+    private readonly done;
+    private readonly redraw;
+    private readonly rows;
+    private page;
+    private selected;
+    private selectedPath?;
+    private actionIndex;
+    private scroll;
+    private viewport;
+    private detailLength;
+    private timer?;
+    constructor(getView: () => InspectorView, theme: Pick<Theme, 'fg' | 'bold'>, done: (action: InspectorAction | undefined) => void, redraw?: () => void, rows?: () => number);
+    startRefresh(): void;
+    dispose(): void;
+    invalidate(): void;
+    private view;
+    private actions;
+    private fingerprint;
+    handleInput(data: string): void;
+    private wrapped;
+    render(width: number): string[];
+}
+export declare function showWorkflowInspector(ctx: ExtensionContext, getView: () => InspectorView): Promise<InspectorAction | undefined>;

package/dist/workflow-inspector.js

@@ -0,0 +1,235 @@
+import { matchesKey, truncateToWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
+import { cleanText } from './presentation.js';
+const MAX_CHARS = 24_000, MAX_LINES = 600;
+const safeLine = (value) => cleanText(value).replace(/[\n\t]/g, ' ');
+/** Exported for deterministic rendering/navigation tests, without a terminal or model. */
+export class WorkflowInspector {
+    getView;
+    theme;
+    done;
+    redraw;
+    rows;
+    page = 'overview';
+    selected = 0;
+    selectedPath;
+    actionIndex = 0;
+    scroll = 0;
+    viewport = 12;
+    detailLength = 0;
+    timer;
+    constructor(getView, theme, done, redraw = () => { }, rows = () => 24) {
+        this.getView = getView;
+        this.theme = theme;
+        this.done = done;
+        this.redraw = redraw;
+        this.rows = rows;
+    }
+    startRefresh() {
+        if (this.timer)
+            return;
+        let previous = this.fingerprint();
+        this.timer = setInterval(() => {
+            const next = this.fingerprint();
+            if (next !== previous) {
+                previous = next;
+                this.redraw();
+            }
+        }, 250);
+    }
+    dispose() { if (this.timer)
+        clearInterval(this.timer); this.timer = undefined; }
+    invalidate() { }
+    view() {
+        const view = this.getView();
+        const index = this.selectedPath ? view.nodes.findIndex(node => node.path === this.selectedPath) : -1;
+        this.selected = Math.max(0, Math.min(index >= 0 ? index : this.selected, view.nodes.length - 1));
+        this.selectedPath = view.nodes[this.selected]?.path;
+        return view;
+    }
+    actions(view) {
+        if (view.readOnly)
+            return [];
+        return view.status === 'running' ? ['stop', 'history'] : ['run', 'input', 'edit', 'save', 'load', 'history'];
+    }
+    fingerprint() {
+        const view = this.view();
+        // Track the visible projection, not raw receipts or the whole workflow state.
+        const visible = this.page === 'detail' ? view.nodes[this.selected]?.details ?? []
+            : this.page === 'output' ? view.output ?? [] : view.summary;
+        let budget = MAX_CHARS;
+        const text = [];
+        for (const line of visible) {
+            if (budget <= 0 || text.length >= MAX_LINES)
+                break;
+            text.push(line.slice(0, budget));
+            budget -= line.length;
+        }
+        return JSON.stringify([view.title, view.digest, view.status, view.readOnly, view.output !== undefined,
+            view.nodes.map(node => [node.path, node.label, node.kind, node.status, node.summary]), text]);
+    }
+    handleInput(data) {
+        const view = this.view();
+        if (matchesKey(data, 'escape')) {
+            if (this.page === 'overview') {
+                this.dispose();
+                this.done(undefined);
+                return;
+            }
+            this.page = this.page === 'detail' ? 'stages' : 'overview';
+            this.scroll = 0;
+        }
+        else if (matchesKey(data, 'ctrl+c')) {
+            // Close the view, never silently cancel a workflow.
+            this.dispose();
+            this.done(undefined);
+            return;
+        }
+        else if (data === 'a' && !view.readOnly && this.page !== 'actions') {
+            this.page = 'actions';
+            this.actionIndex = 0;
+            this.scroll = 0;
+        }
+        else if (data === 'g') {
+            this.page = 'stages';
+            this.scroll = 0;
+        }
+        else if (data === 'v') {
+            this.page = 'overview';
+            this.scroll = 0;
+        }
+        else if (data === 'o' && view.output) {
+            this.page = 'output';
+            this.scroll = 0;
+        }
+        else if (matchesKey(data, 'enter')) {
+            if (this.page === 'actions') {
+                const action = this.actions(view)[this.actionIndex];
+                if (action) {
+                    this.dispose();
+                    this.done(action);
+                    return;
+                }
+            }
+            else if (this.page === 'overview') {
+                this.page = 'stages';
+                this.scroll = 0;
+            }
+            else if (this.page === 'stages' && view.nodes.length) {
+                this.page = 'detail';
+                this.scroll = 0;
+            }
+        }
+        else {
+            const direction = matchesKey(data, 'up') ? -1 : matchesKey(data, 'down') ? 1 : 0;
+            const pageDirection = matchesKey(data, 'pageUp') ? -1 : matchesKey(data, 'pageDown') ? 1 : 0;
+            const amount = direction || pageDirection * this.viewport;
+            if (this.page === 'stages') {
+                this.selected = Math.max(0, Math.min(view.nodes.length - 1, this.selected + amount));
+                this.selectedPath = view.nodes[this.selected]?.path;
+            }
+            else if (this.page === 'actions') {
+                this.actionIndex = Math.max(0, Math.min(this.actions(view).length - 1, this.actionIndex + amount));
+            }
+            else
+                this.scroll = Math.max(0, Math.min(Math.max(0, this.detailLength - this.viewport), this.scroll + amount));
+        }
+        this.redraw();
+    }
+    wrapped(values, width) {
+        const lines = [];
+        let remaining = MAX_CHARS, clipped = false;
+        for (const value of values) {
+            if (!remaining || lines.length >= MAX_LINES) {
+                clipped = true;
+                break;
+            }
+            // Slice before sanitizing/wrapping so a huge individual field stays bounded.
+            const portion = value.slice(0, remaining);
+            remaining -= portion.length;
+            if (portion.length < value.length)
+                clipped = true;
+            const clean = cleanText(portion).replace(/\t/g, '  ');
+            const paragraphs = clean.split('\n');
+            for (const [index, line] of paragraphs.entries()) {
+                const wrapped = wrapTextWithAnsi(line, width);
+                const available = MAX_LINES - lines.length;
+                if (wrapped.length > available)
+                    clipped = true;
+                lines.push(...wrapped.slice(0, available));
+                if (lines.length >= MAX_LINES) {
+                    if (index < paragraphs.length - 1)
+                        clipped = true;
+                    break;
+                }
+            }
+        }
+        return { lines, clipped };
+    }
+    render(width) {
+        const view = this.view();
+        const columns = Math.max(1, width);
+        // Cover the viewport except Pi's two status rows, including on tall terminals.
+        const height = Math.max(8, this.rows() - 2);
+        this.viewport = height - 6;
+        const cut = (value) => truncateToWidth(safeLine(value.slice(0, MAX_CHARS)), columns);
+        const title = this.theme.bold(cut(view.title));
+        const subtitle = cut(`${view.status} · ${view.digest.slice(0, 12)}`);
+        let body = [], position = '', clipped = false;
+        if (this.page === 'stages') {
+            const first = Math.max(0, Math.min(this.selected - Math.floor(this.viewport / 2), view.nodes.length - this.viewport));
+            body = view.nodes.slice(first, first + this.viewport).map((node, index) => {
+                const selected = first + index === this.selected;
+                const depth = Math.min(5, (node.path.match(/\/(?:steps|body|branches|workflow)(?:\/|$)/g) ?? []).length);
+                const text = cut(`${selected ? '›' : ' '} ${'  '.repeat(depth)}${node.label} · ${node.kind} · ${node.status}`);
+                return selected ? this.theme.fg('accent', text) : text;
+            });
+            if (!body.length)
+                body = [cut('No stages yet. Use Actions to load a workflow.')];
+            position = view.nodes.length ? `Stage ${this.selected + 1}/${view.nodes.length}` : 'No stages';
+        }
+        else if (this.page === 'actions') {
+            const actions = this.actions(view);
+            this.actionIndex = Math.min(this.actionIndex, actions.length - 1);
+            const labels = { run: 'Run this workflow', save: 'Save procedure', load: 'Load procedure', input: 'Change input', history: 'Inspect run history', stop: 'Stop running workflow', edit: 'Edit procedure' };
+            const first = Math.max(0, this.actionIndex - this.viewport + 1);
+            body = actions.slice(first, first + this.viewport).map((action, index) => cut(`${first + index === this.actionIndex ? '›' : ' '} ${labels[action]}`));
+            position = 'Choose an action; execution stays with Pi.';
+        }
+        else {
+            const node = view.nodes[this.selected];
+            const details = function* () {
+                if (!node) {
+                    yield 'This stage is no longer available.';
+                    return;
+                }
+                yield node.label;
+                yield `${node.kind} · ${node.status}`;
+                yield node.path;
+                yield node.summary;
+                yield* node.details;
+            };
+            const values = this.page === 'overview' ? view.summary : this.page === 'output' ? view.output ?? ['No output recorded.'] : details();
+            const wrapped = this.wrapped(values, columns);
+            this.detailLength = wrapped.lines.length;
+            clipped = wrapped.clipped;
+            this.scroll = Math.max(0, Math.min(this.scroll, this.detailLength - this.viewport));
+            body = wrapped.lines.slice(this.scroll, this.scroll + this.viewport);
+            position = `${this.page === 'overview' ? 'Overview' : this.page === 'output' ? 'Output' : 'Stage details'} · lines ${this.detailLength ? this.scroll + 1 : 0}–${Math.min(this.scroll + this.viewport, this.detailLength)}/${this.detailLength}`;
+        }
+        while (body.length < this.viewport)
+            body.push('');
+        const guidance = this.page === 'stages' ? '↑↓ stages · Enter inspect · v overview' : this.page === 'actions' ? '↑↓ actions · Enter choose · Esc back' : '↑↓ scroll · g stages · v overview';
+        const footer = clipped ? 'Display clipped; see full run record.' : `${view.readOnly ? 'Read-only · ' : 'a actions · '}${view.output ? 'o output · ' : ''}${this.page === 'overview' ? 'Esc close' : 'Esc back'}`;
+        return [title, subtitle, cut(position), ...body.slice(0, this.viewport),
+            this.theme.fg('muted', cut(guidance)), this.theme.fg(clipped ? 'warning' : 'muted', cut(footer)), ''];
+    }
+}
+export async function showWorkflowInspector(ctx, getView) {
+    if (ctx.mode !== 'tui')
+        return undefined;
+    return ctx.ui.custom((tui, theme, _keys, done) => {
+        const component = new WorkflowInspector(getView, theme, done, () => tui.requestRender(), () => tui.terminal.rows);
+        component.startRefresh();
+        return component;
+    }, { overlay: true, overlayOptions: { width: '100%', maxHeight: '100%', margin: 0, anchor: 'top-left' } });
+}

package/dist/workflow-session.d.ts

@@ -0,0 +1,19 @@
+import { type Workflow } from '@parcha/agentrun-dsl';
+import type { ExtensionRunReport } from './extension-service.js';
+import type { RunObservation } from './workflow-view.js';
+export interface WorkflowSessionSnapshot {
+    version: 1;
+    workflow: Workflow;
+    input: Record<string, unknown>;
+    savedName?: string;
+    demo?: 'scripted' | 'empty' | 'triage' | 'triage-failure';
+    report?: ExtensionRunReport;
+    observation?: RunObservation;
+    running?: boolean;
+    runId?: string;
+    createdAt: string;
+}
+/** Caller supplies Pi's active branch, not the complete session tree. */
+export declare function restoreWorkflowSession(branch: readonly unknown[]): WorkflowSessionSnapshot | undefined;
+/** Newest first, one terminal record per run; unmatched starts are interruptions. */
+export declare function workflowRunHistory(branch: readonly unknown[]): WorkflowSessionSnapshot[];

package/dist/workflow-session.js

@@ -0,0 +1,167 @@
+import { types } from 'node:util';
+import { inspectWorkflow, validateWorkflow } from '@parcha/agentrun-dsl';
+import { demoWorkflow } from './demo.js';
+import { supportTriageWorkflow } from './triage-demo.js';
+const MAX_BYTES = 8 * 1024 * 1024;
+const object = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const only = (v, keys) => Object.keys(v).every(key => keys.includes(key));
+const count = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+const textFields = (v, required, optional = []) => required.every(key => typeof v[key] === 'string') && optional.every(key => v[key] === undefined || typeof v[key] === 'string');
+/** Copy data without invoking accessors, proxy traps, toJSON or authored code. */
+function jsonSnapshot(value) {
+    const ancestors = new Set();
+    let values = 0, bytes = 0;
+    const visit = (item, depth) => {
+        if (++values > 200_000 || depth > 128 || bytes > MAX_BYTES)
+            throw new Error('snapshot bounds');
+        if (item === null || typeof item === 'boolean')
+            return item;
+        if (typeof item === 'number' && Number.isFinite(item))
+            return item;
+        if (typeof item === 'string') {
+            bytes += Buffer.byteLength(item);
+            if (bytes > MAX_BYTES)
+                throw new Error('snapshot bounds');
+            return item;
+        }
+        if (typeof item !== 'object' || types.isProxy(item) || ancestors.has(item))
+            throw new Error('snapshot data');
+        const prototype = Object.getPrototypeOf(item);
+        if (prototype !== (Array.isArray(item) ? Array.prototype : Object.prototype) && prototype !== null)
+            throw new Error('snapshot prototype');
+        const descriptors = Object.getOwnPropertyDescriptors(item);
+        if (Object.getOwnPropertySymbols(item).length || Object.values(descriptors).some(d => !('value' in d)))
+            throw new Error('snapshot descriptors');
+        ancestors.add(item);
+        try {
+            if (Array.isArray(item)) {
+                if (Object.keys(descriptors).some(key => key !== 'length' && !/^(0|[1-9]\d*)$/.test(key)) || item.length > 200_000)
+                    throw new Error('snapshot array');
+                return Array.from({ length: item.length }, (_, index) => visit(descriptors[index]?.value, depth + 1));
+            }
+            return Object.fromEntries(Object.entries(descriptors).map(([key, descriptor]) => {
+                if (!descriptor.enumerable)
+                    throw new Error('snapshot hidden data');
+                bytes += Buffer.byteLength(key);
+                return [key, visit(descriptor.value, depth + 1)];
+            }));
+        }
+        finally {
+            ancestors.delete(item);
+        }
+    };
+    const result = visit(value, 0);
+    if (Buffer.byteLength(JSON.stringify(result)) > MAX_BYTES)
+        throw new Error('snapshot bounds');
+    return result;
+}
+function validReport(r, digest) {
+    if (!object(r) || !only(r, ['digest', 'status', 'calls', 'events', 'output', 'escalation', 'error', 'uncertainEffects', 'traceTruncated', 'trace'])
+        || r.digest !== digest || !['complete', 'escalated', 'failed', 'interrupted'].includes(r.status)
+        || !object(r.calls) || !only(r.calls, ['agent', 'judge', 'tool']) || !['agent', 'judge', 'tool'].every(k => count(r.calls[k]))
+        || !Array.isArray(r.events) || !r.events.every((e) => object(e) && textFields(e, ['type', 'label'], ['executionPath']))
+        || r.traceTruncated !== undefined && typeof r.traceTruncated !== 'boolean')
+        return false;
+    if (r.error !== undefined && (!object(r.error) || !only(r.error, ['code', 'message', 'stage', 'path', 'reason', 'status', 'problems', 'stateBytes', 'maxStateBytes'])
+        || !textFields(r.error, ['code', 'message'], ['stage', 'path', 'reason'])
+        || ['status', 'stateBytes', 'maxStateBytes'].some(k => r.error[k] !== undefined && !count(r.error[k]))
+        || r.error.problems !== undefined && (!Array.isArray(r.error.problems) || !r.error.problems.every((p) => typeof p === 'string'))))
+        return false;
+    if (r.escalation !== undefined && (!object(r.escalation) || !only(r.escalation, ['kind', 'stage', 'summary', 'label', 'executionPath'])
+        || !textFields(r.escalation, ['kind', 'stage', 'summary'], ['label', 'executionPath'])))
+        return false;
+    if (r.uncertainEffects !== undefined && (!Array.isArray(r.uncertainEffects) || !r.uncertainEffects.every((e) => object(e)
+        && only(e, ['idempotencyKey', 'executionPath', 'outcome']) && textFields(e, ['idempotencyKey'], ['executionPath']) && e.outcome === 'unknown')))
+        return false;
+    if (r.trace !== undefined) {
+        const fields = ['receivedEvents', 'receivedBytes', 'rejectedEvents', 'retainedEvents', 'retainedBytes', 'droppedEvents', 'droppedBytes'];
+        if (!object(r.trace) || !only(r.trace, ['policy', ...fields]) || r.trace.policy !== 'tail' || !fields.every(k => count(r.trace[k])))
+            return false;
+    }
+    return true;
+}
+function validObservation(o) {
+    return object(o) && only(o, ['steps', 'decisions', 'notes', 'routes', 'omitted']) && count(o.omitted)
+        && object(o.steps) && Object.values(o.steps).every(s => object(s) && only(s, ['label', 'kind', 'status']) && textFields(s, ['label', 'kind', 'status']))
+        && object(o.notes) && Object.values(o.notes).every(n => typeof n === 'string')
+        && (o.routes === undefined || object(o.routes) && Object.values(o.routes).every(n => typeof n === 'string'))
+        && Array.isArray(o.decisions) && o.decisions.every((d) => object(d) && only(d, ['path', 'label', 'questions', 'evidence', 'answer', 'accepted'])
+        && textFields(d, ['path', 'label', 'questions', 'evidence'], ['answer']) && (d.accepted === undefined || typeof d.accepted === 'boolean'));
+}
+function snapshotEntry(entry) {
+    try {
+        if (!object(entry) || types.isProxy(entry) || ![Object.prototype, null].includes(Object.getPrototypeOf(entry)))
+            return;
+        const descriptors = Object.getOwnPropertyDescriptors(entry);
+        if (descriptors.type?.value !== 'custom' || descriptors.customType?.value !== 'agentrun:snapshot' || !('value' in (descriptors.data ?? {})))
+            return;
+        const s = jsonSnapshot(descriptors.data.value);
+        if (!object(s) || !only(s, ['version', 'workflow', 'input', 'savedName', 'demo', 'report', 'observation', 'running', 'runId', 'createdAt'])
+            || s.version !== 1 || !object(s.input) || typeof s.createdAt !== 'string' || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(s.createdAt)
+            || !Number.isFinite(Date.parse(s.createdAt)) || new Date(s.createdAt).toISOString() !== s.createdAt
+            || s.savedName !== undefined && (typeof s.savedName !== 'string' || !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(s.savedName))
+            || s.runId !== undefined && (typeof s.runId !== 'string' || !s.runId.length || s.runId.length > 200)
+            || s.running !== undefined && typeof s.running !== 'boolean')
+            return;
+        const inspection = inspectWorkflow(s.workflow);
+        // Input remains an exact draft, including incomplete form values; run preflight owns it.
+        if (!validateWorkflow(s.workflow, { executeCode: false }).ok)
+            return;
+        if (s.report !== undefined && !validReport(s.report, inspection.sha256))
+            return;
+        if (s.observation !== undefined && !validObservation(s.observation))
+            return;
+        if (s.demo !== undefined) {
+            const bundled = s.demo === 'scripted' || s.demo === 'empty' ? demoWorkflow
+                : s.demo === 'triage' || s.demo === 'triage-failure' ? supportTriageWorkflow : undefined;
+            if (!bundled || inspectWorkflow(bundled).sha256 !== inspection.sha256)
+                delete s.demo;
+        }
+        return s;
+    }
+    catch {
+        return undefined;
+    }
+}
+function interrupted(s) {
+    if (!s.running)
+        return s;
+    s.running = false;
+    s.report = { digest: inspectWorkflow(s.workflow).sha256, status: 'interrupted',
+        calls: s.report?.calls ?? { agent: 0, judge: 0, tool: 0 }, events: s.report?.events ?? [],
+        ...(s.report?.uncertainEffects ? { uncertainEffects: s.report.uncertainEffects } : {}),
+        error: { code: 'session_interrupted', message: 'This run has no retained completion record. It was not restarted. Recorded counts may be incomplete; reconcile any admitted effects before starting a new run.' } };
+    if (s.observation)
+        for (const step of Object.values(s.observation.steps))
+            if (step.status === 'running')
+                step.status = 'interrupted';
+    return s;
+}
+/** Caller supplies Pi's active branch, not the complete session tree. */
+export function restoreWorkflowSession(branch) {
+    if (!Array.isArray(branch) || types.isProxy(branch))
+        return undefined;
+    for (let i = branch.length - 1; i >= 0; i--) {
+        const snapshot = snapshotEntry(Object.getOwnPropertyDescriptor(branch, String(i))?.value);
+        if (snapshot)
+            return interrupted(snapshot);
+    }
+    return undefined;
+}
+/** Newest first, one terminal record per run; unmatched starts are interruptions. */
+export function workflowRunHistory(branch) {
+    const results = [], seen = new Set();
+    if (!Array.isArray(branch) || types.isProxy(branch))
+        return results;
+    for (let i = branch.length - 1; i >= 0 && results.length < 20; i--) {
+        const snapshot = snapshotEntry(Object.getOwnPropertyDescriptor(branch, String(i))?.value);
+        if (!snapshot || !snapshot.report && !snapshot.running)
+            continue;
+        const key = snapshot.runId ?? `entry:${i}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        results.push(interrupted(snapshot));
+    }
+    return results;
+}

package/dist/workflow-store.d.ts

@@ -0,0 +1,30 @@
+import { type Workflow } from '@parcha/agentrun-dsl';
+export interface WorkflowRevision {
+    name: string;
+    digest: string;
+    createdAt: string;
+    workflowName: string;
+}
+export interface StoredWorkflow extends WorkflowRevision {
+    workflow: Workflow;
+}
+export declare class WorkflowStoreError extends Error {
+    readonly code: 'invalid_name' | 'invalid_revision' | 'invalid_workflow' | 'unsafe_path' | 'not_found' | 'invalid_record' | 'ambiguous_revision';
+    constructor(code: 'invalid_name' | 'invalid_revision' | 'invalid_workflow' | 'unsafe_path' | 'not_found' | 'invalid_record' | 'ambiguous_revision', message: string);
+}
+/** Local procedure revisions, not execution state or authority. The host still
+ * preflights loaded workflows against current capabilities and approves each run.
+ * This is not a sandbox against a process concurrently replacing project directories.
+ */
+export declare class WorkflowStore {
+    private readonly projectDirectory;
+    constructor(projectDirectory: string);
+    private directory;
+    private read;
+    private latest;
+    /** All revisions, newest first; the active revision leads within a timestamp tie. */
+    list(): Promise<WorkflowRevision[]>;
+    load(name: string, digest?: string): Promise<StoredWorkflow>;
+    /** Publish a complete immutable revision atomically; identical saves are idempotent. */
+    save(name: string, value: unknown): Promise<StoredWorkflow>;
+}