@unson/brainbase-mcp 0.44.0 → 0.44.2

package/dist/automation-run.js

@@ -0,0 +1,479 @@
+import { createHash } from 'node:crypto';
+import { normalizeRunReceipt } from './run-receipt.js';
+import { resolveRuntimeHostContext } from './runtime-host.js';
+function assertRequest(request) {
+    if (!request || typeof request !== 'object') {
+        throw new Error('automation run request is required');
+    }
+    if (typeof request.workflowId !== 'string' || request.workflowId.trim() === '') {
+        throw new Error('automation run request workflowId must be a non-empty string');
+    }
+    if (typeof request.externalRunId !== 'string' || request.externalRunId.trim() === '') {
+        throw new Error('automation run request externalRunId must be a non-empty string');
+    }
+}
+function assertPorts(ports) {
+    if (!ports.runner || typeof ports.runner !== 'object' || typeof ports.runner.start !== 'function') {
+        throw new Error('automation runner port with start is required');
+    }
+    if (!ports.receipt || typeof ports.receipt !== 'object'
+        || typeof ports.receipt.persist !== 'function'
+        || typeof ports.receipt.query !== 'function') {
+        throw new Error('automation receipt port with persist and query is required');
+    }
+    if (!ports.runStore || typeof ports.runStore !== 'object'
+        || typeof ports.runStore.claim !== 'function'
+        || typeof ports.runStore.markRunnerStarted !== 'function'
+        || typeof ports.runStore.markReceiptPersisted !== 'function'
+        || typeof ports.runStore.complete !== 'function'
+        || typeof ports.runStore.release !== 'function'
+        || typeof ports.runStore.read !== 'function') {
+        throw new Error('automation runStore port with atomic claim, phase checkpoints, complete, release, and read is required');
+    }
+    if (ports.lifecycle !== undefined) {
+        if (!ports.lifecycle || typeof ports.lifecycle !== 'object') {
+            throw new Error('automation lifecycle port must be an object');
+        }
+        for (const [name, value] of [
+            ['lookup', ports.lifecycle.lookup],
+            ['designGate', ports.lifecycle.designGate],
+            ['checkpoint', ports.lifecycle.checkpoint],
+            ['humanGate', ports.lifecycle.humanGate],
+            ['transition', ports.lifecycle.transition]
+        ]) {
+            if (value !== undefined && typeof value !== 'function') {
+                throw new Error(`automation lifecycle port ${name} must be a function`);
+            }
+        }
+    }
+}
+function stableValue(value, seen = new WeakSet()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (Number.isNaN(value))
+            return { __type: 'number', value: 'NaN' };
+        if (value === Infinity)
+            return { __type: 'number', value: 'Infinity' };
+        if (value === -Infinity)
+            return { __type: 'number', value: '-Infinity' };
+        return value;
+    }
+    if (typeof value === 'bigint')
+        return { __type: 'bigint', value: value.toString() };
+    if (typeof value === 'undefined')
+        return { __type: 'undefined' };
+    if (typeof value === 'function' || typeof value === 'symbol') {
+        return { __type: typeof value, value: String(value) };
+    }
+    if (value instanceof Date)
+        return { __type: 'date', value: value.toISOString() };
+    if (typeof value !== 'object')
+        return String(value);
+    if (seen.has(value))
+        throw new Error('automation run request contains a cyclic identity value');
+    seen.add(value);
+    if (Array.isArray(value)) {
+        const result = value.map((entry) => stableValue(entry, seen));
+        seen.delete(value);
+        return result;
+    }
+    const result = {};
+    for (const key of Object.keys(value).sort()) {
+        result[key] = stableValue(value[key], seen);
+    }
+    seen.delete(value);
+    return result;
+}
+function digest(value) {
+    return createHash('sha256').update(JSON.stringify(stableValue(value))).digest('hex');
+}
+function stringFromRecord(value, keys) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    for (const key of keys) {
+        const candidate = record[key];
+        if (typeof candidate === 'string' && candidate.trim() !== '')
+            return candidate.trim();
+    }
+    return undefined;
+}
+function requiredNamespaceValue(name, ...values) {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim() !== '')
+            return value.trim();
+    }
+    throw new Error(`automation run namespace ${name} must be explicit`);
+}
+function runNamespace(request, context) {
+    const identity = context.identity;
+    const graph = context.graph;
+    return {
+        tenantId: requiredNamespaceValue('tenantId', context.tenantId),
+        projectId: requiredNamespaceValue('projectId', request.projectId),
+        organizationId: requiredNamespaceValue('organizationId', request.organizationId, request.orgId, stringFromRecord(identity, ['organizationId', 'organization_id', 'orgId', 'org_id']), stringFromRecord(graph, ['organizationId', 'organization_id', 'orgId', 'org_id'])),
+        actorId: requiredNamespaceValue('actorId', request.actorId, stringFromRecord(identity, ['actorId', 'actor_id', 'userId', 'user_id', 'subject', 'sub']))
+    };
+}
+function buildRunIdentity(operation, request, context, previousRunId) {
+    const namespace = runNamespace(request, context);
+    const base = {
+        operation,
+        namespace,
+        workflowId: request.workflowId,
+        automationId: request.automationId || null,
+        sourceType: request.sourceType || null,
+        externalRunId: request.externalRunId,
+        previousRunId: previousRunId || null,
+        payload: request.payload === undefined ? null : request.payload,
+        metadata: request.metadata === undefined ? null : request.metadata
+    };
+    const fingerprint = digest(base);
+    const key = `automation-run:${digest({
+        operation,
+        namespace,
+        workflowId: request.workflowId,
+        externalRunId: request.externalRunId
+    })}`;
+    return {
+        operation,
+        key,
+        fingerprint,
+        runnerIdempotencyKey: `automation-run:${fingerprint}`,
+        namespace
+    };
+}
+function conflictError(request, phase) {
+    const error = new Error(`automation run '${request.externalRunId}' is already in progress`);
+    Object.assign(error, {
+        code: 'automation_run_in_progress',
+        status: 409,
+        statusCode: 409,
+        externalRunId: request.externalRunId,
+        ...(phase ? { phase } : {})
+    });
+    return error;
+}
+function identityConflictError(request) {
+    const error = new Error(`automation run '${request.externalRunId}' conflicts with an existing identity`);
+    Object.assign(error, {
+        code: 'automation_run_identity_conflict',
+        status: 409,
+        statusCode: 409,
+        externalRunId: request.externalRunId
+    });
+    return error;
+}
+function uncertainError(request, phase) {
+    const error = new Error(`automation run '${request.externalRunId}' has an uncertain durable outcome`);
+    Object.assign(error, {
+        code: 'automation_run_uncertain',
+        status: 409,
+        statusCode: 409,
+        externalRunId: request.externalRunId,
+        ...(phase ? { phase } : {})
+    });
+    return error;
+}
+function invalidClaimError() {
+    return new Error('automation runStore claim returned an invalid state');
+}
+function replayResult(stored, context) {
+    return {
+        runnerResult: stored.runnerResult,
+        normalizedReceipt: stored.normalized || normalizeRunReceipt(stored.payload),
+        persistedReceipt: stored.persistedReceipt,
+        context,
+        replayed: true
+    };
+}
+function workflowLifecycleError(code, request, reason) {
+    const suffix = typeof reason === 'string' && reason.trim() !== '' ? `: ${reason}` : '';
+    const error = new Error(`${code}${suffix}`);
+    Object.assign(error, {
+        code,
+        status: 409,
+        statusCode: 409,
+        externalRunId: request.externalRunId
+    });
+    return error;
+}
+function requireWorkflowGate(decision, code, request) {
+    const allowed = decision === true
+        || (typeof decision === 'object'
+            && decision !== null
+            && decision.allowed === true);
+    if (!allowed) {
+        const reason = typeof decision === 'object' && decision !== null ? decision.reason : undefined;
+        throw workflowLifecycleError(code, request, reason);
+    }
+}
+export class AutomationRunService {
+    ports;
+    constructor(ports) {
+        assertPorts(ports);
+        this.ports = ports;
+    }
+    async start(request) {
+        return this.execute('automation.start', request, (context, idempotencyKey) => this.ports.runner.start({ request, context, idempotencyKey }));
+    }
+    async run(request) {
+        return this.start(request);
+    }
+    async retry(request, previousRunId) {
+        assertRequest(request);
+        if (typeof previousRunId !== 'string' || previousRunId.trim() === '') {
+            throw new Error('previousRunId must be a non-empty string');
+        }
+        if (typeof this.ports.runner.retry !== 'function') {
+            throw new Error('automation runner retry port is required');
+        }
+        return this.execute('automation.retry', request, (context, idempotencyKey) => this.ports.runner.retry({ request, context, previousRunId, idempotencyKey }), previousRunId);
+    }
+    async rerun(request, previousRunId) {
+        return this.retry(request, previousRunId);
+    }
+    async history(request) {
+        assertRequest(request);
+        const input = {
+            operation: 'automation.history',
+            automationId: request.automationId,
+            runId: request.externalRunId,
+            request
+        };
+        const context = await resolveRuntimeHostContext(this.ports, input);
+        return this.ports.receipt.query({ request, context });
+    }
+    async getRun(request) {
+        return this.history(request);
+    }
+    async execute(operation, request, run, previousRunId) {
+        assertRequest(request);
+        const input = {
+            operation,
+            automationId: request.automationId,
+            runId: request.externalRunId,
+            request
+        };
+        const context = await resolveRuntimeHostContext(this.ports, input);
+        const identity = buildRunIdentity(operation, request, context, previousRunId);
+        const claimInput = { ...identity, request, context };
+        const lifecycle = this.ports.lifecycle;
+        let workflow;
+        const preparedLifecycleInput = () => ({
+            request,
+            context,
+            identity,
+            phase: 'prepared',
+            workflow,
+            previousRunId
+        });
+        // Workflow lookup and policy gates are host-owned. They run before the
+        // durable claim so a denied design/HITL decision cannot leave a retryable
+        // record behind, while the core still fixes their order before the runner.
+        if (lifecycle?.lookup) {
+            workflow = await lifecycle.lookup(preparedLifecycleInput());
+            if (workflow === null || workflow === undefined) {
+                throw workflowLifecycleError('automation_workflow_lookup_failed', request);
+            }
+        }
+        if (lifecycle?.designGate) {
+            requireWorkflowGate(await lifecycle.designGate(preparedLifecycleInput()), 'automation_workflow_design_gate_denied', request);
+        }
+        if (lifecycle?.humanGate) {
+            requireWorkflowGate(await lifecycle.humanGate(preparedLifecycleInput()), 'automation_workflow_human_gate_denied', request);
+        }
+        // A rejected claim is not safe to release: the backing store may have
+        // committed it while the response was lost. Fail closed and let a durable
+        // reconciliation worker inspect the record.
+        const claim = await this.ports.runStore.claim(claimInput);
+        if (!claim || typeof claim !== 'object' || typeof claim.status !== 'string') {
+            throw invalidClaimError();
+        }
+        if (claim.status === 'conflict') {
+            if (claim.reason === 'identity_mismatch')
+                throw identityConflictError(request);
+            throw uncertainError(request, claim.phase);
+        }
+        if (claim.status === 'replay') {
+            const stored = await this.ports.runStore.read(claimInput);
+            if (stored.status === 'completed') {
+                if (lifecycle?.transition) {
+                    try {
+                        await lifecycle.transition({
+                            ...preparedLifecycleInput(),
+                            phase: 'completed',
+                            from: 'receipt_persisted',
+                            to: 'completed'
+                        });
+                    }
+                    catch {
+                        // The runStore has already committed the external side effect;
+                        // retrying the runner is forbidden while the host transition is
+                        // reconciled separately.
+                        throw uncertainError(request, 'completed');
+                    }
+                }
+                return replayResult(stored, context);
+            }
+            if (stored.status === 'uncertain')
+                throw uncertainError(request, stored.phase);
+            throw new Error(`automation runStore replay readback was not completed for ${request.externalRunId}`);
+        }
+        if (claim.status === 'in_progress') {
+            const stored = await this.ports.runStore.read(claimInput);
+            if (stored.status === 'completed') {
+                if (lifecycle?.transition) {
+                    try {
+                        await lifecycle.transition({
+                            ...preparedLifecycleInput(),
+                            phase: 'completed',
+                            from: 'receipt_persisted',
+                            to: 'completed'
+                        });
+                    }
+                    catch {
+                        throw uncertainError(request, 'completed');
+                    }
+                }
+                return replayResult(stored, context);
+            }
+            if (stored.status === 'uncertain')
+                throw uncertainError(request, stored.phase);
+            throw conflictError(request, stored.phase || claim.phase);
+        }
+        if (claim.status !== 'claimed' || typeof claim.claimToken !== 'string' || claim.claimToken.trim() === '') {
+            throw invalidClaimError();
+        }
+        let phase = 'claimed';
+        try {
+            if (lifecycle?.checkpoint) {
+                phase = 'unknown';
+                await lifecycle.checkpoint({
+                    ...preparedLifecycleInput(),
+                    phase: 'claimed',
+                    claimToken: claim.claimToken
+                });
+                phase = 'claimed';
+            }
+            // The marker is durable and precedes the external call. If it fails, the
+            // state is unknown and must never be made retryable automatically.
+            phase = 'unknown';
+            await this.ports.runStore.markRunnerStarted({ ...claimInput, claimToken: claim.claimToken });
+            phase = 'runner_started';
+            if (lifecycle?.transition) {
+                phase = 'unknown';
+                await lifecycle.transition({
+                    ...preparedLifecycleInput(),
+                    phase: 'runner_started',
+                    claimToken: claim.claimToken,
+                    from: 'claimed',
+                    to: 'runner_started'
+                });
+                phase = 'runner_started';
+            }
+            const runnerResult = await run(context, identity.runnerIdempotencyKey);
+            if (!runnerResult || typeof runnerResult !== 'object' || !('receipt' in runnerResult)) {
+                throw new Error(`automation runner ${operation} must return a receipt`);
+            }
+            const result = runnerResult;
+            const normalizedReceipt = normalizeRunReceipt(result.receipt);
+            const persistedReceipt = await this.ports.receipt.persist({
+                payload: result.receipt,
+                normalized: normalizedReceipt,
+                context
+            });
+            phase = 'unknown';
+            await this.ports.runStore.markReceiptPersisted({
+                ...claimInput,
+                claimToken: claim.claimToken,
+                payload: result.receipt,
+                normalized: normalizedReceipt,
+                runnerResult: result.result,
+                persistedReceipt
+            });
+            phase = 'receipt_persisted';
+            if (lifecycle?.transition) {
+                phase = 'unknown';
+                await lifecycle.transition({
+                    ...preparedLifecycleInput(),
+                    phase: 'receipt_persisted',
+                    claimToken: claim.claimToken,
+                    from: 'runner_started',
+                    to: 'receipt_persisted'
+                });
+                phase = 'receipt_persisted';
+            }
+            phase = 'unknown';
+            await this.ports.runStore.complete({
+                ...claimInput,
+                claimToken: claim.claimToken,
+                payload: result.receipt,
+                normalized: normalizedReceipt,
+                runnerResult: result.result,
+                persistedReceipt
+            });
+            phase = 'completed';
+            // Readback is part of the contract. A lost response after complete must
+            // not cause a caller to invoke the runner again.
+            phase = 'unknown';
+            const stored = await this.ports.runStore.read(claimInput);
+            if (!stored || stored.status !== 'completed') {
+                throw uncertainError(request, stored?.phase || 'unknown');
+            }
+            if (lifecycle?.transition) {
+                phase = 'unknown';
+                await lifecycle.transition({
+                    ...preparedLifecycleInput(),
+                    phase: 'completed',
+                    claimToken: claim.claimToken,
+                    from: 'receipt_persisted',
+                    to: 'completed'
+                });
+                phase = 'completed';
+            }
+            phase = 'completed';
+            return {
+                runnerResult: stored.runnerResult,
+                normalizedReceipt: stored.normalized || normalizeRunReceipt(stored.payload),
+                persistedReceipt: stored.persistedReceipt,
+                context
+            };
+        }
+        catch (error) {
+            const outcome = phase === 'claimed' ? 'retryable' : 'uncertain';
+            const releasePhase = outcome === 'retryable' ? 'retryable' : phase;
+            await Promise.resolve(this.ports.runStore.release({
+                ...claimInput,
+                claimToken: claim.claimToken,
+                outcome,
+                phase: releasePhase,
+                error
+            })).catch(() => undefined);
+            throw error;
+        }
+    }
+}
+/** Thin compatibility facade for hosts that previously composed a control runtime. */
+export class AutomationControlRuntime {
+    service;
+    constructor(service) {
+        this.service = service;
+    }
+    start(request) {
+        return this.service.start(request);
+    }
+    retry(request, previousRunId) {
+        return this.service.retry(request, previousRunId);
+    }
+    history(request) {
+        return this.service.history(request);
+    }
+    getRun(request) {
+        return this.service.getRun(request);
+    }
+}
+export function createAutomationRunService(ports) {
+    return new AutomationRunService(ports);
+}

