opencode-plugin-flow 4.4.0 → 5.1.0

package/CHANGELOG.md

@@ -2,6 +2,96 @@
 
 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
+recover without carrying a v4 compatibility layer:
+
+- The compiler is TypeScript 7.0.2; the pinned toolchain is Bun 1.3.14,
+  Biome 2.5.4, OpenCode plugin 1.18.3, and Zod 4.4.3. Published code now
+  requires Node.js 24 or newer and CI covers Node 24 and 26.
+- Source code now follows `domain -> application -> infrastructure ->
+  platform`: pure transitions use injected time and IDs, application use cases
+  depend on repository ports, filesystem state is an outer implementation,
+  and OpenCode owns only host transport and rendering.
+- OpenCode's embedded validator is private to the host adapter. Flow's core
+  schemas use its direct Zod dependency, shared fixtures keep both wire
+  contracts aligned, and declaration emit no longer leaks package-manager or
+  nested-validator paths.
+- Persisted sessions use schema version 3. Version 2 sessions are not migrated;
+  they are reported as unsupported and preserved in quarantine so a new v5
+  session can start safely.
+- Public use-case results have an explicit typed operation status. Repository-
+  and caller-controlled prose is confined to `workflowData`; top-level
+  summaries, next actions, and recovery fields remain plugin-authored. Feature
+  and session IDs are branded, feature IDs are consistently lowercase
+  kebab-case at every input boundary, and all superseded `src/runtime` and
+  `src/adapters` entrypoints are removed.
+- Source and declaration imports follow NodeNext ESM rules with explicit `.js`
+  specifiers, and the packed-package smoke test compiles a strict NodeNext
+  consumer without skipping library checks before importing the plugin in Node.
+- Workspace roots are canonicalized and every Flow-managed directory and file
+  rejects symbolic links before read or mutation. Archive publication is
+  no-clobber and retry-safe, while lock contention and malformed owner metadata
+  fail closed for manual inspection instead of using age or liveness to steal a
+  lock. Completion outcomes require an explicit discriminator, and domain
+  transitions copy caller-owned plan and evidence collections before recording
+  them.
+- Flow no longer synchronizes Markdown into OpenCode's global skill registry.
+  Core command guidance and optional helpers are embedded in the plugin;
+  `flow_guidance` returns exact package-versioned documents by stable id, plugin
+  startup performs no global skill filesystem work, and `flow_status` no longer
+  carries setup/restart health.
+- Plugin configuration only registers commands and agents; it performs no
+  workspace filesystem I/O and maintains no ambient instruction projection.
+  `/flow-review` validates OpenCode's native subtask identity and agent before
+  rewriting only its prompt, so malformed dispatch fails closed.
+- Orchestration telemetry retains at most 50 recent pass records and accepts at
+  most 50 per completion. Deduplication is scoped to that retained telemetry
+  window, and failed completion mutations now update `timestamps.updatedAt`
+  from the same instant recorded in `lastError`.
+- The experimental compaction hook, token telemetry, phase boundaries, resume
+  packets, and acknowledgement protocol are gone. Review retry exhaustion uses
+  the ordinary blocked-feature/reset path, while a recorded closure makes the
+  session archive-only until retry-safe publication succeeds.
+- The old doctor/sync/uninstall CLI is replaced by explicit
+  `legacy-cleanup --dry-run|--apply`. Apply never deletes: it moves only
+  marker-proven pristine v4 folders to a recovery archive and refuses
+  foreign, edited, extra, malformed, or symlinked content.
+
 ## [4.4.0] - 2026-07-17
 
 Prompt economy lore makes Flow's instructions smaller, more role-specific, and

package/README.md

@@ -6,10 +6,10 @@ then implement one feature at a time with enforced validation and review
 evidence. State lives in `.flow/session.json`, so a session survives restarts,
 model switches, and context loss.
 
