@quantiya/codevibe-core 2.0.1 → 2.0.3

package/dist/local-executor/task-group-types.d.ts

@@ -0,0 +1,346 @@
+import type { TeamExecution } from './team-execution-flag';
+import type { AgentKind } from './types';
+/**
+ * A shared-contract reference + access mode (Condition 2, #C12-2).
+ * snake_case-irrelevant single words; `access` reuses the lowercase wire
+ * values `'write' | 'read'` of `codevibe_policy::ContractAccess`.
+ */
+export interface ContractRefInput {
+    path: string;
+    access: 'write' | 'read';
+}
+/**
+ * The 4 disjointness-condition inputs (#C12-2). **snake_case field names**
+ * — deserializes to `codevibe_policy::OwnershipScope` which has no serde
+ * rename. See the casing warning at the top of this file.
+ */
+export interface OwnershipScopeInput {
+    /** Condition 1 — file paths this track may WRITE. */
+    write_paths: string[];
+    /** Condition 2 — shared contracts this track touches (tagged write/read). */
+    shared_contracts: ContractRefInput[];
+    /** Condition 3 — test surfaces this track owns. */
+    test_surfaces: string[];
+    /** Condition 4 — auto-modified files this track's tooling rewrites. */
+    auto_modified_files: string[];
+}
+/**
+ * One ordered work item (§2.1). Each becomes a track. `implementorAgent` is
+ * the UPPERCASE `CLAUDE | CODEX | GEMINI` (the `AgentKind` union).
+ */
+export interface WorkItemInput {
+    ownershipScope: OwnershipScopeInput;
+    implementorAgent: AgentKind;
+    isSharedTestOwner: boolean;
+    /**
+     * CP-12 W4 (#593) §3.1 — the track's brief, E2E-encrypted under the session
+     * key (a BARE base64 ciphertext string — NOT a `{ciphertextB64,…}` envelope;
+     * recovery already knows the session + key version). The desktop encrypts it
+     * at `/team` dispatch and the engine persists it verbatim onto
+     * `TrackDescriptor.encrypted_brief` as an OPAQUE pass-through blob (never
+     * decrypted server-side). On a desktop restart the recovery handler returns
+     * the ciphertext so the desktop re-decrypts the brief (the local
+     * `briefsByTrackIndex` map is empty post-restart). NULLABLE — a track may
+     * legitimately have no `description`; in that case the desktop sends no
+     * ciphertext (→ wire `null` → recovery treats it as "no brief", an empty brief).
+     * The PLAINTEXT brief NEVER goes on the wire — only this ciphertext.
+     */
+    encryptedBrief?: string;
+}
+/**
+ * User-lowered ceilings (§2.1, §11.4). LOWER-only — the server rejects
+ * values above the product max. Both fields optional.
+ */
+export interface UserCeilingsInput {
+    maxAutoReviseAttempts?: number;
+    maxWallClockMinutes?: number;
+}
+/**
+ * `createTaskGroup` mutation input (§2.1). The server validates disjointness
+ * (#C12-2) BEFORE creating any track.
+ */
+export interface CreateTaskGroupInput {
+    /** The ONE team Session (`caller_sub == session.userId`). */
+    sessionId: string;
+    /** Ordered work items (each a future track). */
+    workItems: WorkItemInput[];
+    /** Lock-row dedup key (#C12-1). */
+    groupIdempotencyKey: string;
+    /** Option-A re-submission (#C12-3); `undefined` = all tracks eligible. */
+    phase0aTrackIndex?: number;
+    /** User-lowered ceilings (#C12-11); `undefined` = product defaults. */
+    userCeilings?: UserCeilingsInput;
+    /**
+     * CP-14 P1 (§2.1) — the team EXECUTION MODEL: `'worktree_merge' |
+     * ({@link TeamExecution}) — always `'worktree_merge'` since the §10
+     * retirement (2026-07-03; strict pre-P1 disjointness,
+     * byte-identical). Send `'worktree_merge'` ONLY when this client will run the
+     * merge-train (its own `resolveTeamExecution`); that opts the group into
+     * overlapping-track dispatch (the merge-train + the server-side shared-contract
+     * gate become the authority). Snake_case wire value end-to-end (no GraphQL
+     * enum) — typed as the {@link TeamExecution} union for compile-time safety;
+     * the GraphQL field is `String`.
+     */
+    executionModel?: TeamExecution;
+    /**
+     * CP-14 P1 (§2.1 / LOCK #C14-INDEP) — requested convergence: `'joint' |
+     * 'independent'`. `undefined` ⇒ Joint. SERVER-VALIDATED (a multi-track
+     * code-change is forced `joint`). Usually omitted until CP-4 populates it.
+     */
+    convergence?: string;
+}
+/** Which disjointness condition failed (abstract, #C12-3, snake_case wire). */
+export type FailingCondition = 'write_path' | 'shared_contract' | 'test_surface' | 'inherently_ordered';
+/** Deterministic recommended resolution option (#C12-3, snake_case wire). */
+export type RecommendedOption = 'phase_lock_then_parallel' | 'assign_shared_test_owner' | 'single_track' | 'serial_owner';
+/**
+ * The cited overlap — an externally-tagged enum (no serde rename on
+ * `codevibe_policy::DisjointnessViolation`), so on the wire it is an object
+ * with a SINGLE variant key. e.g.
+ * `{ "WritePathOverlap": { "file": "src/x.ts", "tracks": [0, 1] } }`.
+ */
+export type DisjointnessViolation = {
+    WritePathOverlap: {
+        file: string;
+        tracks: number[];
+    };
+} | {
+    SharedContractMultiWriter: {
+        contract: string;
+        writers: number[];
+    };
+} | {
+    TestSurfaceOverlapNoOwner: {
+        surface: string;
+        tracks: number[];
+    };
+} | {
+    AutoModifiedFileOverlap: {
+        file: string;
+        tracks: number[];
+    };
+};
+/** The disjointness rejection (failure arm of `CreateTaskGroupResult`). */
+export interface DisjointnessRejection {
+    failing_condition: FailingCondition;
+    recommended_option: RecommendedOption;
+    cited_overlap: DisjointnessViolation;
+}
+/**
+ * `createTaskGroup` result (§2.1). Returned as an AWSJSON string by the
+ * backend resolver (`createTaskGroup.res.vtl` → `$util.toJson($ctx.result)`)
+ * and parsed by the SDK. Mirrors `types.rs::CreateTaskGroupOutput`:
+ *   - accepted arm carries `taskGroupId` + `dispatchedTracks` (+ `rejection: null`).
+ *   - rejected arm carries `rejection` (failing condition + recommended
+ *     option + cited overlap, #C12-2 / #C12-3) (+ `taskGroupId: null` +
+ *     `dispatchedTracks: null`).
+ *
+ * SERDE FIDELITY (load-bearing): the Rust `CreateTaskGroupOutput` (types.rs)
+ * tags `task_group_id` / `dispatched_tracks` / `rejection` with
+ * `#[serde(default)]` but NO `skip_serializing_if`, so serde ALWAYS
+ * serializes all four keys — the inactive arm's fields are explicit `null`,
+ * NOT omitted. Model them as present-but-nullable (`T | null`) rather than
+ * optional (`field?:`), and discriminate the arm on `accepted` (the bool),
+ * never on key ABSENCE.
+ */
+export interface CreateTaskGroupResult {
+    accepted: boolean;
+    taskGroupId: string | null;
+    dispatchedTracks: number | null;
+    rejection: DisjointnessRejection | null;
+}
+/** One track's changed-file set in the LE-signed classification (§2.1). */
+export interface TrackChangedFiles {
+    trackIndex: number;
+    paths: string[];
+}
+/** MergeGate result discriminator (§2.1). SCREAMING wire values. */
+export type MergeResult = 'PASS' | 'FAIL';
+/** The 6-class MergeGate failure classification (§2.1, #C12-8). */
+export type MergeFailureClass = 'SHARED_FILE_CONFLICT' | 'INTEGRATION_FAILURE' | 'REVIEWER_DISAGREEMENT' | 'SCOPE_VIOLATION' | 'DIRTY_REPO_STATE' | 'BUDGET_EXHAUSTED';
+/** Retry-target kind discriminator (§2.1). SCREAMING wire values. */
+export type MergeRetryTargetKind = 'TRACK' | 'SERIAL_OWNER' | 'NONE';
+/**
+ * LE-recommended retry target (§2.1). `trackIndex` is the `TRACK:<idx>` when
+ * `kind === 'TRACK'`, else `null`. It is part of the classification's signing
+ * domain, so callers send it as explicit `null` (NOT omitted) when absent —
+ * mirroring Rust `MergeRetryTarget::track_index: Option<u32>` which serializes
+ * to `"trackIndex": null` (no `skip_serializing_if`), matching json-freeze's
+ * null output for byte-identical canonicalization.
+ */
+export interface MergeRetryTarget {
+    kind: MergeRetryTargetKind;
+    trackIndex: number | null;
+}
+/**
+ * EncryptedPayloadInput (2f.4 contract, schema.graphql:986-991). Reused for
+ * the human-readable `detail` (E2E-encrypted under the team session key).
+ */
+export interface EncryptedPayloadInput {
+    ciphertextB64: string;
+    nonceB64?: string;
+    sessionId: string;
+    keyVersion?: number;
+}
+/**
+ * The LE-signed, server-readable MergeGate classification envelope (§2.1,
+ * #C12-8). Carries only non-secret structural metadata; the human-readable
+ * detail stays E2E-encrypted in `SubmitMergeGateVerdictInput.detail`. The
+ * server verifies `signatureB64` (ECDSA P-256, LE Class A key resolved by
+ * `(caller_sub, leDeviceId)`) before routing.
+ *
+ * `signatureB64` is produced by `signMergeClassification` (class-a-sign.ts)
+ * over this object MINUS `signatureB64`; `leDeviceId` is INSIDE the signing
+ * domain.
+ *
+ * Mirrors `types.rs::MergeClassificationInput` (`rename_all = "camelCase"`).
+ * The Rust `Option` fields use `#[serde(default)]` WITHOUT
+ * `skip_serializing_if`, so on the verifier side they serialize to `null`
+ * when absent — the LE-side canonicalization MUST include them as `null`
+ * too (json-freeze emits nulls), which is why this interface's nullable
+ * fields are set to `null` (not omitted) when building the signing object.
+ */
+export interface MergeClassificationInput {
+    result: MergeResult;
+    failureClass: MergeFailureClass | null;
+    failingTrackIndex: number | null;
+    sharedFilePath: string | null;
+    changedFileSets: TrackChangedFiles[];
+    retryTarget: MergeRetryTarget;
+    conflictingTracks: number[];
+    sharedContractRef: string | null;
+    leDeviceId: string;
+    signatureB64: string;
+}
+/** `submitMergeGateVerdict` mutation input (§2.1). */
+export interface SubmitMergeGateVerdictInput {
+    taskGroupId: string;
+    mergeGateId: string;
+    sessionId: string;
+    verdictIdempotencyKey: string;
+    classification: MergeClassificationInput;
+    detail: EncryptedPayloadInput;
+}
+/**
+ * `submitMergeGateVerdict` result (§2.1). Returned as an AWSJSON string by
+ * `submitMergeGateVerdict.res.vtl`. Mirrors
+ * `types.rs::SubmitMergeGateVerdictOutput` — `outcome` is the resolved label
+ * (`"complete"` or a `halted_reason` const), and on an idempotent replay it
+ * is the stored `TaskGroupRow.merge_gate_verdict.outcome` (#C12-1).
+ */
+export interface SubmitMergeGateVerdictResult {
+    outcome: string;
+}
+/**
+ * PHASE-589/469 W1 — the CONTENT-FREE closed reason set for a team-track local
+ * hard-fail. W1 wires EVERY team-track hard-fail dead-end (the 4 pre-submit /
+ * promote-time sites), so the closed set has exactly these 4 labels — NEVER raw
+ * test output. The engine `submit_track_verification_outcome.rs::VALID_OUTCOMES`
+ * is the mirror authority and rejects any value outside this set.
+ *
+ * W2 routes by the revisable-vs-terminal split: REVISABLE reasons AUTO-REVISE
+ * (mint round-N+1; the track stays InFlight + renders `Revising`) while the
+ * per-track cap remains, else terminal-fail; TERMINAL reasons ALWAYS
+ * terminal-fail (security/IO backstops — NEVER auto-revised):
+ *   - `verification_failure` — a declared test failed OR the pre-submit
+ *     re-capture failed. [REVISABLE — W2 auto-revises]
+ *   - `out_of_scope_write`   — the track wrote outside its declared paths.
+ *     [REVISABLE — W2 auto-revises]
+ *   - `review_integrity_violation` — the shadow was modified after review/test
+ *     (the #598 integrity drift, pre-submit AND promote-time). [TERMINAL — a
+ *     security backstop; NEVER auto-revised]
+ *   - `promote_failure` — a promote-time capture/IO failure. [TERMINAL]
+ */
+export type TeamTrackFailureReason = 'verification_failure' | 'out_of_scope_write' | 'review_integrity_violation' | 'promote_failure';
+/**
+ * No-op UX (#1) — the full set of `submitTrackVerificationOutcome` outcomes: the
+ * 4 hard-FAILURE reasons above PLUS the BENIGN `no_change` terminal. A team track
+ * that produced an EMPTY diff (nothing to do) reports `no_change` so the engine
+ * marks it `Passed` (via `pass_track_and_schedule`) — NOT `Failed` — so the
+ * scheduler fires the MergeGate on all-terminal-no-failure and NEVER triggers the
+ * all-or-nothing revert of sibling tracks.
+ */
+export type TeamTrackVerificationOutcome = TeamTrackFailureReason | 'no_change';
+/**
+ * PHASE-589/469 W1 — `submitTrackVerificationOutcome` mutation input
+ * (LOCK #589-F). The desktop reports that ONE team track HARD-FAILED its own
+ * local gate (a declared-test failure, an out-of-scope write, a review-integrity
+ * drift, or a promote-time failure) so the engine marks the track `Failed` NOW →
+ * its existing scheduler drain + group-escalation resolves the group promptly
+ * (instead of the slow lease sweeper). A NET-NEW shape: NO proposal /
+ * `encProposal` — the marker MUST NOT fan out to reviewers (#598's guarantee).
+ * `outcome` is the CONTENT-FREE closed reason label — NEVER raw test output.
+ */
+export interface SubmitTrackVerificationOutcomeInput {
+    taskGroupId: string;
+    trackIndex: number;
+    sessionId: string;
+    verdictIdempotencyKey: string;
+    /**
+     * The CONTENT-FREE closed outcome label (4 failure reasons + the benign
+     * `no_change`). The server validates it against the fixed set and rejects an
+     * unknown value.
+     */
+    outcome: TeamTrackVerificationOutcome;
+    /**
+     * PHASE-589/469 W2 — the round-N `reviewer_quorum` gate id of the track's
+     * CURRENT round (the gate `runImplementorRound` registered). REQUIRED for a
+     * REVISABLE outcome (`verification_failure` / `out_of_scope_write`): the engine
+     * uses it as the parent for the round-N+1 revise gate + the `REVISE_FEEDBACK`
+     * packet's `gateId` (so `taskByGateId` re-resolves the track). Omitted for
+     * TERMINAL outcomes (`review_integrity_violation` / `promote_failure`), which
+     * never auto-revise.
+     */
+    gateId?: string;
+}
+/**
+ * PHASE-589/469 W1 — `submitTrackVerificationOutcome` result. Returned as an
+ * AWSJSON string by `submitTrackVerificationOutcome.res.vtl`. Mirrors
+ * `types.rs::SubmitTrackVerificationOutcomeOutput` — `trackState` is the
+ * track's terminal state label (`"Failed"`), or on an idempotent replay the
+ * already-terminal state.
+ */
+export interface SubmitTrackVerificationOutcomeResult {
+    trackState: string;
+}
+/**
+ * PHASE-589/469 W3.2 — the closed 5-option group-escalation decision set
+ * (position-bound, server-derived — the SAME `SOURCE_OF_TRUTH_LITERALS` 5-tuple
+ * `gate-prompts.ts` renders). Mirror of the engine `VALID_DECISIONS`.
+ */
+export type GroupDecisionLabel = 'ACCEPT' | 'ACCEPT_WITH_NOTES' | 'REJECT_WITH_NOTES' | 'REJECT_RESTART' | 'ABORT_TASK';
+/** The CLAIM | COMMIT phase discriminator for the two-phase group decision. */
+export type GroupDecisionPhase = 'claim' | 'commit';
+/**
+ * PHASE-589/469 W3.2 — `claimGroupDecision` mutation input (LOCK #589-J). The
+ * two-phase group-escalation resolve: CLAIM atomically locks the group to the
+ * first acting surface; COMMIT (after the desktop revert side-effect) drives the
+ * group terminal. CONTENT-FREE scalars only — NO proposal, NO prose; the
+ * optional `*_WITH_NOTES` notes ride E2E-encrypted exactly as
+ * `applyUserDecision.notes` do (the engine NEVER decrypts them).
+ */
+export interface ClaimGroupDecisionInput {
+    taskGroupId: string;
+    sessionId: string;
+    phase: GroupDecisionPhase;
+    decision: GroupDecisionLabel;
+    verdictIdempotencyKey: string;
+    /** On COMMIT — the token the CLAIM minted (must match the live claim). Absent on CLAIM. */
+    claimToken?: string;
+    /** Optional E2E-encrypted advisory notes on an `*_WITH_NOTES` decision. */
+    notes?: string;
+}
+/**
+ * PHASE-589/469 W3.2 — `claimGroupDecision` result. On a CLAIM: `phase:"claimed"`
+ * + the minted `claimToken`. On a COMMIT: `phase:"committed"` + the group's
+ * terminal status label. On an idempotent replay: `already_claimed` /
+ * `already_committed`. Returned as an AWSJSON string. Mirrors
+ * `types.rs::ClaimGroupDecisionOutput`.
+ */
+export interface ClaimGroupDecisionResult {
+    phase: 'claimed' | 'committed' | 'already_claimed' | 'already_committed';
+    decision: string;
+    claimToken: string;
+    /** The group's resulting status label after a COMMIT (`"complete"` | `"halted"`); empty after a CLAIM. */
+    groupStatus?: string;
+}

