Interface RailOk

Type Declaration

• id: string

  Unique session identifier.

• schemaVersion: "v1"

  Schema version — always "v1" for this generation.

• phase:
      | "READY"
      | "TICKET"
      | "PLAN"
      | "PLAN_REVIEW"
      | "VALIDATION"
      | "IMPLEMENTATION"
      | "IMPL_REVIEW"
      | "EVIDENCE_REVIEW"
      | "COMPLETE"
      | "ARCHITECTURE"
      | "ARCH_REVIEW"
      | "ARCH_COMPLETE"
      | "REVIEW"
      | "REVIEW_COMPLETE"

  Current FlowGuard phase.

• binding: Readonly<
      {
          sessionId: string;
          worktree: string;
          fingerprint: string;
          resolvedAt: string;
      },
  >

  Workspace binding (OpenCode session <-> git worktree).

• ticket:
      | Readonly<
          {
              text: string;
              digest: string;
              source: "user"
              | "external";
              createdAt: string;
              inputOrigin?:
                  | "manual_text"
                  | "external_reference"
                  | "mixed"
                  | "workspace"
                  | "branch"
                  | "pr"
                  | "unknown";
              references?: Readonly<
                  {
                      ref: string;
                      type?: | "branch"
                      | "pr"
                      | "ticket"
                      | "issue"
                      | "commit"
                      | "url"
                      | "doc"
                      | "other";
                      title?: string;
                      source?: string;
                      extractedAt?: string;
                  },
              >[];
          },
      >
      | null

  Ticket/task evidence from /ticket.

• architecture:
      | Readonly<
          {
              id: string;
              title: string;
              adrText: string;
              status: "proposed"
              | "accepted"
              | "deprecated";
              createdAt: string;
              digest: string;
              reviewFindings?: Readonly<
                  {
                      iteration: number;
                      planVersion: number;
                      reviewMode: "subagent"
                      | "self";
                      overallVerdict: "approve" | "changes_requested" | "unable_to_review";
                      blockingIssues: Readonly<
                          { severity: ...; category: ...; message: ...; location?: ... },
                      >[];
                      majorRisks: Readonly<
                          { severity: ...; category: ...; message: ...; location?: ... },
                      >[];
                      missingVerification: string[];
                      scopeCreep: string[];
                      unknowns: string[];
                      reviewedBy: Readonly<
                          {
                              sessionId: string;
                              actorId?: (...)
                              | (...);
                              actorSource?: (...) | (...) | (...) | (...) | (...);
                              actorAssurance?: (...) | (...) | (...) | (...);
                          },
                      >;
                      reviewedAt: string;
                      attestation?: Readonly<
                          {
                              mandateDigest: ...;
                              criteriaVersion: ...;
                              toolObligationId: ...;
                              iteration: ...;
                              planVersion: ...;
                              reviewedBy: ...;
                          },
                      >;
                  },
              >[];
          },
      >
      | null

  Architecture Decision Record from /architecture.

• plan:
      | Readonly<
          {
              current: {
                  body: string;
                  digest: string;
                  sections: string[];
                  createdAt: string;
              };
              history: {
                  body: string;
                  digest: string;
                  sections: string[];
                  createdAt: string;
              }[];
              reviewFindings?: Readonly<
                  {
                      iteration: number;
                      planVersion: number;
                      reviewMode: "subagent"
                      | "self";
                      overallVerdict: "approve" | "changes_requested" | "unable_to_review";
                      blockingIssues: Readonly<
                          { severity: ...; category: ...; message: ...; location?: ... },
                      >[];
                      majorRisks: Readonly<
                          { severity: ...; category: ...; message: ...; location?: ... },
                      >[];
                      missingVerification: string[];
                      scopeCreep: string[];
                      unknowns: string[];
                      reviewedBy: Readonly<
                          {
                              sessionId: string;
                              actorId?: (...)
                              | (...);
                              actorSource?: (...) | (...) | (...) | (...) | (...);
                              actorAssurance?: (...) | (...) | (...) | (...);
                          },
                      >;
                      reviewedAt: string;
                      attestation?: Readonly<
                          {
                              mandateDigest: ...;
                              criteriaVersion: ...;
                              toolObligationId: ...;
                              iteration: ...;
                              planVersion: ...;
                              reviewedBy: ...;
                          },
                      >;
                  },
              >[];
          },
      >
      | null

  Plan record with version history from /plan.

