specrails-core 5.2.3 → 5.4.0

package/dist/installer/runtime/pipeline-state.d.ts

@@ -0,0 +1,351 @@
+export type PipelinePhase = 'architect' | 'developer' | 'reviewer' | 'archive' | 'ship' | 'ci';
+export type PhaseStatus = 'pending' | 'running' | 'done' | 'blocked' | 'failed' | 'skipped';
+export interface PipelineSpec {
+    id: string | number;
+    title: string;
+    description: string;
+    repositoryIds?: string[];
+    acceptanceCriteria?: string[];
+}
+export interface PipelineRepository {
+    id: string;
+    name: string;
+    path: string;
+    baseSha?: string;
+}
+export interface PipelineContext {
+    schemaVersion: 1;
+    runId: string;
+    backlogRoot: string;
+    backlogPath?: string;
+    artifactRoot: string;
+    artifactRepositoryId: string;
+    repositories: PipelineRepository[];
+    ownership: {
+        git: 'host' | 'core';
+        backlog: 'host' | 'core';
+        worktrees: 'host' | 'core';
+    };
+    specs: PipelineSpec[];
+}
+export interface HostCheckPolicy {
+    reuse?: 'never' | 'snapshot-local';
+    inputs?: string[];
+    deterministic?: boolean;
+    readOnly?: boolean;
+    toolchainInputs?: string[];
+    independentGroup?: string;
+    resources?: string[];
+}
+export interface VerificationCommand {
+    key?: string;
+    label?: string;
+    policy?: HostCheckPolicy;
+    repositoryId: string;
+    command: string;
+    args: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+}
+/** `unverified` admits a full request whose commands do not cover every repository
+ *  (or cover none): the receipt then records which repositories ran no check. */
+export interface VerificationRequest {
+    kind: 'full' | 'scoped';
+    commands: VerificationCommand[];
+    unverified?: boolean;
+    planHash?: string;
+}
+export interface CommandReceipt {
+    repositoryId: string;
+    command: string;
+    args: string[];
+    cwd: string;
+    environmentPolicy?: 'isolated-transport-v1';
+    environmentHash: string;
+    environmentKeys: string[];
+    environmentOverrideKeys: string[];
+    environmentOverridesHash: string;
+    exitCode: number;
+    durationMs: number;
+    output: string;
+    checkDefinitionHash?: string;
+    checkDefinition?: VerificationCommand;
+    disposition?: 'executed' | 'reused' | 'not-run';
+    reusedFrom?: string;
+    reuseReason?: string;
+    snapshot?: VerificationSnapshot;
+    pending?: boolean;
+    evidenceId?: string;
+    stdout?: string;
+    stderr?: string;
+    outputTruncated?: boolean;
+    key?: string;
+    label?: string;
+    configuredTimeoutMs?: number;
+    appliedTimeoutMs?: number;
+    deadline?: number;
+    outcome?: 'passed' | 'failed' | 'cancelled' | 'timed-out' | 'interrupted';
+}
+export interface VerificationReceipt {
+    id: string;
+    kind: 'full' | 'scoped';
+    scopeHash: string;
+    candidateHash: string;
+    planHash?: string;
+    commands: CommandReceipt[];
+    notRunEvidenceIds?: string[];
+    completedAt: string;
+    valid: boolean;
+    reason?: string;
+    /** Repositories in scope that this receipt ran no command for (explicitly admitted by the request). */
+    unverifiedRepositories?: string[];
+}
+export interface AcceptanceCriterion {
+    specId: string;
+    criterionIndex: number;
+    requirement: string;
+    status: 'met' | 'exception' | 'blocked' | 'pending';
+    evidence: string[];
+    exception?: {
+        reason: string;
+        impact: string;
+        material: boolean;
+        acceptedBy: 'reviewer' | 'user' | 'host';
+        approvalEvidence: string;
+    };
+}
+export interface AcceptanceCheck {
+    name: string;
+    status: 'passed' | 'failed' | 'unavailable';
+    required: boolean;
+    evidence: string[];
+    /** What was measured and what remains outside the measurement. */
+    scope: string;
+    limitations: string;
+}
+export interface AcceptanceReport {
+    criteria: AcceptanceCriterion[];
+    checks: AcceptanceCheck[];
+    findings: string[];
+}
+export interface AcceptanceReceipt extends AcceptanceReport {
+    scopeHash: string;
+    candidateHash: string;
+    artifactHash: string;
+    recordedAt: string;
+    planHash?: string;
+}
+export interface PipelineCompletion {
+    implementation: 'complete' | 'incomplete';
+    validation: 'verified' | 'with-exceptions' | 'pending' | 'blocked';
+    archive: PhaseStatus;
+    delivery: 'pending-host' | 'complete' | 'pending';
+    reasons: string[];
+}
+interface PhaseRecord {
+    startedAt?: string;
+    durationMs?: number;
+    attempts?: number;
+    status: PhaseStatus;
+    reason?: string;
+    candidateHash?: string;
+    artifactHash?: string;
+    completedAt?: string;
+}
+export interface PipelineState {
+    schemaVersion: 1;
+    runId: string;
+    change: string;
+    context: PipelineContext;
+    scopeHash: string;
+    revision: number;
+    createdAt: string;
+    updatedAt: string;
+    phases: Record<PipelinePhase, PhaseRecord>;
+    verificationPlan?: {
+        hash: string;
+        files: Array<{
+            path: string;
+            hash: string;
+        }>;
+    };
+    verification?: VerificationReceipt;
+    acceptance?: AcceptanceReceipt;
+    archivePath?: string;
+    archiveApproval?: {
+        candidateHash: string;
+        artifactHash: string;
+        confidenceHash: string;
+        acceptanceHash: string;
+    };
+    artifactExclusions: string[];
+    preview?: {
+        baseHash: string;
+        files: PreviewFile[];
+        createdAt: string;
+    };
+}
+export interface PreviewFile {
+    repositoryId: string;
+    path: string;
+    operation: 'write' | 'delete';
+    sourcePath?: string;
+    contentHash?: string;
+}
+export declare function verificationEnvironment(env: NodeJS.ProcessEnv, overrides?: Record<string, string>, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
+export declare function validatePipelineContext(input: unknown): PipelineContext;
+export declare function pipelineStateDirectory(context: PipelineContext): string;
+export interface CandidateManifest {
+    schemaVersion: 1;
+    scopeHash: string;
+    repositories: Array<{
+        id: string;
+        path: string;
+        files: Array<[string, string]>;
+    }>;
+}
+export declare function candidateManifest(state: PipelineState): CandidateManifest;
+export declare function fingerprintCandidate(state: PipelineState): string;
+export declare function initializePipeline(contextInput: unknown, change: string): PipelineState;
+/** Host-owned binding, including immutable harness bytes outside the candidate. */
+export declare function bindVerificationPlan(contextInput: PipelineContext, hash: string, files: Array<{
+    path: string;
+    hash: string;
+}>): void;
+declare function inspectReceipt(state: PipelineState, env?: NodeJS.ProcessEnv): {
+    valid: boolean;
+    reasons: string[];
+    receipt?: VerificationReceipt;
+};
+/** The frozen requirements an acceptance report must certify, in scope order. */
+export declare function frozenAcceptanceCriteria(contextInput: unknown): Array<Pick<AcceptanceCriterion, 'specId' | 'criterionIndex' | 'requirement'>>;
+/** Validates a report against the frozen scope without recording it; throws the same errors `recordAcceptance` would. */
+export declare function validateAcceptanceReport(contextInput: unknown, input: unknown): AcceptanceReport;
+declare function inspectAcceptance(state: PipelineState): {
+    valid: boolean;
+    status: PipelineCompletion['validation'];
+    reasons: string[];
+    receipt?: AcceptanceReceipt;
+};
+export declare function recordAcceptance(contextInput: unknown, input: unknown): PipelineState;
+export declare function checkArchive(contextInput: unknown): PipelineState;
+export declare function transitionPipeline(contextInput: unknown, phase: PipelinePhase, status: PhaseStatus, reason?: string): PipelineState;
+export declare function inspectPipeline(contextInput: unknown): {
+    schemaVersion: 1;
+    runId: string;
+    change: string;
+    context: PipelineContext;
+    stateDir: string;
+    resumePhase: PipelinePhase | null;
+    phases: PipelineState['phases'];
+    verification: ReturnType<typeof inspectReceipt>;
+    acceptance: ReturnType<typeof inspectAcceptance>;
+    completion: PipelineCompletion;
+    planHash?: string;
+    candidateHash: string;
+};
+/**
+ * Native executables retain structured argv; Windows script shims need cmd.
+ * This runtime is copied as one standalone module into .specrails/runtime,
+ * without installer util/exec. Keep this builtins-only equivalent local rather
+ * than importing a helper absent from installed projects. Like runCommand, it
+ * handles Windows shims; unlike a shell string it refuses ambiguous arguments.
+ */
+export declare function verificationInvocation(command: string, args: string[], cwd: string, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): {
+    command: string;
+    args: string[];
+    windowsVerbatimArguments?: boolean;
+};
+/** Shared persisted-output/provider diagnostic redaction; preserves line structure. */
+export declare function redactRuntimeText(text: string, env?: NodeJS.ProcessEnv): string;
+export interface VerificationSnapshot {
+    eligible: boolean;
+    reason: string;
+    inputHash?: string;
+    toolchainHash?: string;
+}
+/** Host opt-in is a declaration of determinism, not inferred hermeticity. */
+export declare function verificationSnapshot(context: PipelineContext, command: VerificationCommand): VerificationSnapshot;
+/** Contiguous waves preserve baseline order; an uncertain check is a barrier. */
+export declare function verificationWaves<T extends VerificationCommand>(commands: T[], maxConcurrency?: number): T[][];
+export declare function verifyPipeline(contextInput: unknown, raw: unknown, log?: (text: string) => void, signal?: AbortSignal, options?: {
+    deadline?: number;
+    maxConcurrency?: number;
+    onEvidence?: (kind: 'check-started' | 'check-finished' | 'check-reused' | 'check-invalidated', payload: Record<string, string | number | null>) => Promise<void>;
+}): Promise<VerificationReceipt>;
+/** Validate a check plan without creating state or executing commands. */
+export declare function validateVerificationRequest(contextInput: unknown, raw: unknown): void;
+export declare function preparePreview(contextInput: unknown, raw: unknown): PipelineState;
+export declare function applyPreview(contextInput: unknown, verificationRequest: unknown, log?: (text: string) => void): Promise<VerificationReceipt>;
+export declare function runPipelineCommand(flags: Record<string, string | boolean>, positionals: string[]): Promise<number>;
+export declare function runPipelineCli(argv: string[]): Promise<number>;
+export interface VerificationEvidenceQuery {
+    id?: string;
+    section?: 'summary' | 'stdout' | 'stderr' | 'source';
+    sourceId?: string;
+    cursor?: string;
+    limit?: number;
+}
+/** Historical read: no live repository validation, source execution or lifecycle mutation. */
+export declare function readVerificationEvidence(context: Pick<PipelineContext, 'backlogRoot' | 'runId'>, query?: VerificationEvidenceQuery): {
+    nextCursor?: string | undefined;
+    schemaVersion: number;
+    available: boolean;
+    items: Record<string, unknown>[];
+    truncated: boolean;
+} | {
+    schemaVersion: number;
+    available: boolean;
+    items: {
+        sources: {
+            id: string;
+            displayPath: string;
+            byteCount: number;
+            hash: string;
+        }[];
+        schemaVersion: 1;
+        runId: string;
+        id: string;
+        checkId: string;
+        repositoryId: string;
+        label: string;
+        origin: string[];
+        required: true;
+        disposition: "executed" | "reused" | "not-run";
+        reusedFrom?: string;
+        status: "passed" | "failed" | "cancelled" | "interrupted" | "unavailable";
+        reuseReason?: string;
+        recordedAt: string;
+        execution: {
+            command: string;
+            args: string[];
+            cwd: string;
+            configuredTimeoutMs: number | null;
+            appliedTimeoutMs: number | null;
+            deadline: number | null;
+            outcome: string | null;
+        };
+        planHash: string;
+        candidateHash: string;
+        executionId: string;
+        exitCode: number | null;
+        durationMs: number | null;
+        outputTruncated: boolean;
+        stdoutBytes: number;
+        stderrBytes: number;
+        stdoutHash: string;
+        stderrHash: string;
+    }[];
+    truncated: boolean;
+} | {
+    nextCursor?: string | undefined;
+    schemaVersion: number;
+    available: boolean;
+    text: string;
+    byteCount: number;
+    totalBytes: number;
+    truncated: boolean;
+    items?: undefined;
+};
+export {};