-The design is skills-first: the skills carry planning, execution, validation,
-review, and orchestration judgment, while the plugin runtime stays deliberately
-small — it keeps the session ledger and enforces the hard gates prompts should
-not be trusted to remember.
+The design is guidance-first: package-owned Markdown carries planning,
+execution, validation, review, and orchestration judgment, while the plugin
+runtime stays deliberately small — it keeps the session ledger and enforces the
+hard gates prompts should not be trusted to remember.
 
 Full project documentation is available in the
 [Flow OpenCode wiki](https://github.com/ddv1982/flow-opencode/wiki).
@@ -17,11 +17,10 @@ Full project documentation is available in the
 ## Quick start
 
 ```bash
-opencode plugin opencode-plugin-flow@4.4.0 --global --force
-npx -y opencode-plugin-flow@4.4.0 sync
+opencode plugin opencode-plugin-flow@5.1.0 --global --force
 ```
 
-Restart OpenCode, then give Flow a goal:
+Start or restart OpenCode, then give Flow a goal:
 
 ```text
 /flow-auto add rate limiting to the public API
@@ -42,20 +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: running, 1/3 features completed
-  nextAction: complete feature "per-route-config"
+  status: ok
+  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
@@ -65,7 +78,7 @@ completed.
 
 | Command | Purpose |
 | --- | --- |
-| `/flow-auto <goal>` | Drive the full skill-guided loop. |
+| `/flow-auto <goal>` | Drive the full guidance-driven loop. |
 | `/flow-plan <goal>` | Create or approve a plan. |
 | `/flow-run` | Execute one approved feature. |
 | `/flow-review` | Run a read-only review. |
@@ -73,20 +86,22 @@ completed.
 
 Commands are compiled entrypoints: manager commands carry only their applicable
 core instructions, while `/flow-review` runs against the reserved reviewer's
-role-specific agent contract. They keep working even when OpenCode's native
-skill discovery lags behind a fresh install (see
-[docs/troubleshooting.md](docs/troubleshooting.md)).
+role-specific agent contract. Flow does not install files into OpenCode's
+global skill registry and does not depend on native skill discovery.
 
-`flow-test`, `flow-deslop`, `flow-ui-quality`, and `flow-commit` are managed
-helper skills, not public commands.
-`flow-commit` is user-triggered only and stays outside the autonomous loop.
+`flow-test`, `flow-deslop`, `flow-ui-quality`, and `flow-commit` are optional
+package-owned guides loaded on demand through `flow_guidance`, not public
+commands. `flow-commit` is user-triggered only and stays outside the autonomous
+loop.
 
 ## Tools
 
-The runtime exposes seven tools:
+The plugin exposes eight tools. `flow_guidance` is read-only and returns embedded
+Markdown; the other seven form the stateful runtime surface:
 
 | Tool | Purpose |
 | --- | --- |
+| `flow_guidance` | Load exact package-owned guidance by stable id. |
 | `flow_status` | Read the active session and next action. |
 | `flow_plan_save` | Create a session and/or save a draft plan. |
 | `flow_plan_approve` | Approve the draft plan. |
@@ -101,7 +116,7 @@ final feature also needs a passing `finalReview`.
 
 ## What the runtime enforces
 
-The runtime owns only safety; judgment lives in the skills:
+The runtime owns only safety; judgment lives in package-owned guidance:
 
 - `.flow/session.json` is the single source of truth; writes are locked and
   atomic, and closed sessions are archived under `.flow/history/`.
@@ -114,19 +129,18 @@ The runtime owns only safety; judgment lives in the skills:
   that is shallower than the approved feature requires.
 - Failed reviews are bounded: a failed review pauses by default, and autonomous
   repair is limited to one repair plus one retry before the feature blocks.
-- Completed feature counts are telemetry only; Flow does not stop an approved
-  plan just because several features have completed. Review retry boundaries
-  still return a bounded resume packet and require explicit `phaseBoundaryAck`
-  before starting the next feature.
-- Skills do not estimate context pressure or request host compaction. Only a
-  runtime-issued phase boundary stops the current loop for a fresh invocation.
+- Review exhaustion uses the ordinary blocked-feature state; continuing requires
+  an explicit `flow_feature_reset`, not a second checkpoint protocol.
+- Once a closure is recorded, the session is archive-only. If publication fails,
+  retry `flow_session_close`; no run, reset, approval, or replan can reopen it.
 - A session can close as `completed` only after final completion has passed.
-- Crash recovery is built in: stale session locks expire automatically and
-  unreadable session files are quarantined with recovery guidance, never
-  silently deleted.
+- Session locks fail closed: Flow never guesses that an old lock is abandoned,
+  and only the unique owner may release it. Unreadable session files are
+  quarantined with recovery guidance, never silently deleted.
 - Flow writes `.flow/.gitignore` so session state stays out of Git by default.
-- `.flow/opencode-instructions.md` is a generated projection of the active
-  session that keeps ambient context accurate; do not edit it.
+- `.flow/session.json` is the only active-state representation. Canonical Flow
+  commands call `flow_status` before acting; plugin configuration does not read,
+  refresh, or project workspace state.
 
 ## Hidden workers
 
@@ -153,27 +167,29 @@ 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
-`session.budget.orchestration`.
+factors. Bounded projections report the relevant aggregate while full worker
+handoffs remain outside `.flow/**`.
 
-## Install details, doctor, repair, uninstall
+## Install details and legacy cleanup
 
-See [docs/troubleshooting.md](docs/troubleshooting.md) for skill sync
-mechanics, the `doctor`/`sync` CLI, older-OpenCode install fallback, stuck
-session recovery, and uninstall (`uninstall --dry-run` previews removals).
+See [docs/troubleshooting.md](docs/troubleshooting.md) for updates,
+older-OpenCode install fallback, stuck session recovery, and removal of global
+Flow skill folders left by v4.
 
-To update a pinned Flow version, rerun the install command with the new
-version. To inspect skill health:
+To update a pinned Flow version, rerun the install command with the new version.
+Flow starts with the new package-owned guidance immediately; no second restart
+or sync command is required. To preview recoverable migration of pristine v4
+global skill folders:
 
 ```bash
-npx -y opencode-plugin-flow@4.4.0 doctor
+npx -y opencode-plugin-flow@5.1.0 legacy-cleanup --dry-run
 ```
 
 ## Development
 
 ```bash
 bun install
-bun run check        # typecheck + lint + build + tests
+bun run check        # typecheck + lint + prompt quality + build + tests
 bun run smoke:live   # boots a real OpenCode server against the packed tarball
 ```
 
@@ -185,7 +201,8 @@ import flowPlugin from "opencode-plugin-flow";
 
 See [docs/development.md](docs/development.md) and
 [docs/maintainer-contract.md](docs/maintainer-contract.md) for the
-runtime/skills split and release process.
+v5 domain/application/infrastructure/platform boundaries, guidance split, and
+release process.
 
 ## Credits
 
@@ -195,5 +212,5 @@ work on parallel agent workflows. Flow also draws conceptual inspiration from
 emphasis on codebase orientation, context engineering, agent orchestration,
 and reviewable handoffs.
 
-The Flow version is its own OpenCode-native design: skills-first,
+The Flow version is its own OpenCode-native design: package-owned guidance,
 manager-owned state, hidden workers, and no extra runtime ledger.

package/dist/application/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class UnreadableFlowSessionError extends Error {
+    readonly code = "UNREADABLE_FLOW_SESSION";
+    readonly reason: string;
+    constructor(message: string, reason: string);
+}

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

@@ -0,0 +1,339 @@
+import { z } from "zod";
+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 WorkflowData = {
+    projection?: unknown;
+    receipt?: ReturnType<typeof mutationReceiptProjection>;
+    failure?: {
+        summary: string;
+        recovery?: string;
+    };
+    archive?: {
+        sessionId: SessionId;
+        closure: Session["closure"];
+    };
+    quarantine?: {
+        reason: string;
+        preservedAt?: string;
+    };
+};
+type ResponseContext = {
+    statusSummary?: string;
+    nextAction?: string;
+    dataNote?: string;
+    warnings?: string[];
+    workflowData?: WorkflowData;
+    recovery?: string;
+};
+export type FlowResponse = ResponseContext & {
+    status: "ok" | "error" | "missing_goal" | "missing_session";
+    summary: string;
+};
+export type FlowService = {
+    status(input?: unknown): Promise<FlowResponse>;
+    planSave(input: unknown): Promise<FlowResponse>;
+    planApprove(): Promise<FlowResponse>;
+    runStart(input: unknown): Promise<FlowResponse>;
+    featureComplete(input: unknown): Promise<FlowResponse>;
+    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<{
+        summary: z.ZodString;
+        overview: z.ZodString;
+        requirements: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        decisions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        finalReviewPolicy: z.ZodOptional<z.ZodEnum<{
+            broad: "broad";
+            detailed: "detailed";
+        }>>;
+        features: z.ZodArray<z.ZodObject<{
+            id: z.ZodPipe<z.ZodString, z.ZodTransform<import("../domain/session.js").FeatureId, string>>;
+            title: z.ZodString;
+            summary: z.ZodString;
+            status: z.ZodOptional<z.ZodEnum<{
+                blocked: "blocked";
+                completed: "completed";
+                in_progress: "in_progress";
+                pending: "pending";
+            }>>;
+            reviewDepth: z.ZodOptional<z.ZodEnum<{
+                detailed: "detailed";
+                quick: "quick";
+                standard: "standard";
+            }>>;
+            targets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            validation: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            dependsOn: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<import("../domain/session.js").FeatureId, string>>>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+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";
+        deferred: "deferred";
+    }>;
+    summary: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+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;
+    status: z.ZodLiteral<"ok">;
+    artifactsChanged: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$strict>>>;
+    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";
+        targeted: "targeted";
+    }>>;
+    featureReviewDepth: z.ZodOptional<z.ZodEnum<{
+        detailed: "detailed";
+        quick: "quick";
+        standard: "standard";
+    }>>;
+    featureReview: 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>>>;
+    }, 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.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";
+            replan_required: "replan_required";
+        }>;
+        summary: z.ZodString;
+        resolutionHint: z.ZodOptional<z.ZodString>;
+    }, 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);
+}