package/dist/local-executor/team-execution-flag.d.ts

@@ -0,0 +1,21 @@
+/** The single execution model. `legacy_disjoint` was deleted 2026-07-03 (§10). */
+export type TeamExecution = 'worktree_merge';
+/** The hard default — and only — execution model. */
+export declare const DEFAULT_TEAM_EXECUTION: TeamExecution;
+/**
+ * The env var that FORMERLY selected the execution model. Inert since the
+ * `legacy_disjoint` deletion (kept exported for the operator-docs surface and
+ * so stale dogfood scripts that still set it don't break anything).
+ */
+export declare const TEAM_EXECUTION_ENV_VAR = "CODEVIBE_TEAM_EXECUTION";
+/** Is `v` the (single) valid {@link TeamExecution} label? */
+export declare function isTeamExecution(v: unknown): v is TeamExecution;
+/**
+ * Resolve the effective `team.execution` model: always `worktree_merge`. The
+ * override/env parameters are retained for call-site stability; every input —
+ * including a stale `legacy_disjoint` — resolves to the single model (the
+ * legacy path no longer exists to be selected).
+ */
+export declare function resolveTeamExecution(_override?: TeamExecution | null | undefined, _env?: NodeJS.ProcessEnv): TeamExecution;
+/** True — the merge-before-push model is the only execution model. */
+export declare function isWorktreeMergeEnabled(_override?: TeamExecution | null | undefined, _env?: NodeJS.ProcessEnv): boolean;