• selfReview:
      | {
          iteration: number;
          maxIterations: number;
          prevDigest: string
          | null;
          currDigest: string;
          revisionDelta: "none" | "minor" | "major";
          verdict: "approve" | "changes_requested" | "unable_to_review";
      }
      | null

  Self-review loop state (PLAN phase, digest-stop).

• validation: Readonly<
      {
          checkId: string;
          passed: boolean;
          detail: string;
          executedAt: string;
          evidenceType?: | "external_reference"
          | "command_output"
          | "ci_run"
          | "manual_review";
          command?: string;
          evidenceSummary?: string;
      },
  >[]

  Validation check results (VALIDATION phase, N checks in one phase).

• implementation:
      | Readonly<
          {
              changedFiles: string[];
              domainFiles: string[];
              digest: string;
              executedAt: string;
          },
      >
      | null

  Implementation evidence from /implement.

• implReview:
      | Readonly<
          {
              iteration: number;
              maxIterations: number;
              prevDigest: string
              | null;
              currDigest: string;
              revisionDelta: "none" | "minor" | "major";
              verdict: "approve" | "changes_requested" | "unable_to_review";
              executedAt: string;
          },
      >
      | null

  Implementation review iteration result (IMPL_REVIEW phase, digest-stop).

• OptionalimplReviewFindings?: Readonly<
      {
          iteration: number;
          planVersion: number;
          reviewMode: "subagent"
          | "self";
          overallVerdict: "approve" | "changes_requested" | "unable_to_review";
          blockingIssues: Readonly<
              {
                  severity: "minor"
                  | "major"
                  | "critical";
                  category:
                      | "completeness"
                      | "correctness"
                      | "feasibility"
                      | "risk"
                      | "quality";
                  message: string;
                  location?: string;
              },
          >[];
          majorRisks: Readonly<
              {
                  severity: "minor"
                  | "major"
                  | "critical";
                  category:
                      | "completeness"
                      | "correctness"
                      | "feasibility"
                      | "risk"
                      | "quality";
                  message: string;
                  location?: string;
              },
          >[];
          missingVerification: string[];
          scopeCreep: string[];
          unknowns: string[];
          reviewedBy: Readonly<
              {
                  sessionId: string;
                  actorId?: string;
                  actorSource?: "unknown"
                  | "env"
                  | "git"
                  | "claim";
                  actorAssurance?: "best_effort" | "claim_validated" | "idp_verified";
              },
          >;
          reviewedAt: string;
          attestation?: Readonly<
              {
                  mandateDigest: string;
                  criteriaVersion: string;
                  toolObligationId: string;
                  iteration: number;
                  planVersion: number;
                  reviewedBy: "flowguard-reviewer";
              },
          >;
      },
  >[]

  Independent review findings for /implement (parallel, NOT mixed with ImplEvidence).

