opencode-plugin-flow 5.0.0 → 5.1.0

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 One short entry per release, written for users deciding whether to upgrade.
 
+## [5.1.0] - 2026-07-18
+
+Causal evidence and review truth lore makes long-running Flow work compact,
+retry-safe, and auditable without putting raw evidence into model-visible state:
+
+- Session v3 gains additive revision and snapshot identity, an authenticated
+  mutation ledger, and guarded idempotent operations. Existing sparse v3
+  sessions hydrate to the canonical revision-zero state without a migration.
+- `flow_status` now separates compact routing, complete execution, bounded
+  detail, reviewer, and revision-delta projections. Mutations return receipts
+  instead of the full session; the checked-in six-feature fixture preserves all
+  transition decisions while reducing measured stateful response bytes by
+  93.95%, with the unavailable historical same-corpus gate reported as such.
+- Validation evidence is bound to a deterministic source digest. Optional raw
+  output lives in an owner-only, hash-addressed `.flow/evidence` store with
+  strict size, permission, symlink, integrity, and no-clobber checks; ordinary
+  state records only typed digest and length references, and concurrent
+  publishers converge on the same ignore policy across platforms.
+- Review executions are durable independently of completion, with stable
+  attempt and logical-pass identity, typed finding fingerprints, append-only
+  failed-to-passed retry history, contradiction checks, and explicit final-
+  feature chronology. Malformed optional orchestration telemetry can no longer
+  erase valid core review evidence.
+- A provider-neutral sanitized replay oracle derives terminal and retry truth
+  from event causality, rejects private or unsafe fixture content, and keeps
+  host facts, Flow-ledger claims, supplied observations, and replay-derived
+  facts distinct. New `replay:report` and `transport:report` commands expose the
+  reproducible local reports.
+- Manager and reviewer guidance now routes from compact status to exact
+  execution context, records every observed review attempt, performs final
+  feature validation and reviews in economy order, and closes only from a
+  refreshed compact projection.
+
 ## [5.0.0] - 2026-07-18
 
 TypeScript 7 hard-cutover lore makes Flow 5 smaller, stricter, and easier to

package/README.md

@@ -17,7 +17,7 @@ Full project documentation is available in the
 ## Quick start
 
 ```bash
-opencode plugin opencode-plugin-flow@5.0.0 --global --force
+opencode plugin opencode-plugin-flow@5.1.0 --global --force
 ```
 
 Start or restart OpenCode, then give Flow a goal:
@@ -41,21 +41,34 @@ restart.
                     features: rate-limit-middleware, per-route-config, docs-update
   (you approve the plan)
   flow_plan_approve plan locked — features are now immutable
-  flow_run_start    feature: rate-limit-middleware
+  flow_run_start    mutation acknowledged
+  flow_status       view: execution, feature: rate-limit-middleware
   ... implementation, tests ...
   flow_feature_complete
                     validationRun: "bun test tests/middleware.test.ts" passed
                     featureReviewDepth: standard
                     featureReview: passed
-  flow_run_start    feature: per-route-config
+  flow_run_start    mutation acknowledged
+  flow_status       view: execution, feature: per-route-config
   ...
 
 > /flow-status
   status: ok