package/dist/local-executor/track-registry.d.ts

@@ -0,0 +1,50 @@
+import type { ImplementorHandle } from './types';
+/** Composite map key `<task_group_id>::<track_index>` (track identity). */
+export declare function trackKey(taskGroupId: string, trackIndex: number): string;
+/**
+ * One tracked track process. `generation` is the `dispatch_generation` that
+ * launched this process — used to ignore a duplicate `TrackAssigned` for an
+ * already-launched generation (#C12-17) and to allow a NEWER generation
+ * (dispute re-dispatch) to supersede a stale one.
+ */
+export interface TrackProcess {
+    taskGroupId: string;
+    trackIndex: number;
+    taskId: string;
+    /** The `dispatch_generation` of the `TrackAssigned` that launched it. */
+    generation: number;
+    /** The isolated per-track state dir (canonicalized realpath). */
+    stateDir: string;
+    /** The live implementor handle (for stop-on-halt + lease tracking). */
+    handle: ImplementorHandle;
+}
+/**
+ * In-memory registry of concurrent track processes, owned by one
+ * `LocalExecutorImpl`. NOT process-global (each session/LE has its own), unlike
+ * the double-construction registry in local-executor-impl.ts.
+ */
+export declare class TrackRegistry {
+    private readonly processes;
+    /**
+     * Idempotency decision (#C12-17). Returns `true` when a `TrackAssigned` for
+     * `(taskGroupId, trackIndex, generation)` should be IGNORED because that
+     * generation (or a newer one) is already launched. Returns `false` when the
+     * caller should spawn.
+     *
+     * A STRICTLY NEWER generation is NOT a duplicate — it is a dispute
+     * re-dispatch (#C12-19) and is allowed to spawn (the caller replaces the
+     * stale entry via `register`). A generation EQUAL to (replay) OR OLDER than
+     * (stale outbox re-drain) the launched generation is a duplicate → ignore.
+     */
+    isDuplicate(taskGroupId: string, trackIndex: number, generation: number): boolean;
+    /** Record a launched track process (overwrites a superseded generation). */
+    register(proc: TrackProcess): void;
+    /** Lookup by track identity (latest generation). */
+    get(taskGroupId: string, trackIndex: number): TrackProcess | undefined;
+    /** All in-flight track processes for a group (for stop-on-halt). */
+    forGroup(taskGroupId: string): TrackProcess[];
+    /** Drop a track entry (e.g., after it terminates). */
+    delete(taskGroupId: string, trackIndex: number): void;
+    /** Test-only — number of tracked processes. */
+    get sizeForTests(): number;
+}