• OptionalreviewAssurance?: Readonly<
      {
          obligations: {
              obligationId: string;
              obligationType: "plan"
              | "implement"
              | "architecture"
              | "review";
              iteration: number;
              planVersion: number;
              criteriaVersion: string;
              mandateDigest: string;
              createdAt: string;
              pluginHandshakeAt: string | null;
              status: "pending" | "fulfilled" | "consumed" | "blocked";
              invocationId: string | null;
              blockedCode: string | null;
              fulfilledAt: string | null;
              consumedAt: string | null;
              metadata?: Record<string, unknown>;
          }[];
          invocations: Readonly<
              {
                  invocationId: string;
                  obligationId: string;
                  obligationType: "plan"
                  | "implement"
                  | "architecture"
                  | "review";
                  parentSessionId: string;
                  childSessionId: string;
                  agentType: "flowguard-reviewer";
                  invocationMode:
                      | "host_subagent_task"
                      | "sdk_session_prompt"
                      | "manual_attested";
                  hostVisible: boolean;
                  promptHash: string;
                  mandateDigest: string;
                  criteriaVersion: string;
                  findingsHash: string;
                  invokedAt: string;
                  fulfilledAt: string
                  | null;
                  consumedByObligationId: string | null;
                  capturedVerdict?: string;
                  capturedRawFindings?: Record<string, unknown>;
                  source?: "host-orchestrated" | "agent-submitted-attested";
                  reviewOutputMode: "structured_output" | "text_compat";
                  structuredOutputUsed: boolean;
                  reviewAssuranceLevel: "structured_high" | "text_compat_lower";
                  extractionMethod?: "direct_json" | "json_fence" | "outermost_braces";
                  modelCapabilityError?: string;
              },
          >[];
      },
  >

  P35 strict independent-review obligations and invocation evidence.

• reviewDecision:
      | Readonly<
          {
              verdict: "approve"
              | "changes_requested"
              | "reject";
              rationale: string;
              decidedAt: string;
              decidedBy: string;
              decisionIdentity?: Readonly<
                  {
                      actorId: string;
                      actorEmail: string
                      | null;
                      actorDisplayName?: string | null;
                      actorSource: "unknown" | "env" | "git" | "claim" | "oidc";
                      actorAssurance: "best_effort" | "claim_validated" | "idp_verified";
                  },
              >;
          },
      >
      | null

  Human review decision at PLAN_REVIEW, EVIDENCE_REVIEW, or ARCH_REVIEW.

• reviewReportPath: string | null

  Absolute path to the generated review report file (REVIEW phase, P8b).

• nextAdrNumber: number

  Next auto-generated ADR sequence number for /architecture.

• activeProfile:
      | {
          id: string;
          name: string;
          ruleContent: string;
          phaseRuleContent?: Record<string, string>;
      }
      | null

  Active profile information — resolved at hydrate time. Contains the profile ID, name, and LLM rule content. The ruleContent is the stack-specific guidance text injected into tool responses when commands reference "profile rules". phaseRuleContent maps Phase values to additional phase-specific text that is appended to ruleContent when the session is in that phase. Null only if no profile was resolved (should not happen — baseline is always available).

• activeChecks: string[]

  Active validation checks for this session. Open string set — profile registry validates at runtime. Base: [test_quality, rollback_safety]. Extended per profile.

• policySnapshot: Readonly<
      {
          mode: string;
          hash: string;
          resolvedAt: string;
          requestedMode: string;
          source?: "default"
          | "explicit"
          | "central"
          | "repo";
          effectiveGateBehavior: "auto_approve" | "human_gated";
          degradedReason?: string;
          resolutionReason?: string;
          centralMinimumMode?: "solo" | "team" | "regulated";
          policyDigest?: string;
          policyVersion?: string;
          policyPathHint?: string;
          requireHumanGates: boolean;
          maxSelfReviewIterations: number;
          maxImplReviewIterations: number;
          allowSelfApproval: boolean;
          minimumActorAssuranceForApproval:
              | "best_effort"
              | "claim_validated"
              | "idp_verified";
          requireVerifiedActorsForApproval: boolean;
          identityProvider?: | {
              issuer: string;
              audience: string[];
              claimMapping: {
                  subjectClaim: string;
                  emailClaim: string;
                  nameClaim: string;
              };
              mode: "static";
              signingKeys: (
                  | {
                      kind: "jwk";
                      kid: string;
                      alg: "RS256"
                      | "ES256";
                      jwk:
                          | { kty: "RSA"; n: string; e: string }
                          | { kty: "EC"; x: string; y: string; crv: string };
                  }
                  | { kind: "pem"; kid: string; alg: "RS256"
                  | "ES256"; pem: string }
              )[];
          }
          | {
              issuer: string;
              audience: string[];
              claimMapping: {
                  subjectClaim: string;
                  emailClaim: string;
                  nameClaim: string;
              };
              mode: "jwks";
              jwksPath?: string;
              jwksUri?: string;
              cacheTtlSeconds: number;
          };
          identityProviderMode: "optional"
          | "required";
          selfReview?: {
              subagentEnabled: boolean;
              fallbackToSelf: boolean;
              strictEnforcement: boolean;
          };
          reviewOutputPolicy?: "structured_required"
          | "text_compat_allowed";
          reviewInvocationPolicy?:
              | "host_task_required"
              | "host_task_preferred"
              | "sdk_allowed";
          audit: {
              emitTransitions: boolean;
              emitToolCalls: boolean;
              enableChainHash: boolean;
          };
          actorClassification: Record<string, string>;
      },
  >

  Immutable policy snapshot — frozen at session creation. Records which FlowGuard rules governed this session. The hash provides non-repudiation for auditors.