-  workflowData.session.status: running, 1/3 features completed
-  nextAction: complete the feature under workflowData.session.activeFeature
+  workflowData.projection.view: compact
+  workflowData.projection.status: running
+  workflowData.projection.progress: { completed: 1, total: 3, remaining: 2 }
+
+> /flow-run
+  flow_status       view: execution
+                    workflowData.projection: full active-feature scope
 ```
 
+`flow_status` returns workflow state under `workflowData.projection`: compact is
+routing-only, execution is the full active-feature working scope, detail is
+diagnostic, and reviewer is narrow assignment context. State-changing tools
+return `workflowData.receipt` acknowledgements; a receipt never replaces a
+fresh status projection.
+
 Interrupt at any point; `/flow-run` resumes the next approved feature. On the
 final feature Flow requires broad project-level validation and a final review
 whose depth matches the approved plan before the session can close as
@@ -154,8 +167,8 @@ For broad implementation, the manager records whether work stayed serial,
 used exact-path candidate workers, used isolated worktrees, ran a tournament, or
 skipped eligible candidates. Feature completion can carry bounded
 `orchestrationPasses` with candidate eligibility, decision, and structured
-factors; `flow_status` reports the aggregate under
-`workflowData.session.budget.orchestration`.
+factors. Bounded projections report the relevant aggregate while full worker
+handoffs remain outside `.flow/**`.
 
 ## Install details and legacy cleanup
 
@@ -169,7 +182,7 @@ or sync command is required. To preview recoverable migration of pristine v4
 global skill folders:
 
 ```bash
-npx -y opencode-plugin-flow@5.0.0 legacy-cleanup --dry-run
+npx -y opencode-plugin-flow@5.1.0 legacy-cleanup --dry-run
 ```
 
 ## Development

package/dist/application/flow-service.d.ts

@@ -1,19 +1,14 @@
 import { z } from "zod";
-import type { Feature, Session, SessionId } from "../domain/session.js";
-import { summarizeSession, type TransitionEnvironment } from "../domain/transitions.js";
+import type { Session, SessionId } from "../domain/session.js";
+import { mutationReceiptProjection, type TransitionEnvironment } from "../domain/transitions.js";
 import type { SessionRepository } from "./ports/session-repository.js";
-type StatusResponse = ReturnType<typeof summarizeSession>;
-type ActiveStatusResponse = Extract<StatusResponse, {
-    workflowData: unknown;
-}>;
-type SessionWorkflowData = ActiveStatusResponse["workflowData"]["session"];
 type WorkflowData = {
-    session?: SessionWorkflowData;
+    projection?: unknown;
+    receipt?: ReturnType<typeof mutationReceiptProjection>;
     failure?: {
         summary: string;
         recovery?: string;
     };
-    startedFeature?: Feature;
     archive?: {
         sessionId: SessionId;
         closure: Session["closure"];
@@ -27,6 +22,7 @@ type ResponseContext = {
     statusSummary?: string;
     nextAction?: string;
     dataNote?: string;
+    warnings?: string[];
     workflowData?: WorkflowData;
     recovery?: string;
 };
@@ -35,7 +31,7 @@ export type FlowResponse = ResponseContext & {
     summary: string;
 };
 export type FlowService = {
-    status(): Promise<FlowResponse>;
+    status(input?: unknown): Promise<FlowResponse>;
     planSave(input: unknown): Promise<FlowResponse>;
     planApprove(): Promise<FlowResponse>;
     runStart(input: unknown): Promise<FlowResponse>;
@@ -43,6 +39,31 @@ export type FlowService = {
     featureReset(input: unknown): Promise<FlowResponse>;
     sessionClose(input: unknown): Promise<FlowResponse>;
 };
+export declare const FlowStatusSchema: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+    view: z.ZodLiteral<"reviewer">;
+    featureId: z.ZodPipe<z.ZodString, z.ZodTransform<import("../domain/session.js").FeatureId, string>>;
+    packetHash: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+    evidenceRefs: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>>;
+    expectedRevision: z.ZodNumber;
+    expectedSnapshotId: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+    reviewKind: z.ZodLiteral<"feature">;
+}, z.core.$strict>, z.ZodObject<{
+    view: z.ZodLiteral<"reviewer">;
+    featureId: z.ZodPipe<z.ZodString, z.ZodTransform<import("../domain/session.js").FeatureId, string>>;
+    packetHash: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+    evidenceRefs: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>>;
+    expectedRevision: z.ZodNumber;
+    expectedSnapshotId: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+    reviewKind: z.ZodLiteral<"final">;
+}, z.core.$strict>], "reviewKind">, z.ZodObject<{
+    view: z.ZodLiteral<"execution">;
+}, z.core.$strict>, z.ZodObject<{
+    view: z.ZodLiteral<"detail">;
+    sinceRevision: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    view: z.ZodDefault<z.ZodLiteral<"compact">>;
+    sinceRevision: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>]>;
 export declare const FlowPlanSaveSchema: z.ZodObject<{
     goal: z.ZodOptional<z.ZodString>;
     plan: z.ZodOptional<z.ZodObject<{
@@ -79,9 +100,15 @@ export declare const FlowRunStartSchema: z.ZodObject<{
     featureId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("../domain/session.js").FeatureId, string>>>;
 }, z.core.$strict>;
 export declare const FlowFeatureResetSchema: z.ZodObject<{
+    operationId: z.ZodString;
+    expectedRevision: z.ZodNumber;
+    expectedSnapshotId: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
     featureId: z.ZodPipe<z.ZodString, z.ZodTransform<import("../domain/session.js").FeatureId, string>>;
 }, z.core.$strict>;
 export declare const FlowSessionCloseSchema: z.ZodObject<{
+    operationId: z.ZodString;
+    expectedRevision: z.ZodNumber;
+    expectedSnapshotId: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
     kind: z.ZodEnum<{
         abandoned: "abandoned";
         completed: "completed";
@@ -89,23 +116,136 @@ export declare const FlowSessionCloseSchema: z.ZodObject<{
     }>;
     summary: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
-export declare const FlowFeatureCompleteToolSchema: z.ZodObject<{
-    status: z.ZodEnum<{
-        needs_input: "needs_input";
-        ok: "ok";
-    }>;
+export declare const FlowFeatureCompleteToolSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    operationId: z.ZodString;
+    expectedRevision: z.ZodNumber;
+    expectedSnapshotId: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
     featureId: z.ZodPipe<z.ZodString, z.ZodTransform<import("../domain/session.js").FeatureId, string>>;
     summary: z.ZodString;
-    artifactsChanged: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    status: z.ZodLiteral<"ok">;
+    artifactsChanged: z.ZodDefault<z.ZodArray<z.ZodObject<{
         path: z.ZodString;
     }, z.core.$strict>>>;
-    validationRun: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    validations: z.ZodArray<z.ZodObject<{
+        startedAt: z.ZodString;
+        completedAt: z.ZodString;
         command: z.ZodString;
+        summary: z.ZodString;
+        exitCode: z.ZodNumber;
+        outputDigest: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+        artifactRef: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"restricted_evidence_v1">;
+            digest: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+            byteLength: z.ZodNumber;
+        }, z.core.$strict>>;
+        environmentKeys: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    validationScope: z.ZodEnum<{
+        broad: "broad";
+        targeted: "targeted";
+    }>;
+    featureReviewDepth: z.ZodEnum<{
+        detailed: "detailed";
+        quick: "quick";
+        standard: "standard";
+    }>;
+    featureReview: z.ZodObject<{
         status: z.ZodEnum<{
             failed: "failed";
             passed: "passed";
         }>;
         summary: z.ZodString;
+        blockingFindings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            summary: z.ZodString;
+            severity: z.ZodDefault<z.ZodEnum<{
+                advisory: "advisory";
+                blocking: "blocking";
+            }>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+    finalReview: z.ZodOptional<z.ZodObject<{
+        status: z.ZodEnum<{
+            failed: "failed";
+            passed: "passed";
+        }>;
+        summary: z.ZodString;
+        blockingFindings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            summary: z.ZodString;
+            severity: z.ZodDefault<z.ZodEnum<{
+                advisory: "advisory";
+                blocking: "blocking";
+            }>>;
+        }, z.core.$strict>>>;
+        reviewDepth: z.ZodEnum<{
+            broad: "broad";
+            detailed: "detailed";
+        }>;
+    }, z.core.$strict>>;
+    reviewExecutions: z.ZodArray<z.ZodObject<{
+        attemptId: z.ZodString;
+        logicalPassId: z.ZodString;
+        featureId: z.ZodPipe<z.ZodString, z.ZodTransform<import("../domain/session.js").FeatureId, string>>;
+        reviewKind: z.ZodEnum<{
+            feature: "feature";
+            final: "final";
+        }>;
+        reviewSnapshotId: z.ZodPipe<z.ZodString, z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>>;
+        verdict: z.ZodEnum<{
+            failed: "failed";
+            passed: "passed";
+        }>;
+        startedAt: z.ZodString;
+        completedAt: z.ZodString;
+        terminalDisposition: z.ZodEnum<{
+            observed_unsubmitted: "observed_unsubmitted";
+            submitted: "submitted";
+        }>;
+        findings: z.ZodArray<z.ZodObject<{
+            taxonomy: z.ZodEnum<{
+                advisory: "advisory";
+                evidence_gap: "evidence_gap";
+                implementation_defect: "implementation_defect";
+                regression_coverage_gap: "regression_coverage_gap";
+            }>;
+            subject: z.ZodString;
+            requirementOrRisk: z.ZodString;
+            evidenceLocator: z.ZodString;
+            summary: z.ZodString;
+            severity: z.ZodEnum<{
+                advisory: "advisory";
+                blocking: "blocking";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    outcome: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"completed">;
+        summary: z.ZodOptional<z.ZodString>;
+        resolutionHint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    orchestrationPasses: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>, z.ZodObject<{
+    operationId: z.ZodString;
+    expectedRevision: z.ZodNumber;
+    expectedSnapshotId: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+    featureId: z.ZodPipe<z.ZodString, z.ZodTransform<import("../domain/session.js").FeatureId, string>>;
+    summary: z.ZodString;
+    status: z.ZodLiteral<"needs_input">;
+    artifactsChanged: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$strict>>>;
+    validations: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        startedAt: z.ZodString;
+        completedAt: z.ZodString;
+        command: z.ZodString;
+        summary: z.ZodString;
+        exitCode: z.ZodNumber;
+        outputDigest: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+        artifactRef: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"restricted_evidence_v1">;
+            digest: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+            byteLength: z.ZodNumber;
+        }, z.core.$strict>>;
+        environmentKeys: z.ZodArray<z.ZodString>;
     }, z.core.$strict>>>;
     validationScope: z.ZodOptional<z.ZodEnum<{
         broad: "broad";
@@ -148,11 +288,43 @@ export declare const FlowFeatureCompleteToolSchema: z.ZodObject<{
             detailed: "detailed";
         }>;
     }, z.core.$strict>>;
-    outcome: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        kind: z.ZodLiteral<"completed">;
-        summary: z.ZodOptional<z.ZodString>;
-        resolutionHint: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>, z.ZodObject<{
+    reviewExecutions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        attemptId: z.ZodString;
+        logicalPassId: z.ZodString;
+        featureId: z.ZodPipe<z.ZodString, z.ZodTransform<import("../domain/session.js").FeatureId, string>>;
+        reviewKind: z.ZodEnum<{
+            feature: "feature";
+            final: "final";
+        }>;
+        reviewSnapshotId: z.ZodPipe<z.ZodString, z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>>;
+        verdict: z.ZodEnum<{
+            failed: "failed";
+            passed: "passed";
+        }>;
+        startedAt: z.ZodString;
+        completedAt: z.ZodString;
+        terminalDisposition: z.ZodEnum<{
+            observed_unsubmitted: "observed_unsubmitted";
+            submitted: "submitted";
+        }>;
+        findings: z.ZodArray<z.ZodObject<{
+            taxonomy: z.ZodEnum<{
+                advisory: "advisory";
+                evidence_gap: "evidence_gap";
+                implementation_defect: "implementation_defect";
+                regression_coverage_gap: "regression_coverage_gap";
+            }>;
+            subject: z.ZodString;
+            requirementOrRisk: z.ZodString;
+            evidenceLocator: z.ZodString;
+            summary: z.ZodString;
+            severity: z.ZodEnum<{
+                advisory: "advisory";
+                blocking: "blocking";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    outcome: z.ZodObject<{
         kind: z.ZodEnum<{
             blocked: "blocked";
             needs_input: "needs_input";
@@ -160,84 +332,8 @@ export declare const FlowFeatureCompleteToolSchema: z.ZodObject<{
         }>;
         summary: z.ZodString;
         resolutionHint: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>], "kind">>;
-    orchestrationPasses: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        kind: z.ZodEnum<{
-            audit: "audit";
-            candidate: "candidate";
-            discovery: "discovery";
-            "implementation-decision": "implementation-decision";
-            review: "review";
-            validation: "validation";
-            verification: "verification";
-        }>;
-        decision: z.ZodOptional<z.ZodEnum<{
-            "candidate-exact-path": "candidate-exact-path";
-            "candidate-worktree": "candidate-worktree";
-            parallel: "parallel";
-            serial: "serial";
-            skipped: "skipped";
-            tournament: "tournament";
-        }>>;
-        decisionReason: z.ZodOptional<z.ZodString>;
-        candidateEligibility: z.ZodDefault<z.ZodEnum<{
-            eligible: "eligible";
-            not_eligible: "not_eligible";
-            unknown: "unknown";
-        }>>;
-        candidateDecision: z.ZodOptional<z.ZodEnum<{
-            serial_required: "serial_required";
-            skipped: "skipped";
-            used: "used";
-        }>>;
-        decisionFactors: z.ZodDefault<z.ZodArray<z.ZodEnum<{
-            independent_surface: "independent_surface";
-            needs_manager_judgment: "needs_manager_judgment";
-            overlapping_files: "overlapping_files";
-            shared_state: "shared_state";
-            small_slice: "small_slice";
-            validation_available: "validation_available";
-        }>>>;
-        modes: z.ZodDefault<z.ZodArray<z.ZodEnum<{
-            audit: "audit";
-            "candidate-implementation": "candidate-implementation";
-            evidence: "evidence";
-            review: "review";
-            validation: "validation";
-            verifier: "verifier";
-        }>>>;
-        workerCount: z.ZodDefault<z.ZodNumber>;
-        candidateWorkerCount: z.ZodDefault<z.ZodNumber>;
-        verifierWorkerCount: z.ZodDefault<z.ZodNumber>;
-        sliceIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
-        dependsOn: z.ZodDefault<z.ZodArray<z.ZodString>>;
-        writeScope: z.ZodDefault<z.ZodEnum<{
-            "exact-path": "exact-path";
-            "isolated-worktree": "isolated-worktree";
-            "manager-serial": "manager-serial";
-            mixed: "mixed";
-            none: "none";
-        }>>;
-        handoffRefs: z.ZodDefault<z.ZodArray<z.ZodString>>;
-        verificationStatus: z.ZodDefault<z.ZodEnum<{
-            downgraded: "downgraded";
-            failed: "failed";
-            mixed: "mixed";
-            "not-needed": "not-needed";
-            passed: "passed";
-            pending: "pending";
-        }>>;
-        outcome: z.ZodDefault<z.ZodEnum<{
-            accepted: "accepted";
-            modified: "modified";
-            "not-covered": "not-covered";
-            partial: "partial";
-            rejected: "rejected";
-            superseded: "superseded";
-        }>>;
-        synthesisRef: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>>;
-}, z.core.$strict>;
+    }, z.core.$strict>;
+    orchestrationPasses: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>], "status">;
 export declare function createFlowService(repository: SessionRepository, environment: TransitionEnvironment): FlowService;
 export {};

package/dist/application/ports/evidence-artifact-store.d.ts

@@ -0,0 +1,28 @@
+import type { EvidenceArtifactRef } from "../../domain/session.js";
+export declare const MAX_EVIDENCE_ARTIFACT_BYTES: number;
+export type EvidenceArtifactDigest = `sha256:${string}`;
+export type { EvidenceArtifactRef } from "../../domain/session.js";
+export interface EvidenceArtifactStore {
+    publishEvidenceArtifact(bytes: Uint8Array): Promise<EvidenceArtifactRef>;
+    readEvidenceArtifact(ref: EvidenceArtifactRef): Promise<Uint8Array>;
+}
+export declare class InvalidEvidenceArtifactReferenceError extends Error {
+    readonly code = "FLOW_EVIDENCE_INVALID_REFERENCE";
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class EvidenceArtifactNotFoundError extends Error {
+    readonly code = "FLOW_EVIDENCE_NOT_FOUND";
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class EvidenceArtifactIntegrityError extends Error {
+    readonly code = "FLOW_EVIDENCE_INTEGRITY";
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class EvidenceArtifactCollisionError extends Error {
+    readonly code = "FLOW_EVIDENCE_COLLISION";
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class EvidenceArtifactTooLargeError extends Error {
+    readonly code = "FLOW_EVIDENCE_TOO_LARGE";
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/application/ports/session-repository.d.ts

@@ -1,6 +1,13 @@
 import type { Session } from "../../domain/session.js";
-export type SessionTransaction = {
+import type { EvidenceArtifactStore } from "./evidence-artifact-store.js";
+import type { SourceIdentityProvider } from "./source-identity.js";
+export declare class ArchivedSessionLookupError extends Error {
+    readonly code = "FLOW_ARCHIVE_LOOKUP_FAILED";
+    constructor(message: string, options?: ErrorOptions);
+}
+export type SessionTransaction = EvidenceArtifactStore & SourceIdentityProvider & {
     load(): Promise<Session | null>;
+    findArchivedByOperationId(operationId: string): Promise<Session | null>;
     save(session: Session): Promise<Session>;
     archiveAndClear(session: Session): Promise<void>;
     quarantineUnreadable(): Promise<string | null>;

package/dist/application/ports/source-identity.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Application port for the authoritative source/worktree identity boundary.
+ *
+ * The provider derives a canonical, deterministic digest of the workspace
+ * source state (the "A1 canonical source digest"). It is the single trusted
+ * producer of source identity used by the transactional completion boundary.
+ * Callers never assert source identity; Flow recomputes it and binds evidence
+ * to it. The source-v2 manifest is materialization-sensitive:
+ * an indexed sparse-checkout path absent from disk is distinct from the same
+ * path materialized in a dense worktree.
+ */
+export type SourceDigest = `sha256:${string}`;
+export type SourceIdentity = {
+    /** Canonical lowercase SHA-256 digest of the source state. */
+    readonly digest: SourceDigest;
+    /** Whether the digest was derived from a Git manifest or a full-tree walk. */
+    readonly mode: "git" | "non-git";
+    /** Number of source entries that contributed to the digest. */
+    readonly entryCount: number;
+};
+export interface SourceIdentityProvider {
+    /**
+     * Compute the canonical source digest for the workspace. Implementations
+     * must fail closed on unsafe symlinks, unreadable entries, resource limits,
+     * or a workspace mutation observed while the source is being measured.
+     */
+    computeSourceIdentity(): Promise<SourceIdentity>;
+}
+/**
+ * Base class for source-identity failures. The message never carries absolute
+ * paths, file contents, or command output; only a bounded, safe reason.
+ */
+export declare class SourceIdentityError extends Error {
+    readonly code: string;
+    constructor(message: string, options?: ErrorOptions);
+}
+/** A symlink whose target escapes the workspace root or is absolute. */
+export declare class SourceIdentityUnsafeSymlinkError extends SourceIdentityError {
+    readonly code = "FLOW_SOURCE_IDENTITY_UNSAFE_SYMLINK";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** An entry that could not be read; measurement never silently skips state. */
+export declare class SourceIdentityUnreadableError extends SourceIdentityError {
+    readonly code = "FLOW_SOURCE_IDENTITY_UNREADABLE";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The source exceeded the bounded file-count or byte budget. */
+export declare class SourceIdentityOverflowError extends SourceIdentityError {
+    readonly code = "FLOW_SOURCE_IDENTITY_OVERFLOW";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The workspace changed while it was being measured. */
+export declare class SourceIdentityRaceError extends SourceIdentityError {
+    readonly code = "FLOW_SOURCE_IDENTITY_RACE";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Git enumeration failed for a Git workspace. */
+export declare class SourceIdentityGitError extends SourceIdentityError {
+    readonly code = "FLOW_SOURCE_IDENTITY_GIT";
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/application/replay/canonical-json.d.ts

@@ -0,0 +1,7 @@
+export type CanonicalJsonValue = null | boolean | number | string | readonly CanonicalJsonValue[] | {
+    readonly [key: string]: CanonicalJsonValue;
+};
+/** Stable, whitespace-free JSON with recursively sorted object keys. */
+export declare function canonicalizeReplayJson(value: CanonicalJsonValue): string;
+export declare const canonicalizeJson: typeof canonicalizeReplayJson;
+export declare const canonicalReplayJson: typeof canonicalizeReplayJson;