@svadmin/surface 0.8.19 → 0.9.0

package/dist/workflows/openui-guard.js

@@ -0,0 +1,209 @@
+/** Strict, bounded framing for the static OpenUI subset consumed by Surface.
+ * This is NOT a replacement for the upstream parser. It prevents unsupported
+ * expressions from reaching that parser and only releases complete statements.
+ */
+export const OPENUI_LIMITS = Object.freeze({ characters: 131_072, statementCharacters: 32_768, statements: 128, depth: 32, tokens: 12_000 });
+export class SurfaceOpenUIError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SurfaceOpenUIError';
+    }
+}
+const identifier = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+const forbidden = new Set(['__proto__', 'prototype', 'constructor']);
+function checkStatement(text, calls) {
+    const tokens = [];
+    // JSON.parse rejects unescaped control characters in string tokens below.
+    const lexer = /\s+|"(?:[^"\\]|\\(?:["\\/bfnrt]|u[0-9a-fA-F]{4}))*"|-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?|[A-Za-z_][A-Za-z0-9_]*|[=(),[\]{}:]/uy;
+    let offset = 0;
+    while (offset < text.length) {
+        lexer.lastIndex = offset;
+        const token = lexer.exec(text);
+        if (!token)
+            throw new SurfaceOpenUIError('syntax', 'Only static OpenUI declarations and JSON literals are supported');
+        offset = lexer.lastIndex;
+        if (token[0].trim())
+            tokens.push(token[0]);
+        if (tokens.length > OPENUI_LIMITS.tokens)
+            throw new SurfaceOpenUIError('limit', 'Too many tokens in a declaration');
+    }
+    const topCall = tokens[2];
+    if (!topCall || !calls.has(topCall) || tokens[3] !== '(')
+        throw new SurfaceOpenUIError('unsupported', 'Declarations must be registered component calls');
+    if ((tokens[0] === 'root') !== (topCall === 'Surface'))
+        throw new SurfaceOpenUIError('unsupported', 'Only root may declare Surface');
+    const references = new Set();
+    let at = 0;
+    function take(value) {
+        if (tokens[at++] !== value)
+            throw new SurfaceOpenUIError('syntax', `Expected ${value}`);
+    }
+    function value(depth) {
+        if (depth > OPENUI_LIMITS.depth)
+            throw new SurfaceOpenUIError('limit', 'OpenUI nesting limit exceeded');
+        const token = tokens[at++];
+        if (token === undefined)
+            throw new SurfaceOpenUIError('syntax', 'Missing expression');
+        if (token.startsWith('"') || /^(?:-?[0-9]|true$|false$|null$)/u.test(token)) {
+            const literal = JSON.parse(token);
+            if (typeof literal === 'number' && !Number.isFinite(literal))
+                throw new SurfaceOpenUIError('syntax', 'Numbers must be finite');
+            return;
+        }
+        if (token === '[' || token === '{') {
+            const end = token === '[' ? ']' : '}';
+            const keys = new Set();
+            if (tokens[at] !== end) {
+                for (;;) {
+                    if (token === '{') {
+                        const keyToken = tokens[at++];
+                        if (!keyToken?.startsWith('"'))
+                            throw new SurfaceOpenUIError('syntax', 'Object keys must be quoted JSON strings');
+                        const key = JSON.parse(keyToken);
+                        if (forbidden.has(key) || keys.has(key))
+                            throw new SurfaceOpenUIError('syntax', 'Duplicate or unsafe object key');
+                        keys.add(key);
+                        take(':');
+                    }
+                    value(depth + 1);
+                    if (tokens[at] !== ',')
+                        break;
+                    at += 1;
+                }
+            }
+            take(end);
+            return;
+        }
+        if (!identifier.test(token) || forbidden.has(token))
+            throw new SurfaceOpenUIError('syntax', 'Invalid reference');
+        if (tokens[at] === '(') {
+            if (depth !== 0)
+                throw new SurfaceOpenUIError('unsupported', 'Use named declarations, not nested calls');
+            if (!calls.has(token))
+                throw new SurfaceOpenUIError('unsupported', `Unregistered OpenUI call: ${token}`);
+            at += 1;
+            if (tokens[at] !== ')') {
+                for (;;) {
+                    value(depth + 1);
+                    if (tokens[at] !== ',')
+                        break;
+                    at += 1;
+                }
+            }
+            take(')');
+        }
+        else {
+            if (topCall !== 'Surface' || token === 'root' || references.has(token))
+                throw new SurfaceOpenUIError('unsupported', 'References are only allowed once in the Surface root');
+            references.add(token);
+            if (references.size > 32)
+                throw new SurfaceOpenUIError('limit', 'Too many root references');
+        }
+    }
+    const name = tokens[at++];
+    if (!name || !identifier.test(name) || forbidden.has(name) || name.length > 64)
+        throw new SurfaceOpenUIError('syntax', 'Invalid declaration name');
+    take('=');
+    value(0);
+    if (at !== tokens.length)
+        throw new SurfaceOpenUIError('syntax', 'Unexpected tokens after declaration');
+    return name;
+}
+export function createOpenUIStatementGuard(callNames) {
+    const calls = new Set(callNames);
+    const names = new Set();
+    let pending = '';
+    let characters = 0;
+    const stack = [];
+    let inString = false;
+    let escaped = false;
+    let closed = false;
+    let failure;
+    function release() {
+        const statement = pending.trim();
+        pending = '';
+        if (!statement)
+            return undefined;
+        const name = checkStatement(statement, calls);
+        if (names.has(name))
+            throw new SurfaceOpenUIError('syntax', `Duplicate declaration: ${name}`);
+        names.add(name);
+        if (names.size > OPENUI_LIMITS.statements)
+            throw new SurfaceOpenUIError('limit', 'Too many declarations');
+        return statement + '\n';
+    }
+    return {
+        push(chunk) {
+            if (failure)
+                throw failure;
+            if (closed)
+                throw new SurfaceOpenUIError('syntax', 'Stream is closed');
+            try {
+                if (typeof chunk !== 'string')
+                    throw new SurfaceOpenUIError('syntax', 'Chunks must be text');
+                characters += chunk.length;
+                if (characters > OPENUI_LIMITS.characters)
+                    throw new SurfaceOpenUIError('limit', 'OpenUI input is too large');
+                const result = [];
+                for (const char of chunk) {
+                    if (!inString && stack.length === 0 && (char === '\n' || char === ';')) {
+                        const statement = release();
+                        if (statement)
+                            result.push(statement);
+                        continue;
+                    }
+                    pending += char;
+                    if (pending.length > OPENUI_LIMITS.statementCharacters)
+                        throw new SurfaceOpenUIError('limit', 'Declaration is too large');
+                    if (inString) {
+                        if (escaped)
+                            escaped = false;
+                        else if (char === '\\')
+                            escaped = true;
+                        else if (char === '"')
+                            inString = false;
+                    }
+                    else if (char === '"')
+                        inString = true;
+                    else if ('([{'.includes(char)) {
+                        stack.push(char);
+                        if (stack.length > OPENUI_LIMITS.depth)
+                            throw new SurfaceOpenUIError('limit', 'OpenUI nesting limit exceeded');
+                    }
+                    else if (')]}'.includes(char)) {
+                        const expected = { ')': '(', ']': '[', '}': '{' }[char];
+                        if (stack.pop() !== expected)
+                            throw new SurfaceOpenUIError('syntax', 'Unbalanced delimiter');
+                    }
+                }
+                return result;
+            }
+            catch (error) {
+                failure = error instanceof SurfaceOpenUIError ? error : new SurfaceOpenUIError('syntax', 'Invalid OpenUI input');
+                pending = '';
+                throw failure;
+            }
+        },
+        finish() {
+            if (failure)
+                throw failure;
+            if (closed)
+                return [];
+            closed = true;
+            if (inString || stack.length) {
+                failure = new SurfaceOpenUIError('syntax', 'Truncated OpenUI declaration');
+                throw failure;
+            }
+            try {
+                const statement = release();
+                return statement ? [statement] : [];
+            }
+            catch (error) {
+                failure = error instanceof SurfaceOpenUIError ? error : new SurfaceOpenUIError('syntax', 'Invalid OpenUI input');
+                throw failure;
+            }
+        },
+    };
+}

package/dist/workflows/service.d.ts

@@ -0,0 +1,58 @@
+import type { JsonObject, JsonValue } from '../types.js';
+import type { SurfaceWorkflowContext, SurfaceWorkflowOptions, SurfaceActionProposal, SurfaceStoredRevision } from './types.js';
+/** Server-only orchestration; no functions from this file belong in a browser bundle. */
+export declare function createSurfaceWorkflowService(options: SurfaceWorkflowOptions): {
+    saveSurface(identity: SurfaceWorkflowContext, input: {
+        spec: unknown;
+        expectedRevision: number;
+    }): Promise<SurfaceStoredRevision>;
+    readSurface(identity: SurfaceWorkflowContext, surfaceId: string, revision?: number): Promise<SurfaceStoredRevision>;
+    propose(identity: SurfaceWorkflowContext, input: {
+        actionId: string;
+        args: unknown;
+        surfaceId: string;
+        surfaceRevision: number;
+        requestKey: string;
+    }): Promise<SurfaceActionProposal>;
+    inspect(identity: SurfaceWorkflowContext, id: string): Promise<SurfaceActionProposal>;
+    approve(identity: SurfaceWorkflowContext, id: string, expectedDigest: string): Promise<{
+        status: "approved";
+        approvedBy: string;
+        id: string;
+        tenantId: string;
+        requesterId: string;
+        requestKey: string;
+        surfaceId: string;
+        surfaceRevision: number;
+        actionId: string;
+        actionVersion: string;
+        actionLabel: string;
+        args: JsonObject;
+        digest: string;
+        approval: import("./types.js").SurfaceApprovalPolicy;
+        createdAt: number;
+        expiresAt: number;
+        result?: JsonValue;
+    }>;
+    reject(identity: SurfaceWorkflowContext, id: string, expectedDigest: string): Promise<{
+        status: "rejected";
+        id: string;
+        tenantId: string;
+        requesterId: string;
+        requestKey: string;
+        surfaceId: string;
+        surfaceRevision: number;
+        actionId: string;
+        actionVersion: string;
+        actionLabel: string;
+        args: JsonObject;
+        digest: string;
+        approval: import("./types.js").SurfaceApprovalPolicy;
+        createdAt: number;
+        expiresAt: number;
+        approvedBy?: string;
+        result?: JsonValue;
+    }>;
+    execute(identity: SurfaceWorkflowContext, id: string, expectedDigest: string): Promise<SurfaceActionProposal>;
+    audit(identity: SurfaceWorkflowContext, surfaceId: string, after?: number, limit?: number): Promise<readonly import("./types.js").SurfaceWorkflowAuditEvent[]>;
+};

package/dist/workflows/service.js

@@ -0,0 +1,296 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { jsonValueIssue } from '../json.js';
+import { validateSurfaceSpec } from '../validation.js';
+import { SurfaceWorkflowError } from './types.js';
+import { defineSurfaceAction } from './action-contracts.js';
+const clone = (value) => structuredClone(value);
+function frozen(value) {
+    if (value && typeof value === 'object') {
+        for (const child of Object.values(value))
+            frozen(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+function canonical(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    const object = value;
+    return '{' + Object.entries(object).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, child]) => JSON.stringify(key) + ':' + canonical(child)).join(',') + '}';
+}
+function json(input) {
+    if (jsonValueIssue(input) || JSON.stringify(input).length > 131_072)
+        throw new SurfaceWorkflowError('invalid_input', 'Expected bounded, plain JSON');
+}
+function key(value) {
+    if (typeof value !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/u.test(value))
+        throw new SurfaceWorkflowError('invalid_input', 'Invalid identifier');
+}
+function context(input) {
+    key(input.tenantId);
+    key(input.actorId);
+    return Object.freeze({ tenantId: input.tenantId, actorId: input.actorId });
+}
+function digest(value) { return createHash('sha256').update(canonical(value)).digest('hex'); }
+function argumentDigest(p) {
+    return digest({ tenantId: p.tenantId, requesterId: p.requesterId, surfaceId: p.surfaceId,
+        surfaceRevision: p.surfaceRevision, actionId: p.actionId, actionVersion: p.actionVersion, args: p.args, approval: p.approval });
+}
+/** Server-only orchestration; no functions from this file belong in a browser bundle. */
+export function createSurfaceWorkflowService(options) {
+    const { store } = options;
+    const now = options.now ?? Date.now;
+    const lifetime = options.proposalLifetimeMs ?? 900_000;
+    if (!Number.isFinite(lifetime) || lifetime < 1000 || lifetime > 86_400_000)
+        throw new Error('Invalid proposal lifetime');
+    const actions = new Map();
+    for (const action of options.actions) {
+        if (actions.has(action.id))
+            throw new Error(`Duplicate Surface action: ${action.id}`);
+        actions.set(action.id, defineSurfaceAction(action));
+    }
+    function registered(id) {
+        const action = actions.get(id);
+        if (!action)
+            throw new SurfaceWorkflowError('denied');
+        return action;
+    }
+    async function access(ctx, surfaceId, operation) {
+        key(surfaceId);
+        const result = await options.authorizeSurface({ context: ctx, operation, surfaceId });
+        if (!result)
+            throw new SurfaceWorkflowError('denied');
+        return result;
+    }
+    async function authorize(ctx, action, phase, args, requesterId) {
+        if (!await action.authorize({ context: ctx, phase, args: frozen(clone(args)), requesterId }))
+            throw new SurfaceWorkflowError('denied');
+    }
+    function event(tx, ctx, name, p) {
+        tx.audit({ tenantId: ctx.tenantId, surfaceId: p.surfaceId, proposalId: p.id, actorId: ctx.actorId,
+            event: name, at: now(), metadata: { actionId: p.actionId, revision: p.surfaceRevision, digest: p.digest } });
+    }
+    function latest(tx, ctx, surfaceId, revision) {
+        const saved = tx.getRevision(ctx.tenantId, surfaceId);
+        if (!saved || saved.revision !== revision)
+            throw new SurfaceWorkflowError('conflict', 'Surface revision changed');
+        return saved;
+    }
+    function proposal(tx, ctx, id) {
+        key(id);
+        const p = tx.getProposal(ctx.tenantId, id);
+        if (!p)
+            throw new SurfaceWorkflowError('not_found');
+        return p;
+    }
+    function current(tx, ctx, p, action) {
+        if (p.actionVersion !== action.version || p.approval !== action.approval || p.digest !== argumentDigest(p))
+            throw new SurfaceWorkflowError('conflict', 'Action contract changed');
+        if (p.expiresAt <= now())
+            throw new SurfaceWorkflowError('expired');
+        if (!action.validateInput(p.args))
+            throw new SurfaceWorkflowError('invalid_input');
+        const saved = latest(tx, ctx, p.surfaceId, p.surfaceRevision);
+        if (!saved.spec.widgets.some((w) => w.type === 'resource-form' && w.props['actionId'] === action.id))
+            throw new SurfaceWorkflowError('denied');
+    }
+    return {
+        async saveSurface(identity, input) {
+            const ctx = context(identity);
+            input = { spec: input.spec, expectedRevision: input.expectedRevision };
+            json(input.spec);
+            const spec = clone(input.spec);
+            const surfaceId = spec?.['surfaceId'];
+            key(surfaceId);
+            if (!Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 0)
+                throw new SurfaceWorkflowError('invalid_input');
+            const { catalog, policy } = await access(ctx, surfaceId, 'save');
+            const checked = validateSurfaceSpec(spec, catalog, policy);
+            if (!checked.ok)
+                throw new SurfaceWorkflowError('invalid_input', 'Surface failed policy validation');
+            return store.transaction((tx) => {
+                const previous = tx.getRevision(ctx.tenantId, surfaceId);
+                if ((previous?.revision ?? 0) !== input.expectedRevision)
+                    throw new SurfaceWorkflowError('conflict');
+                const revision = { tenantId: ctx.tenantId, surfaceId, revision: input.expectedRevision + 1,
+                    spec: clone(checked.value), actorId: ctx.actorId, createdAt: now() };
+                tx.putRevision(revision);
+                tx.audit({ tenantId: ctx.tenantId, surfaceId, actorId: ctx.actorId, event: 'surface.saved', at: now(), metadata: { revision: revision.revision } });
+                return clone(revision);
+            });
+        },
+        async readSurface(identity, surfaceId, revision) {
+            const ctx = context(identity);
+            const { catalog, policy } = await access(ctx, surfaceId, 'read');
+            if (revision !== undefined && (!Number.isSafeInteger(revision) || revision < 1))
+                throw new SurfaceWorkflowError('invalid_input');
+            const saved = store.getRevision(ctx.tenantId, surfaceId, revision);
+            if (!saved)
+                throw new SurfaceWorkflowError('not_found');
+            if (!validateSurfaceSpec(saved.spec, catalog, policy).ok)
+                throw new SurfaceWorkflowError('denied');
+            return clone(saved);
+        },
+        async propose(identity, input) {
+            const ctx = context(identity);
+            input = { ...input };
+            key(input.requestKey);
+            key(input.actionId);
+            if (!Number.isSafeInteger(input.surfaceRevision) || input.surfaceRevision < 1)
+                throw new SurfaceWorkflowError('invalid_input');
+            json(input.args);
+            const args = clone(input.args);
+            const action = registered(input.actionId);
+            if (!action.validateInput(args))
+                throw new SurfaceWorkflowError('invalid_input');
+            const { catalog, policy } = await access(ctx, input.surfaceId, 'read');
+            await authorize(ctx, action, 'propose', args, ctx.actorId);
+            const candidate = {
+                id: randomUUID(), tenantId: ctx.tenantId, requesterId: ctx.actorId, requestKey: input.requestKey,
+                surfaceId: input.surfaceId, surfaceRevision: input.surfaceRevision,
+                actionId: action.id, actionVersion: action.version, actionLabel: action.label,
+                args: args, approval: action.approval, status: 'pending',
+                createdAt: now(), expiresAt: now() + lifetime, digest: '',
+            };
+            const next = { ...candidate, digest: argumentDigest(candidate) };
+            return store.transaction((tx) => {
+                const saved = latest(tx, ctx, input.surfaceId, input.surfaceRevision);
+                if (!validateSurfaceSpec(saved.spec, catalog, policy).ok)
+                    throw new SurfaceWorkflowError('denied');
+                current(tx, ctx, next, action);
+                const existing = tx.findRequest(ctx.tenantId, ctx.actorId, input.requestKey);
+                if (existing) {
+                    if (existing.digest !== next.digest)
+                        throw new SurfaceWorkflowError('conflict', 'Idempotency key reused with different input');
+                    return clone(existing);
+                }
+                tx.putProposal(next);
+                event(tx, ctx, 'action.proposed', next);
+                return clone(next);
+            });
+        },
+        async inspect(identity, id) {
+            const ctx = context(identity);
+            const p = proposal(store, ctx, id);
+            await access(ctx, p.surfaceId, 'read');
+            await authorize(ctx, registered(p.actionId), 'read', p.args, p.requesterId);
+            return clone(p);
+        },
+        async approve(identity, id, expectedDigest) {
+            const ctx = context(identity);
+            const before = proposal(store, ctx, id);
+            const action = registered(before.actionId);
+            const { catalog, policy } = await access(ctx, before.surfaceId, 'read');
+            await authorize(ctx, action, 'approve', before.args, before.requesterId);
+            if (action.approval === 'confirm' ? ctx.actorId !== before.requesterId : ctx.actorId === before.requesterId)
+                throw new SurfaceWorkflowError('denied');
+            return store.transaction((tx) => {
+                const p = proposal(tx, ctx, id);
+                current(tx, ctx, p, action);
+                if (!validateSurfaceSpec(latest(tx, ctx, p.surfaceId, p.surfaceRevision).spec, catalog, policy).ok)
+                    throw new SurfaceWorkflowError('denied');
+                if (expectedDigest !== p.digest)
+                    throw new SurfaceWorkflowError('conflict');
+                if (p.status !== 'pending')
+                    throw new SurfaceWorkflowError('invalid_state');
+                const next = { ...p, status: 'approved', approvedBy: ctx.actorId };
+                tx.putProposal(next);
+                event(tx, ctx, 'action.approved', next);
+                return clone(next);
+            });
+        },
+        async reject(identity, id, expectedDigest) {
+            const ctx = context(identity);
+            const before = proposal(store, ctx, id);
+            await access(ctx, before.surfaceId, 'read');
+            await authorize(ctx, registered(before.actionId), 'reject', before.args, before.requesterId);
+            return store.transaction((tx) => {
+                const p = proposal(tx, ctx, id);
+                if (p.digest !== expectedDigest)
+                    throw new SurfaceWorkflowError('conflict');
+                if (p.status !== 'pending' && p.status !== 'approved')
+                    throw new SurfaceWorkflowError('invalid_state');
+                const next = { ...p, status: 'rejected' };
+                tx.putProposal(next);
+                event(tx, ctx, 'action.rejected', next);
+                return clone(next);
+            });
+        },
+        async execute(identity, id, expectedDigest) {
+            const ctx = context(identity);
+            const before = proposal(store, ctx, id);
+            const action = registered(before.actionId);
+            if (before.requesterId !== ctx.actorId)
+                throw new SurfaceWorkflowError('denied');
+            if (before.status !== 'approved' && before.status !== 'succeeded')
+                throw new SurfaceWorkflowError('invalid_state');
+            const { catalog, policy } = await access(ctx, before.surfaceId, 'read');
+            await authorize(ctx, action, 'execute', before.args, before.requesterId);
+            if (before.status === 'approved' && before.approvedBy) {
+                await authorize(context({ ...ctx, actorId: before.approvedBy }), action, 'approve', before.args, before.requesterId);
+            }
+            const claimed = store.transaction((tx) => {
+                const p = proposal(tx, ctx, id);
+                if (p.digest !== expectedDigest)
+                    throw new SurfaceWorkflowError('conflict');
+                // Repeated successful requests return the recorded result, never rerun.
+                if (p.status === 'succeeded')
+                    return p;
+                current(tx, ctx, p, action);
+                const saved = latest(tx, ctx, p.surfaceId, p.surfaceRevision);
+                if (!validateSurfaceSpec(saved.spec, catalog, policy).ok)
+                    throw new SurfaceWorkflowError('denied');
+                if (p.status !== 'approved' || !p.approvedBy)
+                    throw new SurfaceWorkflowError('invalid_state');
+                if (p.approval === 'confirm' ? p.approvedBy !== p.requesterId : p.approvedBy === p.requesterId)
+                    throw new SurfaceWorkflowError('denied');
+                const next = { ...p, status: 'executing' };
+                tx.putProposal(next);
+                event(tx, ctx, 'action.executing', next);
+                return next;
+            });
+            if (claimed.status === 'succeeded')
+                return clone(claimed);
+            let result;
+            try {
+                const value = await action.execute({ context: ctx, args: frozen(clone(claimed.args)), idempotencyKey: claimed.id });
+                json(value);
+                result = clone(value);
+            }
+            catch {
+                try {
+                    store.transaction((tx) => {
+                        const p = proposal(tx, ctx, id);
+                        tx.putProposal({ ...p, status: 'indeterminate' });
+                        event(tx, ctx, 'action.indeterminate', p);
+                    });
+                }
+                catch { /* The durable executing claim still prevents a duplicate effect. */ }
+                throw new SurfaceWorkflowError('indeterminate', 'Business effect may have occurred; reconciliation is required before any retry');
+            }
+            try {
+                return store.transaction((tx) => {
+                    const p = proposal(tx, ctx, id);
+                    if (p.status !== 'executing')
+                        throw new SurfaceWorkflowError('invalid_state');
+                    const next = { ...p, status: 'succeeded', result };
+                    tx.putProposal(next);
+                    event(tx, ctx, 'action.succeeded', next);
+                    return clone(next);
+                });
+            }
+            catch {
+                throw new SurfaceWorkflowError('indeterminate', 'Business effect completed but recording failed; do not retry the business effect');
+            }
+        },
+        async audit(identity, surfaceId, after = 0, limit = 50) {
+            const ctx = context(identity);
+            await access(ctx, surfaceId, 'audit');
+            if (!Number.isSafeInteger(after) || after < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+                throw new SurfaceWorkflowError('invalid_input');
+            return clone(store.listAudit(ctx.tenantId, surfaceId, after, limit));
+        },
+    };
+}

package/dist/workflows/sqlite-store.d.ts

@@ -0,0 +1,20 @@
+import type { SurfaceWorkflowStore, SurfaceWorkflowTransaction, SurfaceStoredRevision, SurfaceActionProposal, SurfaceWorkflowAuditEvent } from './types.js';
+/** Node-only durable adapter. Use a local persistent volume, not an ephemeral
+ * serverless filesystem or a network filesystem shared between server replicas.
+ * DB files/backups contain form data and require application retention/access controls.
+ */
+export declare class SqliteSurfaceWorkflowStore implements SurfaceWorkflowStore {
+    private readonly db;
+    private active;
+    constructor(filename: string);
+    transaction<T>(work: (tx: SurfaceWorkflowTransaction) => T): T;
+    private writing;
+    getRevision(tenantId: string, surfaceId: string, revision?: number): SurfaceStoredRevision | undefined;
+    putRevision(revision: SurfaceStoredRevision): void;
+    getProposal(tenantId: string, id: string): SurfaceActionProposal | undefined;
+    findRequest(tenantId: string, requesterId: string, requestKey: string): SurfaceActionProposal | undefined;
+    putProposal(proposal: SurfaceActionProposal): void;
+    audit(event: SurfaceWorkflowAuditEvent): void;
+    listAudit(tenantId: string, surfaceId: string, after: number, limit: number): readonly SurfaceWorkflowAuditEvent[];
+    close(): void;
+}

package/dist/workflows/sqlite-store.js

@@ -0,0 +1,91 @@
+import { DatabaseSync } from 'node:sqlite';
+/** Node-only durable adapter. Use a local persistent volume, not an ephemeral
+ * serverless filesystem or a network filesystem shared between server replicas.
+ * DB files/backups contain form data and require application retention/access controls.
+ */
+export class SqliteSurfaceWorkflowStore {
+    db;
+    active = false;
+    constructor(filename) {
+        this.db = new DatabaseSync(filename);
+        this.db.exec(`
+      PRAGMA busy_timeout = 5000;
+      PRAGMA journal_mode = WAL;
+      PRAGMA synchronous = FULL;
+      CREATE TABLE IF NOT EXISTS svadmin_surface_revisions (
+        tenant TEXT NOT NULL, surface TEXT NOT NULL, revision INTEGER NOT NULL CHECK(revision > 0),
+        document TEXT NOT NULL, PRIMARY KEY(tenant, surface, revision)
+      );
+      CREATE TABLE IF NOT EXISTS svadmin_surface_proposals (
+        tenant TEXT NOT NULL, id TEXT NOT NULL, requester TEXT NOT NULL, request_key TEXT NOT NULL,
+        document TEXT NOT NULL, PRIMARY KEY(tenant, id), UNIQUE(tenant, requester, request_key)
+      );
+      CREATE TABLE IF NOT EXISTS svadmin_surface_audit (
+        sequence INTEGER PRIMARY KEY AUTOINCREMENT, tenant TEXT NOT NULL, surface TEXT NOT NULL,
+        document TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS svadmin_surface_audit_scope ON svadmin_surface_audit(tenant, surface, sequence);
+    `);
+    }
+    transaction(work) {
+        if (this.active)
+            throw new Error('Nested workflow transactions are not supported');
+        this.db.exec('BEGIN IMMEDIATE');
+        this.active = true;
+        try {
+            const result = work(this);
+            if (result && typeof result === 'object' && 'then' in result)
+                throw new Error('Workflow transactions must be synchronous');
+            this.db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+        finally {
+            this.active = false;
+        }
+    }
+    writing() {
+        if (!this.active)
+            throw new Error('Workflow writes must occur in an atomic transaction');
+    }
+    getRevision(tenantId, surfaceId, revision) {
+        const row = revision === undefined
+            ? this.db.prepare('SELECT document FROM svadmin_surface_revisions WHERE tenant = ? AND surface = ? ORDER BY revision DESC LIMIT 1').get(tenantId, surfaceId)
+            : this.db.prepare('SELECT document FROM svadmin_surface_revisions WHERE tenant = ? AND surface = ? AND revision = ?').get(tenantId, surfaceId, revision);
+        return row ? JSON.parse(String(row['document'])) : undefined;
+    }
+    putRevision(revision) {
+        this.writing();
+        this.db.prepare('INSERT INTO svadmin_surface_revisions(tenant, surface, revision, document) VALUES (?, ?, ?, ?)')
+            .run(revision.tenantId, revision.surfaceId, revision.revision, JSON.stringify(revision));
+    }
+    getProposal(tenantId, id) {
+        const row = this.db.prepare('SELECT document FROM svadmin_surface_proposals WHERE tenant = ? AND id = ?').get(tenantId, id);
+        return row ? JSON.parse(String(row['document'])) : undefined;
+    }
+    findRequest(tenantId, requesterId, requestKey) {
+        const row = this.db.prepare('SELECT document FROM svadmin_surface_proposals WHERE tenant = ? AND requester = ? AND request_key = ?')
+            .get(tenantId, requesterId, requestKey);
+        return row ? JSON.parse(String(row['document'])) : undefined;
+    }
+    putProposal(proposal) {
+        this.writing();
+        this.db.prepare(`INSERT INTO svadmin_surface_proposals(tenant, id, requester, request_key, document)
+      VALUES (?, ?, ?, ?, ?) ON CONFLICT(tenant, id) DO UPDATE SET document = excluded.document`)
+            .run(proposal.tenantId, proposal.id, proposal.requesterId, proposal.requestKey, JSON.stringify(proposal));
+    }
+    audit(event) {
+        this.writing();
+        this.db.prepare('INSERT INTO svadmin_surface_audit(tenant, surface, document) VALUES (?, ?, ?)')
+            .run(event.tenantId, event.surfaceId, JSON.stringify(event));
+    }
+    listAudit(tenantId, surfaceId, after, limit) {
+        return this.db.prepare('SELECT sequence, document FROM svadmin_surface_audit WHERE tenant = ? AND surface = ? AND sequence > ? ORDER BY sequence LIMIT ?')
+            .all(tenantId, surfaceId, after, limit)
+            .map((row) => ({ ...JSON.parse(String(row['document'])), sequence: Number(row['sequence']) }));
+    }
+    close() { this.db.close(); }
+}