@osovv/vv-opencode 1.4.2 → 1.4.3-rc.1

package/dist/lib/workflow-contract.d.ts

@@ -0,0 +1,277 @@
+export declare const WORKFLOW_CONTRACT_VERSION = 1;
+export declare const WORKFLOW_ID_MAX_CHARS = 128;
+export declare const WORKFLOW_TEXT_MAX_CHARS = 2000;
+export declare const WORKFLOW_TEXT_MAX_ITEMS = 64;
+/** Normalized workspace-relative path, or the reason a declared path is malformed. */
+export type DeclaredScopePathResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Text-level canonical normalization for declared scope file paths. The linter
+ * and the runtime snapshot fingerprint share this representation so a plan that
+ * lints clean cannot declare paths the runtime normalizer rejects on sight.
+ * Filesystem-specific checks (existence, symlinks, regular files) stay in the
+ * runtime normalizer; this function is deliberately pure.
+ */
+export declare function normalizeDeclaredScopePath(raw: string): DeclaredScopePathResult;
+/**
+ * Normalize a declared directory subtree. Identical traversal and wildcard
+ * rejection as file paths, but one trailing separator is allowed and removed so
+ * an explicitly named subtree can never be normalized into an empty segment.
+ */
+export declare function normalizeDeclaredDirectoryPath(raw: string): DeclaredScopePathResult;
+/** Canonical reviewer roles accepted inside a delegated checkpoint's reviewer set. */
+export type DelegatedReviewer = "spec" | "code";
+/** Typed delegated obligation for one declared plan task. */
+export interface DelegatedTaskDefinition {
+    /** Canonical task id used by depends_on and checkpoint coverage (e.g. "T-001"). */
+    taskId: string;
+    /** Declaring identity element name (e.g. "TASK-T-001"). */
+    taskElement: string;
+    /** Declaring wave id in document order (e.g. "WAVE-1"). */
+    wave: string;
+    /** Normalized workspace-relative write scope files declared for the task. */
+    writeScope: string[];
+    /** Declared task title lifted from the validated source, when present. */
+    title?: string;
+    /** Declared acceptance criterion texts lifted from the validated source. */
+    acceptance?: string[];
+    /** Declared verification command texts lifted from the validated source. */
+    verification?: string[];
+    /** Declared task dependency ids lifted from the validated source. */
+    dependsOn?: string[];
+}
+/** Typed delegated obligation for one declared review checkpoint. */
+export interface DelegatedCheckpointDefinition {
+    /** Declared checkpoint identity (e.g. "CHECKPOINT-R-001"). */
+    checkpointId: string;
+    kind: "milestone" | "final";
+    /** Wave barrier that must be accepted before the checkpoint may start. */
+    afterWave: string;
+    /** Canonical task ids covered by the checkpoint. */
+    covers: string[];
+    /** Normalized workspace-relative files reviewed by the checkpoint. */
+    scope: string[];
+    /** Declared reviewer roles; every role must pass for the checkpoint to pass. */
+    reviewers: DelegatedReviewer[];
+    /** Acceptance criterion texts recorded in the plan. */
+    acceptance: string[];
+    /** Verification command texts recorded in the plan. */
+    verification: string[];
+}
+/** Typed obligations extracted from a plan's delegated execution section. */
+export interface DelegatedPlanDefinition {
+    mode: "delegated";
+    /** Declared wave ids in document order. */
+    waves: string[];
+    tasks: DelegatedTaskDefinition[];
+    checkpoints: DelegatedCheckpointDefinition[];
+}
+/** Either a typed delegated definition or the collected validation errors. */
+export type DelegatedPlanExtractionResult = {
+    ok: true;
+    definition: DelegatedPlanDefinition;
+} | {
+    ok: false;
+    errors: string[];
+};
+export type WorkflowReviewer = DelegatedReviewer;
+/** Where a registered obligation came from: the selected source, the user, or the controller. */
+export type WorkflowObligationOrigin = "source" | "user" | "controller";
+/** Structural native definition shape accepted by the common adapter. */
+export interface NativePlanMetadata {
+    mode: "delegated";
+    waves: string[];
+    tasks: DelegatedTaskDefinition[];
+    checkpoints: DelegatedCheckpointDefinition[];
+}
+/** Bounded generic task contract with explicit dependencies, scope, and reviewer set. */
+export interface WorkflowTaskContract {
+    taskId: string;
+    title: string;
+    goal: string;
+    acceptanceCriteria: string[];
+    verification: string[];
+    /** Normalized workspace-relative exact files the task may write. */
+    writeScope: string[];
+    /** Task ids that must be accepted before this task may launch. */
+    dependsOn: string[];
+    /** Checkpoint ids that must pass before this task may launch. */
+    blockedBy: string[];
+    /** Explicit reviewer set; [] deliberately means no independent review. */
+    requiredReviewers: WorkflowReviewer[];
+}
+/** Bounded generic checkpoint obligation with explicit coverage and reviewer set. */
+export interface WorkflowCheckpointContract {
+    checkpointId: string;
+    kind: "milestone" | "final";
+    /** Task ids covered by the checkpoint. */
+    covers: string[];
+    /** Normalized workspace-relative exact files under review. */
+    scope: string[];
+    /** Explicit reviewer set; a checkpoint with an empty set is invalid. */
+    requiredReviewers: WorkflowReviewer[];
+    acceptance: string[];
+    verification: string[];
+    origin: WorkflowObligationOrigin;
+    /** Checkpoint ids that must pass before this checkpoint may start. */
+    dependsOn: string[];
+}
+/** Normalized exact files plus explicitly named directory subtrees. */
+export interface WorkflowExecutionBoundary {
+    files: string[];
+    directories: string[];
+}
+export type WorkflowExecutionSource = {
+    kind: "native-package";
+    planPath: string;
+    specPath: string;
+    planSha256: string;
+    specSha256: string;
+    definition: NativePlanMetadata;
+} | {
+    kind: "provided-plan";
+    reference: string;
+    sha256?: string;
+} | {
+    kind: "conversation-scoped";
+};
+export type WorkflowExecutionState = "preparing" | "active" | "sealed";
+/** Monotonic contract revision number for one execution. */
+export type WorkflowExecutionRevision = number;
+export type WorkflowLineageKind = "initial" | "amendment" | "replacement" | "split";
+/** One recorded amendment/replacement/split lineage event. */
+export interface WorkflowLineageEntry {
+    lineageId: string;
+    kind: WorkflowLineageKind;
+    amendmentId: string;
+    parentTaskId?: string;
+    childTaskIds: string[];
+    previousRevision: WorkflowExecutionRevision;
+    newRevision: WorkflowExecutionRevision;
+    rationale: string;
+    createdAt: string;
+}
+/** Lifecycle stages that advance authority may cover. */
+export type WorkflowAuthorityStage = "specification" | "planning" | "implementation" | "verification";
+export type WorkflowAuthorityProvenance = "controller_delegated" | "user_observed" | "unspecified";
+/** Bounded decision, stage, and file boundary of one authority grant. */
+export interface WorkflowAuthorityScope {
+    stages: WorkflowAuthorityStage[];
+    decisionScope: string;
+    fileBoundary: string[];
+    reservedStops: WorkflowAuthorityStage[];
+}
+export interface WorkflowAuthorityExtension {
+    extensionId: string;
+    messageId: string;
+    messageCreatedMs: number;
+    units: number;
+    createdAt: string;
+}
+export interface WorkflowAuthorityRevocation {
+    revocationId: string;
+    /** "narrow" disables out-of-scope credits; "revoke" disables all future credits. */
+    kind: "narrow" | "revoke";
+    reason: string;
+    /** Surviving stages after a narrowing; absent for a full revocation. */
+    narrowedStages?: WorkflowAuthorityStage[];
+    revokedAt: string;
+}
+/** Advance-authority record with its finite shared reserve metadata. */
+export interface WorkflowAuthorityRecord {
+    authorityId: string;
+    /** Owning common execution; a second initial grant for the same run cannot add reserve. */
+    runId: string;
+    rootSessionId: string;
+    grantedByMessageId: string;
+    messageCreatedMs: number;
+    scope: WorkflowAuthorityScope;
+    initialUnits: number;
+    extensions: WorkflowAuthorityExtension[];
+    revocations: WorkflowAuthorityRevocation[];
+    createdAt: string;
+}
+/** Recorded stage approval bound to an approved artifact hash and provenance. */
+export interface WorkflowStageApproval {
+    approvalId: string;
+    authorityId: string;
+    stage: WorkflowAuthorityStage;
+    artifactPath: string;
+    artifactSha256: string;
+    provenance: WorkflowAuthorityProvenance;
+    recordedAt: string;
+}
+/** One consumed unit of the shared advance-recovery reserve, bound to its exact target. */
+export interface WorkflowReserveDebit {
+    recoveryId: string;
+    authorityId: string;
+    targetKind: "task" | "checkpoint";
+    targetId: string;
+    units: number;
+    debitedAt: string;
+}
+/** Session-wide claim that one root-user message already funded an authority grant. */
+export interface WorkflowMessageClaim {
+    messageId: string;
+    runId: string;
+    authorityId: string;
+    claimedAt: string;
+}
+export interface WorkflowContractProblem {
+    code: string;
+    message: string;
+}
+export type WorkflowContractValidation<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    problems: WorkflowContractProblem[];
+};
+/** Whether a value is a bounded explicit workflow identity (not a native-only pattern). */
+export declare function isBoundedWorkflowId(value: unknown): value is string;
+/**
+ * Normalize an explicit reviewer array. Absent, non-array, malformed, or
+ * duplicate-bearing input returns undefined so callers cannot silently turn a
+ * missing or invalid declaration into "no review". An explicit empty array is
+ * preserved as [] because it deliberately means no independent review.
+ */
+export declare function normalizeReviewerSet(value: unknown): WorkflowReviewer[] | undefined;
+/** Validate and normalize exact files plus explicitly named directory subtrees. */
+export declare function validateExecutionBoundary(raw: unknown): WorkflowContractValidation<WorkflowExecutionBoundary>;
+/** Whether a normalized path is contained in a normalized execution boundary. */
+export declare function isPathInExecutionBoundary(path: string, boundary: WorkflowExecutionBoundary): boolean;
+/** Validate one generic task contract. */
+export declare function validateWorkflowTaskContract(raw: unknown): WorkflowContractValidation<WorkflowTaskContract>;
+/** Validate one generic checkpoint contract. */
+export declare function validateWorkflowCheckpointContract(raw: unknown): WorkflowContractValidation<WorkflowCheckpointContract>;
+/**
+ * Validate unique ids, exact references, boundary containment, and acyclicity
+ * across tasks and checkpoints. Same-batch references are validated before any
+ * caller publishes an item or key index.
+ */
+export declare function validateWorkflowContractGraph(graph: {
+    tasks: readonly WorkflowTaskContract[];
+    checkpoints: readonly WorkflowCheckpointContract[];
+    boundary: WorkflowExecutionBoundary;
+}): WorkflowContractValidation<{
+    tasks: WorkflowTaskContract[];
+    checkpoints: WorkflowCheckpointContract[];
+}>;
+/**
+ * Adapt native-extracted task obligations into common task contracts, lifting
+ * acceptance/verification/dependency text from the validated source instead of
+ * inventing generic requirements. The source's own wave barriers remain owned
+ * by the native adapter and are not converted into per-task dependencies here.
+ */
+export declare function taskContractsFromNativeDefinition(definition: NativePlanMetadata): WorkflowTaskContract[];
+/** Adapt native checkpoints into common checkpoint contracts with source origin. */
+export declare function checkpointContractsFromNativeDefinition(definition: NativePlanMetadata, scope?: {
+    origin?: WorkflowObligationOrigin;
+    dependsOn?: string[];
+}): WorkflowCheckpointContract[];