package/dist/canonical-task-operations.d.ts

@@ -0,0 +1,205 @@
+import type { CanonicalTaskPgClient, CanonicalTaskPgPool } from './canonical-task-postgres.js';
+type JsonRecord = Record<string, unknown>;
+export type CanonicalTaskOperationError = Error & {
+    code: string;
+    status: number;
+    details: JsonRecord;
+};
+export declare function canonicalTaskOperationError(code: string, message: string, status?: number, details?: JsonRecord): CanonicalTaskOperationError;
+export interface CanonicalTaskOperationRepositoryOptions {
+    pool?: CanonicalTaskPgPool | null;
+    writerToken?: string | null;
+    processIdentity?: JsonRecord | null;
+    writerEnabled?: boolean;
+    operationWaitTimeoutMs?: number;
+    operationPollIntervalMs?: number;
+}
+export interface CanonicalTaskReadinessRow {
+    ready: boolean;
+    writer_token: string | null;
+    manifest_hash: string | null;
+    schema_version: string | null;
+    source_head: string | null;
+    evidence_hash: string | null;
+    evidence_path: string | null;
+    reason: string | null;
+    updated_at: unknown;
+}
+/**
+ * Single-writer coordination for Canonical Task mutations
+ * (`contracts/canonical-task/operation-schema.sql`). One process owns the
+ * writer token; every mutation is recorded by scope and operation key so a
+ * retry with the same input replays and a different input conflicts.
+ */
+export declare class CanonicalTaskOperationRepository {
+    /**
+     * A PostgreSQL coordinator is a durable mutation boundary. Callers must
+     * bind it to the release readiness gate before exposing mutations.
+     */
+    readonly requiresReadiness = true;
+    readonly pool: CanonicalTaskPgPool | null;
+    readonly writerToken: string | null;
+    readonly processIdentity: JsonRecord | null;
+    readonly writerEnabled: boolean;
+    readonly operationWaitTimeoutMs: number;
+    readonly operationPollIntervalMs: number;
+    writerClaimed: boolean;
+    activeOperations: number;
+    constructor({ pool, writerToken, processIdentity, writerEnabled, operationWaitTimeoutMs, operationPollIntervalMs, }?: CanonicalTaskOperationRepositoryOptions);
+    private identityJson;
+    private connect;
+    waitForCompletedOperation({ scope, operationKey, fingerprint }: {
+        scope: string;
+        operationKey: string;
+        fingerprint: string;
+    }): Promise<unknown>;
+    assertConfigured(): void;
+    assertWriterEnabled(): void;
+    claimWriter({ sourceHead }?: {
+        sourceHead?: string | null;
+    }): Promise<JsonRecord>;
+    assertWriter(client?: CanonicalTaskPgClient | null): Promise<void>;
+    readReadiness(): Promise<CanonicalTaskReadinessRow | null>;
+    reconcileReadiness({ manifestHash, schemaVersion, sourceHead, allowWriterRebind }?: {
+        manifestHash?: string | null;
+        schemaVersion?: string | null;
+        sourceHead?: string | null;
+        allowWriterRebind?: boolean;
+    }): Promise<CanonicalTaskReadinessRow | null>;
+    rebindReadinessSourceHead({ manifestHash, schemaVersion, fromHead, toHead }?: {
+        manifestHash?: string | null;
+        schemaVersion?: string | null;
+        fromHead?: string | null;
+        toHead?: string | null;
+    }): Promise<CanonicalTaskReadinessRow>;
+    releaseWriter(): Promise<boolean>;
+    execute<T>(args: CanonicalTaskCoordinatedRequest<T>): Promise<T>;
+    executeCoordinated<T>({ scope, operationKey, fingerprint, recover, projectResult, run }: CanonicalTaskCoordinatedRequest<T>): Promise<T>;
+    executePreparedDelete<T>(args: CanonicalTaskPreparedDeleteCoordination<T>): Promise<T>;
+    executePreparedDeleteCoordinated<T>({ operationKey, versionClaimKey, fingerprint, versionFingerprint, principalNamespace, prepare, findTask, removeTask, authorizeReplay, }: CanonicalTaskPreparedDeleteCoordination<T>): Promise<T>;
+    completePreparedDelete<T>({ operationKey, versionClaimKey, row, findTask, removeTask, authorizeReplay }: {
+        operationKey: string;
+        versionClaimKey: string;
+        row: {
+            fingerprint: string;
+            result_json: unknown;
+            authorization_snapshot?: unknown;
+        };
+        findTask: () => Promise<unknown>;
+        removeTask: (task: any) => Promise<void>;
+        authorizeReplay?: (authorizationSnapshot: JsonRecord, result: T) => Promise<void>;
+    }): Promise<T>;
+}
+export interface CanonicalTaskCoordinatedRequest<T> {
+    scope: string;
+    operationKey: string;
+    fingerprint: string;
+    recover?: (() => Promise<{
+        recovered: boolean;
+        result?: T;
+    }>) | null;
+    projectResult?: (value: T) => unknown;
+    run: () => Promise<T>;
+}
+export interface CanonicalTaskPreparedDeleteCoordination<T> {
+    operationKey: string;
+    versionClaimKey: string;
+    fingerprint: string;
+    versionFingerprint: string;
+    principalNamespace: string;
+    prepare: () => Promise<{
+        result: T;
+        authorizationSnapshot?: JsonRecord;
+        task?: unknown;
+    }>;
+    findTask: () => Promise<unknown>;
+    removeTask: (task: any) => Promise<void>;
+    /** Reauthorize a completed or already-applied delete from its durable snapshot. */
+    authorizeReplay?: (authorizationSnapshot: JsonRecord, result: T) => Promise<void>;
+}
+export declare class CanonicalTaskReadinessError extends Error {
+    readonly code: string;
+    readonly status = 503;
+    details?: JsonRecord;
+    constructor(code?: string, message?: string);
+}
+export type CanonicalTaskSourceHeadRebindGuard = (input: {
+    fromHead?: string | null;
+    toHead?: string | null;
+}) => Promise<{
+    allowed: boolean;
+    reason?: string;
+    changedPaths?: string[];
+    changedPackages?: string[];
+    error?: string;
+}>;
+interface CanonicalTaskReadinessLogger {
+    warn?(message: string): void;
+}
+/**
+ * Opens Canonical Task mutation only while the persisted readiness row was
+ * blessed for this release: the same writer, manifest, schema and source head.
+ */
+export declare class CanonicalTaskReadiness {
+    readonly operationRepository: CanonicalTaskOperationRepository | null;
+    readonly expected: {
+        manifestHash: string | null;
+        schemaVersion: string | null;
+        sourceHead: string | null;
+    };
+    readonly sourceHeadRebindGuard: CanonicalTaskSourceHeadRebindGuard | null;
+    readonly logger: CanonicalTaskReadinessLogger | null;
+    ready: boolean;
+    reason: string | null;
+    evidence: JsonRecord | null;
+    constructor({ operationRepository, manifestHash, schemaVersion, sourceHead, sourceHeadRebindGuard, logger, }?: {
+        operationRepository?: CanonicalTaskOperationRepository | null;
+        manifestHash?: string | null;
+        schemaVersion?: string | null;
+        sourceHead?: string | null;
+        sourceHeadRebindGuard?: CanonicalTaskSourceHeadRebindGuard | null;
+        logger?: CanonicalTaskReadinessLogger | null;
+    });
+    open(evidence?: JsonRecord | null): void;
+    close(reason?: string): void;
+    matches(row: CanonicalTaskReadinessRow | null): boolean;
+    refresh({ allowWriterRebind }?: {
+        allowWriterRebind?: boolean | undefined;
+    }): Promise<{
+        ready: boolean;
+        reason?: string | null;
+        evidence?: JsonRecord | null;
+    }>;
+    attemptSourceHeadRebind(): Promise<boolean>;
+    initialize(): Promise<{
+        ready: boolean;
+        reason?: string | null;
+        evidence?: JsonRecord | null;
+        error?: unknown;
+    }>;
+    assertMutationReady(): Promise<void>;
+}
+type ExecFile = (file: string, args: string[]) => Promise<{
+    stdout: string | Buffer;
+}>;
+export interface CanonicalTaskSourceHeadGuardOptions {
+    repoDir?: string | null;
+    /** Repository paths whose change can alter Canonical Task mutation semantics. Tenant configuration. */
+    guardedPaths: string[];
+    /**
+     * Installed packages whose locked version can alter Canonical Task mutation
+     * semantics (for example this package). A change of the locked entry blocks
+     * the rebind even when no guarded path changed.
+     */
+    guardedPackages?: string[];
+    lockfilePath?: string;
+    execFile?: ExecFile;
+}
+/**
+ * Decides whether readiness blessed for one source head may follow a deploy
+ * to another head. It allows the rebind only when git proves that no guarded
+ * path and no guarded package changed between them; anything unknown stays
+ * fail-closed.
+ */
+export declare function createCanonicalTaskSourceHeadGuard({ repoDir, guardedPaths, guardedPackages, lockfilePath, execFile, }: CanonicalTaskSourceHeadGuardOptions): CanonicalTaskSourceHeadRebindGuard;
+export {};