• initiatedBy: string

  Identity of the session initiator (author). Set once at hydrate time, never mutated. Used for regulated approval four-eyes enforcement: initiatedBy !== reviewDecision.decidedBy (approve path).

  P30: For regulated sessions, this MUST be a known actor identity, not the technical session ID. Use initiatedByIdentity for full provenance.

• OptionalinitiatedByIdentity?: Readonly<
      {
          actorId: string;
          actorEmail: string
          | null;
          actorDisplayName?: string | null;
          actorSource: "unknown" | "env" | "git" | "claim" | "oidc";
          actorAssurance: "best_effort" | "claim_validated" | "idp_verified";
      },
  >

  Structured initiator identity for regulated approval (P30). Persists actor identity at session creation for four-eyes proof. Required for regulated mode.

• OptionalactorInfo?: Readonly<
      {
          id: string;
          email: string
          | null;
          displayName?: string | null;
          source: "unknown" | "env" | "git" | "claim" | "oidc";
          assurance: "best_effort" | "claim_validated" | "idp_verified";
          verificationMeta?: Readonly<
              {
                  issuer: string;
                  audience: string[];
                  keyId: string;
                  algorithm: string;
                  verifiedAt: string;
              },
          >;
      },
  >

  Resolved actor identity at hydrate time (P27). Best-effort operator identity — NOT an authentication claim. Absent when no actor identity was resolved; null is not a valid state value.

• OptionaldiscoveryDigest?: string | null

  SHA-256 digest of the DiscoveryResult at session creation time. Used for drift detection: if the workspace discovery changes, this digest will no longer match the current discovery.json. Null for sessions created before Phase 5 (discovery system).

• OptionaldiscoverySummary?:
      | {
          primaryLanguages: string[];
          frameworks: string[];
          topologyKind: "unknown"
          | "monorepo"
          | "single-project";
          moduleCount: number;
          hasApiSurface: boolean;
          hasPersistenceSurface: boolean;
          hasCiCd: boolean;
          hasSecuritySurface: boolean;
          codeSurfaceStatus?: "failed" | "ok" | "partial";
          apiEndpointCount?: number;
          hasAuthBoundary?: boolean;
      }
      | null

  Lightweight discovery summary for quick consumption by Plan/Review/Implement. NOT the full DiscoveryResult — just the most useful fields. Null for sessions created before Phase 5 (discovery system).

• OptionaldetectedStack?:
      | {
          summary: string;
          items: {
              kind: | "language"
              | "framework"
              | "runtime"
              | "buildTool"
              | "tool"
              | "testFramework"
              | "qualityTool"
              | "database";
              id: string;
              version?: string;
              evidence?: string;
          }[];
          versions: {
              id: string;
              version: string;
              target: | "language"
              | "framework"
              | "runtime"
              | "buildTool"
              | "tool"
              | "testFramework"
              | "qualityTool"
              | "database";
              evidence?: string;
          }[];
          targets?: {
              kind: "compilerTarget";
              id: string;
              value: string;
              evidence?: string;
          }[];
          scopes?: {
              path: string;
              summary?: string;
              items: {
                  kind: | "language"
                  | "framework"
                  | "runtime"
                  | "buildTool"
                  | "tool"
                  | "testFramework"
                  | "qualityTool"
                  | "database";
                  id: string;
                  version?: string;
                  evidence?: string;
              }[];
              versions: {
                  id: string;
                  version: string;
                  target: | "language"
                  | "framework"
                  | "runtime"
                  | "buildTool"
                  | "tool"
                  | "testFramework"
                  | "qualityTool"
                  | "database";
                  evidence?: string;
              }[];
          }[];
      }
      | null

  Compact detected stack evidence for surfacing in flowguard_status.

  Derived evidence — NOT SSOT. The authoritative stack data lives in DiscoveryResult.stack. This is a compact projection of all detected stack items (versioned and unversioned), sorted deterministically by category then id.

  Null when no items were detected or for pre-discovery sessions.

• OptionalverificationCandidates?: {
      kind:
          | "format"
          | "build"
          | "test"
          | "lint"
          | "typecheck"
          | "security"
          | "coverage";
      command: string;
      source: string;
      confidence: "high"
      | "medium"
      | "low";
      reason: string;
  }[]

  Advisory verification command candidates derived from stack + manifest evidence.

  Derived evidence — NOT SSOT. These candidates are planning hints only and MUST NOT be treated as executed checks.

• transition:
      | {
          from: | "READY"
          | "TICKET"
          | "PLAN"
          | "PLAN_REVIEW"
          | "VALIDATION"
          | "IMPLEMENTATION"
          | "IMPL_REVIEW"
          | "EVIDENCE_REVIEW"
          | "COMPLETE"
          | "ARCHITECTURE"
          | "ARCH_REVIEW"
          | "ARCH_COMPLETE"
          | "REVIEW"
          | "REVIEW_COMPLETE";
          to: | "READY"
          | "TICKET"
          | "PLAN"
          | "PLAN_REVIEW"
          | "VALIDATION"
          | "IMPLEMENTATION"
          | "IMPL_REVIEW"
          | "EVIDENCE_REVIEW"
          | "COMPLETE"
          | "ARCHITECTURE"
          | "ARCH_REVIEW"
          | "ARCH_COMPLETE"
          | "REVIEW"
          | "REVIEW_COMPLETE";
          event: | "TICKET_SELECTED"
          | "ARCHITECTURE_SELECTED"
          | "REVIEW_SELECTED"
          | "PLAN_READY"
          | "SELF_REVIEW_MET"
          | "SELF_REVIEW_PENDING"
          | "APPROVE"
          | "CHANGES_REQUESTED"
          | "REJECT"
          | "ALL_PASSED"
          | "CHECK_FAILED"
          | "IMPL_COMPLETE"
          | "REVIEW_MET"
          | "REVIEW_PENDING"
          | "REVIEW_DONE"
          | "ERROR"
          | "ABORT";
          at: string;
      }
      | null

  Last transition (from → to via event). Null before first transition.

• error:
      | Readonly<
          {
              code: string;
              message: string;
              recoveryHint: string;
              occurredAt: string;
          },
      >
      | null

  Error state. Non-null triggers ERROR event in guard evaluation.

• createdAt: string

  Session creation timestamp (set once by init()).

• OptionalarchiveStatus?: "pending" | "verified" | "failed" | "created" | null

  Archive lifecycle status for completed sessions.

  Only set for regulated clean completions (EVIDENCE_REVIEW → APPROVE → COMPLETE). Non-regulated sessions and aborted sessions do not set this field.

  • pending — archive creation in progress
  • created — archive created, verification pending
  • verified — archive created and verification passed
  • failed — archive creation or verification failed

  Invariant: phase === 'COMPLETE' && policySnapshot.mode === 'regulated' && !error && archiveStatus !== 'verified' = NOT a clean regulated completion.

  Added in P26 — .optional() for backward compatibility (no schema version bump).