@h-rig/contracts 0.0.6-alpha.16 → 0.0.6-alpha.160

package/dist/src/control-plane-types.d.ts

@@ -0,0 +1,323 @@
+/**
+ * Control-plane shared types.
+ *
+ * These types previously lived inside the runtime native PR/merge/verify
+ * lifecycle modules (pr-automation.ts, pr-review-gate.ts, verifier.ts) and
+ * were imported across module boundaries, creating mutual coupling. They are
+ * hoisted here — the bottom contracts layer — so the lifecycle plugins
+ * (@rig/pr-review-plugin, @rig/bundle-default-lifecycle) and the dumb runtime
+ * substrate (git-ops, task-ops) all reference one canonical definition without
+ * importing each other.
+ */
+import type { CapabilityId } from "./capability-id";
+export type GitHubCommandResult = {
+    readonly exitCode: number;
+    readonly stdout?: string;
+    readonly stderr?: string;
+};
+export type GitHubCommandRunner = (args: readonly string[], options?: {
+    readonly cwd?: string;
+}) => Promise<GitHubCommandResult>;
+export type GitCommandRunner = (args: readonly string[], options?: {
+    readonly cwd?: string;
+}) => Promise<GitHubCommandResult>;
+export type RigAutomationConfig = {
+    readonly automation?: {
+        readonly maxValidationAttempts?: number;
+        readonly maxPrFixIterations?: number;
+    };
+    readonly pr?: {
+        readonly mode?: "auto" | "ask" | "off";
+        readonly watchChecks?: boolean;
+        readonly autoFixChecks?: boolean;
+        readonly autoFixReview?: boolean;
+        readonly pendingTimeoutMs?: number;
+        readonly pendingPollMs?: number;
+    };
+    readonly merge?: {
+        readonly mode?: "auto" | "off" | "pr-ready";
+        readonly method?: "repo-default" | "squash" | "merge" | "rebase";
+        readonly deleteBranch?: "repo-default" | boolean;
+        readonly allowedFailures?: readonly string[];
+        readonly bypass?: boolean;
+    };
+    readonly review?: {
+        readonly mode?: "off" | "advisory" | "required";
+        readonly provider?: "greptile" | "github";
+    };
+};
+export type PrAutomationResult = {
+    readonly status: "skipped" | "opened" | "merged" | "needs_attention";
+    readonly prUrl?: string;
+    readonly iterations: number;
+    readonly actionableFeedback: readonly string[];
+    readonly merged?: boolean;
+};
+export type PrAutomationLifecycle = {
+    readonly onPrOpened?: (input: {
+        readonly prUrl: string;
+    }) => Promise<void> | void;
+    readonly onReviewCiStarted?: (input: {
+        readonly prUrl: string;
+        readonly iteration: number;
+    }) => Promise<void> | void;
+    readonly onFeedback?: (input: {
+        readonly prUrl: string;
+        readonly iteration: number;
+        readonly feedback: readonly string[];
+    }) => Promise<void> | void;
+    readonly onMergeStarted?: (input: {
+        readonly prUrl: string;
+    }) => Promise<void> | void;
+    readonly onMerged?: (input: {
+        readonly prUrl: string;
+    }) => Promise<void> | void;
+};
+export type GithubUser = {
+    readonly login?: string | null;
+} | null;
+export type GithubPullRequestReview = {
+    readonly id?: string | null;
+    readonly state?: string | null;
+    readonly body?: string | null;
+    readonly commit_id?: string | null;
+    readonly html_url?: string | null;
+    readonly author?: GithubUser;
+};
+export type GithubReviewThreadComment = {
+    readonly author?: GithubUser;
+    readonly body?: string | null;
+    readonly path?: string | null;
+    readonly url?: string | null;
+    readonly createdAt?: string | null;
+};
+export type GithubReviewThread = {
+    readonly id?: string | null;
+    readonly isResolved?: boolean | null;
+    readonly isOutdated?: boolean | null;
+    readonly comments?: {
+        readonly nodes?: readonly GithubReviewThreadComment[] | null;
+        readonly pageInfo?: {
+            readonly hasNextPage?: boolean | null;
+            readonly endCursor?: string | null;
+        } | null;
+    } | null;
+};
+export type GithubReviewComment = {
+    readonly id?: number | string | null;
+    readonly user?: GithubUser;
+    readonly author?: GithubUser;
+    readonly body?: string | null;
+    readonly path?: string | null;
+    readonly html_url?: string | null;
+    readonly url?: string | null;
+    readonly commit_id?: string | null;
+    readonly original_commit_id?: string | null;
+};
+export type GithubIssueComment = {
+    readonly id?: number | string | null;
+    readonly user?: GithubUser;
+    readonly author?: GithubUser;
+    readonly body?: string | null;
+    readonly html_url?: string | null;
+    readonly url?: string | null;
+    readonly created_at?: string | null;
+};
+export type PrCheckSummary = {
+    readonly name: string;
+    readonly status?: string | null;
+    readonly state?: string | null;
+    readonly conclusion?: string | null;
+    readonly detailsUrl?: string | null;
+};
+export type GithubStatusCheckRollupItem = PrCheckSummary & {
+    readonly __typename?: string | null;
+    readonly context?: string | null;
+    readonly detailsUrl?: string | null;
+    readonly link?: string | null;
+    readonly headSha?: string | null;
+    readonly head_sha?: string | null;
+    readonly output?: {
+        readonly title?: string | null;
+        readonly summary?: string | null;
+        readonly text?: string | null;
+    } | null;
+    readonly app?: {
+        readonly slug?: string | null;
+        readonly name?: string | null;
+        readonly owner?: GithubUser;
+    } | null;
+};
+export type GreptileScore = {
+    readonly value: number;
+    readonly scale: number;
+    readonly raw: string;
+};
+export type GreptileSignalSource = "api" | "github-review" | "github-check" | "changed-file-comment" | "issue-comment" | "review-thread" | "pr-body" | "pr-title";
+export type GreptileSignalVerdict = "approved" | "rejected" | "skipped" | "pending" | "failed" | "completed";
+export type GreptileSignalEvidence = {
+    readonly source: GreptileSignalSource;
+    readonly trusted: boolean;
+    readonly authorLogin?: string | null;
+    readonly reviewedSha?: string | null;
+    readonly current: boolean | null;
+    readonly stale: boolean;
+    readonly score?: GreptileScore | null;
+    readonly scores?: readonly GreptileScore[];
+    readonly explicitApproval?: boolean;
+    readonly verdict?: GreptileSignalVerdict | null;
+    readonly blocker?: boolean;
+    readonly actionable?: boolean;
+    readonly bodyExcerpt?: string;
+};
+export type GreptileApiSignalInput = {
+    readonly id?: string | null;
+    readonly body?: string | null;
+    readonly reviewedSha?: string | null;
+    readonly status?: string | null;
+};
+export type GreptileEvidence = {
+    readonly source: "api" | "github-review" | "github-check" | "github-comment" | "pr-body" | "combined" | "missing";
+    readonly currentHeadSha: string;
+    readonly reviewedSha?: string | null;
+    readonly fresh: boolean;
+    readonly completed: boolean;
+    readonly approved: boolean;
+    readonly score?: GreptileScore | null;
+    readonly explicitApproval?: boolean;
+    readonly blockers: readonly string[];
+    readonly unresolvedComments: readonly string[];
+    readonly rawBodies: readonly string[];
+    readonly signals: readonly GreptileSignalEvidence[];
+    readonly mapping: "score-5-of-5" | "explicit-approved" | "unproven" | "missing" | "stale";
+};
+export type PrReviewEvidence = {
+    readonly prUrl: string;
+    readonly prNumber: number;
+    readonly repoName: string;
+    readonly title: string;
+    readonly body: string;
+    readonly bodyEditorLogin?: string | null;
+    readonly bodyLastEditedAt?: string | null;
+    readonly headCommittedDate?: string | null;
+    readonly headSha: string;
+    readonly headRefName?: string | null;
+    readonly baseRefName?: string | null;
+    readonly state?: string | null;
+    readonly isDraft?: boolean | null;
+    readonly mergeable?: string | null;
+    readonly mergeStateStatus?: string | null;
+    readonly reviewDecision?: string | null;
+    readonly reviews: readonly GithubPullRequestReview[];
+    readonly reviewThreads: readonly GithubReviewThread[];
+    readonly changedFileReviewComments: readonly GithubReviewComment[];
+    readonly relevantIssueComments: readonly GithubIssueComment[];
+    readonly statusCheckRollup: readonly GithubStatusCheckRollupItem[];
+    readonly checkFailures: readonly string[];
+    readonly pendingChecks: readonly string[];
+    readonly readErrors: readonly string[];
+    readonly greptile: GreptileEvidence;
+};
+export type PrReviewCycleArtifacts = {
+    readonly root: string;
+    readonly prTitlePath: string;
+    readonly prBodyPath: string;
+    readonly prCommentsPath: string;
+    readonly reviewThreadsPath: string;
+    readonly reviewCommentsPath: string;
+    readonly checkRollupPath: string;
+    readonly greptileEvidencePath: string;
+    readonly mergeGateResultPath: string;
+    readonly steeringPromptPath: string;
+    readonly finalMergeGateResultPath?: string;
+};
+export type StrictPrMergeGateReasonCode = "read_error" | "missing_head_sha" | "ci_failed" | "check_pending" | "review_decision_blocking" | "review_thread_unresolved" | "greptile_missing" | "greptile_stale" | "greptile_pending" | "greptile_api_status_unknown" | "greptile_not_current_head" | "greptile_score_not_5" | "greptile_score_missing" | "greptile_mapping_unproven" | "greptile_blocker_text" | "greptile_unresolved_comment";
+export type StrictPrMergeGateReason = {
+    readonly code: StrictPrMergeGateReasonCode;
+    readonly reasonClass: "pending" | "reject";
+    readonly surface: "github" | "ci" | "review" | "greptile";
+    readonly suggestedAction: "wait" | "fix" | "ask_greptile" | "needs_attention";
+    readonly message: string;
+    readonly headSha?: string | null;
+    readonly reviewedSha?: string | null;
+};
+export type StrictPrMergeGateResult = {
+    readonly approved: boolean;
+    readonly pending: boolean;
+    readonly reasons: readonly string[];
+    readonly reasonDetails: readonly StrictPrMergeGateReason[];
+    readonly warnings: readonly string[];
+    readonly actionableFeedback: readonly string[];
+    readonly evidence: PrReviewEvidence;
+    readonly artifacts?: PrReviewCycleArtifacts;
+    readonly steeringPrompt: string;
+};
+export type StrictPrGreptileApiFetch = (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => ReturnType<typeof fetch>;
+export type StrictPrGreptileApiOptions = {
+    readonly enabled?: boolean;
+    readonly env?: Record<string, string | undefined>;
+    readonly fetch?: StrictPrGreptileApiFetch;
+};
+export type StrictPrMergeGateInput = {
+    readonly projectRoot: string;
+    readonly prUrl: string;
+    readonly taskId: string;
+    readonly runId: string;
+    readonly cycle: number;
+    readonly command: GitHubCommandRunner;
+    readonly artifactRoot?: string | null;
+    readonly allowedFailures?: readonly string[];
+    readonly apiSignals?: readonly GreptileApiSignalInput[];
+    readonly greptileApi?: StrictPrGreptileApiOptions;
+    readonly final?: boolean;
+    readonly requireGreptile?: boolean;
+};
+export type VerifyOutcome = {
+    approved: boolean;
+    localReasons: string[];
+    aiReasons: string[];
+    aiWarnings: string[];
+    aiVerdict: "APPROVE" | "REJECT" | "SKIP";
+    reviewFeedbackPath: string;
+    reviewStatePath: string;
+};
+/** Capability id the pr-review plugin registers its merge-head-SHA resolver under. */
+export declare const PR_MERGE_GATE_CAPABILITY_ID = "rig.mergeGate.resolveHeadSha";
+/** Pure input to the merge-head-SHA resolver: the gate result + target PR. */
+export type ResolveMergeHeadShaInput = {
+    readonly result: StrictPrMergeGateResult;
+    readonly prUrl: string;
+    /** Defaults to true at the impl; gate enforces Greptile freshness when set. */
+    readonly requireGreptile?: boolean;
+};
+/**
+ * The cohesive merge-gate seam the default lifecycle bundle depends on. Owned +
+ * provided by `@rig/pr-review-plugin` under {@link PR_MERGE_GATE_CAPABILITY_ID};
+ * `@rig/bundle-default-lifecycle` resolves it off the host instead of importing
+ * `@rig/pr-review-plugin`. Surfaces exactly the merge-gate operations the bundle
+ * uses (gate run + head-SHA resolution + the evidence-collection/evaluation
+ * primitives the verifier composes). Types only here — VOCAB, no behaviour.
+ */
+export interface PrMergeGateService {
+    /**
+     * Given an approved gate result + PR url, return the raw 40-char head SHA it
+     * is safe to merge (throws when not approved / not tied to head). Pure.
+     */
+    resolveHeadSha(input: ResolveMergeHeadShaInput): string;
+    /** Run the full strict merge gate (collect evidence + evaluate + artifacts). */
+    runGate(input: StrictPrMergeGateInput): Promise<StrictPrMergeGateResult>;
+    /** Collect the PR review evidence the gate evaluates (IO). */
+    collectEvidence(input: StrictPrMergeGateInput): Promise<PrReviewEvidence>;
+    /** Evaluate already-collected evidence into a gate decision (pure). */
+    evaluateGate(evidence: PrReviewEvidence, requireGreptile?: boolean): Omit<StrictPrMergeGateResult, "artifacts" | "steeringPrompt">;
+    /** Parse a Greptile review score from a review body (pure). */
+    parseGreptileScore(input: string): GreptileScore | null;
+    /** Strip HTML to plain text (pure). */
+    stripHtml(input: string): string;
+}
+/**
+ * Typed capability id, phantom-typed with {@link PrMergeGateService} so
+ * `defineCapability(PR_MERGE_GATE)` resolves with no cast leaking to callers.
+ * String value is {@link PR_MERGE_GATE_CAPABILITY_ID}.
+ */
+export declare const PR_MERGE_GATE: CapabilityId<PrMergeGateService>;

package/dist/src/control-plane-types.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/control-plane-types.ts
+var PR_MERGE_GATE_CAPABILITY_ID = "rig.mergeGate.resolveHeadSha";
+var PR_MERGE_GATE = makeCapabilityId(PR_MERGE_GATE_CAPABILITY_ID);
+export {
+  PR_MERGE_GATE_CAPABILITY_ID,
+  PR_MERGE_GATE
+};

package/dist/src/conversation.d.ts

@@ -0,0 +1,50 @@
+import { Schema } from "effect";
+export declare const EngineMessageRole: Schema.Literals<readonly ["user", "assistant", "system"]>;
+export type EngineMessageRole = typeof EngineMessageRole.Type;
+export declare const EngineMessageState: Schema.Literals<readonly ["streaming", "completed", "interrupted", "errored"]>;
+export type EngineMessageState = typeof EngineMessageState.Type;
+export declare const ConversationSummary: Schema.Struct<{
+    readonly id: Schema.brand<Schema.Trim, "ConversationId">;
+    readonly runId: Schema.brand<Schema.Trim, "RunId">;
+    readonly title: Schema.Trim;
+    readonly createdAt: Schema.String;
+    readonly updatedAt: Schema.String;
+}>;
+export type ConversationSummary = typeof ConversationSummary.Type;
+export declare const EngineMessage: Schema.Struct<{
+    readonly id: Schema.brand<Schema.Trim, "MessageId">;
+    readonly conversationId: Schema.brand<Schema.Trim, "ConversationId">;
+    readonly role: Schema.Literals<readonly ["user", "assistant", "system"]>;
+    readonly text: Schema.String;
+    readonly attachments: Schema.$Array<Schema.Unknown>;
+    readonly state: Schema.Literals<readonly ["streaming", "completed", "interrupted", "errored"]>;
+    readonly createdAt: Schema.String;
+    readonly completedAt: Schema.NullOr<Schema.String>;
+}>;
+export type EngineMessage = typeof EngineMessage.Type;
+export declare const EngineAction: Schema.Struct<{
+    readonly id: Schema.brand<Schema.Trim, "ActionId">;
+    readonly runId: Schema.brand<Schema.Trim, "RunId">;
+    readonly messageId: Schema.NullOr<Schema.brand<Schema.Trim, "MessageId">>;
+    readonly actionType: Schema.Trim;
+    readonly title: Schema.Trim;
+    readonly detail: Schema.NullOr<Schema.String>;
+    readonly state: Schema.Trim;
+    readonly payload: Schema.Unknown;
+    readonly startedAt: Schema.String;
+    readonly completedAt: Schema.NullOr<Schema.String>;
+}>;
+export type EngineAction = typeof EngineAction.Type;
+export declare const EngineLogTone: Schema.Literals<readonly ["thinking", "tool", "info", "error"]>;
+export type EngineLogTone = typeof EngineLogTone.Type;
+export declare const EngineRunLog: Schema.Struct<{
+    readonly id: Schema.Trim;
+    readonly runId: Schema.brand<Schema.Trim, "RunId">;
+    readonly title: Schema.Trim;
+    readonly detail: Schema.NullOr<Schema.String>;
+    readonly tone: Schema.Literals<readonly ["thinking", "tool", "info", "error"]>;
+    readonly status: Schema.NullOr<Schema.Trim>;
+    readonly payload: Schema.Unknown;
+    readonly createdAt: Schema.String;
+}>;
+export type EngineRunLog = typeof EngineRunLog.Type;

package/dist/src/conversation.js

@@ -16,6 +16,9 @@ var WorkspaceId = makeEntityId("WorkspaceId");
 var GraphId = makeEntityId("GraphId");
 var TaskId = makeEntityId("TaskId");
 var RunId = makeEntityId("RunId");
+var SafePathSegment = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/)).pipe(Schema.brand("SafePathSegment"));
+var SafeRunId = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/)).pipe(Schema.brand("SafeRunId"));
+var SafeGitRefComponent = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/)).pipe(Schema.brand("SafeGitRefComponent"));
 var EngineRuntimeId = makeEntityId("EngineRuntimeId");
 var ConversationId = makeEntityId("ConversationId");
 var ActionId = makeEntityId("ActionId");

package/dist/src/dependency-preflight.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The `workspace.dependency-preflight` capability seam.
+ *
+ * Pure capability VOCAB (no impl). The init/setup plugin (@rig/init-plugin)
+ * PROVIDES the concrete service — it mutates `package.json` to pin the project's
+ * `@rig/*` config deps and runs the package manager's install — and the CLI seed
+ * (`packages/cli/bin/rig.ts`) RESOLVES it by id off a plugin host built from the
+ * embedded standard plugins, invoking it only on the rig.config.ts power-path
+ * fallback (a code config present that the project-binary build did not handle).
+ *
+ * The heavy install/mutate impl therefore lives in the setup plugin, NOT in a
+ * CLI seed module on the hot path: the seed neither imports nor bundles it
+ * eagerly — it is reached purely through this typed seam.
+ */
+import type { CapabilityId } from "./capability-id";
+/** Inputs the CLI seed hands the preflight. The CLI owns version detection (it
+ *  reads its OWN installed version), so it passes the resolved values in rather
+ *  than the floor library reaching back into CLI-specific version resolution. */
+export type RigConfigDependencyPreflightInput = {
+    /** Project root whose `package.json` / config deps are reconciled. */
+    readonly projectRoot: string;
+    /** The CLI's own resolved installed version (drives the `@rig/*` dep pin). */
+    readonly installedCliVersion: string;
+    /** Whether {@link installedCliVersion} is a published (non source/dev) version;
+     *  when false the deps pin to `latest`. */
+    readonly isInstalledCliVersionPublished: boolean;
+};
+/** Outcome of a dependency preflight pass. */
+export type RigConfigDependencyPreflightResult = {
+    readonly rewroteManifest: boolean;
+    readonly ranInstall: boolean;
+    readonly command: string | null;
+    readonly version: string;
+};
+/** The dependency-preflight service the setup plugin provides and the CLI seed
+ *  resolves by id off a host. */
+export interface RigConfigDependencyPreflightService {
+    ensureInstalled(input: RigConfigDependencyPreflightInput): RigConfigDependencyPreflightResult;
+}
+/** The capability id string the setup plugin provides and the CLI seed resolves. */
+export declare const DEPENDENCY_PREFLIGHT_CAPABILITY_ID = "workspace.dependency-preflight";
+/** The typed capability id, phantom-typed with {@link RigConfigDependencyPreflightService}. */
+export declare const DEPENDENCY_PREFLIGHT_CAPABILITY: CapabilityId<RigConfigDependencyPreflightService>;

package/dist/src/dependency-preflight.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/dependency-preflight.ts
+var DEPENDENCY_PREFLIGHT_CAPABILITY_ID = "workspace.dependency-preflight";
+var DEPENDENCY_PREFLIGHT_CAPABILITY = makeCapabilityId(DEPENDENCY_PREFLIGHT_CAPABILITY_ID);
+export {
+  DEPENDENCY_PREFLIGHT_CAPABILITY_ID,
+  DEPENDENCY_PREFLIGHT_CAPABILITY
+};

package/dist/src/doctor.d.ts

@@ -0,0 +1,90 @@
+/**
+ * doctor.ts — pure diagnostic vocabulary for the doctor product domain.
+ *
+ * The diagnostic implementation (toolchain probes, rig.config loadability,
+ * GitHub auth/permission checks, Pi/run/relay discovery, remediation copy)
+ * lives in @rig/doctor-plugin and is resolved by substrate consumers (CLI
+ * surface, rig-extension) through the typed port in
+ * `@rig/runtime/control-plane/doctor-service-port` under
+ * {@link DOCTOR_RUNNER_CAPABILITY_ID}. This file holds ONLY the pure types and
+ * pure helpers shared by producer and consumers — no IO, no plugin imports.
+ */
+import type { CapabilityId } from "./capability-id";
+/** The capability id the doctor plugin registers its runner under. */
+export declare const DOCTOR_RUNNER_CAPABILITY_ID = "doctor.runner";
+export type DoctorStatus = "pass" | "warn" | "fail";
+export type DoctorLevel = "ok" | "warn" | "fail";
+export type DoctorCheck = {
+    readonly id?: string;
+    readonly label: string;
+    readonly status?: DoctorStatus;
+    readonly level?: DoctorLevel;
+    readonly detail?: string;
+    readonly remediation?: string;
+};
+/**
+ * Structural mirror of the runtime's `RigIdentityContext` (in
+ * `@rig/runtime/control-plane/identity`). The diagnostic runner reads the
+ * GitHub/session identity off this context; the field references a runtime
+ * shape, so — exactly like memory's `MemoryCommandEventSink` — it is typed here
+ * as a minimal contracts-owned interface carrying only the structure the runner
+ * needs. The runtime's `RigIdentityContext` is structurally identical and so
+ * flows in/out without a cast, keeping the contract free of any runtime import.
+ */
+export interface DoctorIdentityContext {
+    readonly sessionManager: {
+        getCwd(): string;
+        getSessionId(): string;
+        getBranch(): readonly {
+            type: string;
+            customType?: string;
+            data?: unknown;
+        }[];
+    };
+    readonly modelRegistry?: {
+        readonly authStorage?: {
+            getOAuthAccountIdentity?: (provider: string, sessionId?: string) => unknown;
+        };
+    };
+}
+/**
+ * Options the substrate passes through to the diagnostic runner. The function
+ * fields are typed loosely (the consumers only read `.length`/labels); the
+ * plugin impl supplies concrete client-backed defaults. Keeping these signatures
+ * free of @rig/client types keeps the contract (and runtime) decoupled from
+ * client.
+ */
+export type RunDoctorChecksOptions = {
+    readonly projectRoot: string;
+    readonly requestJson?: (pathname: string, init?: RequestInit) => Promise<unknown>;
+    readonly piChecks?: () => Promise<readonly {
+        ok: boolean;
+        label: string;
+        detail?: string;
+        hint?: string;
+    }[]>;
+    readonly which?: (binary: string) => string | null;
+    readonly bunVersion?: string;
+    readonly loadConfig?: (projectRoot: string) => Promise<unknown>;
+    readonly onProgress?: (label: string) => void;
+    readonly identityContext?: DoctorIdentityContext;
+    readonly listRuns?: (projectRoot: string) => Promise<readonly unknown[]>;
+    readonly listPlacements?: (projectRoot: string) => readonly unknown[];
+};
+/**
+ * The cohesive diagnostic operation the substrate depends on. This is pure
+ * capability VOCAB: `@rig/doctor-plugin` provides a concrete impl (statically
+ * checked against this interface via `DoctorCap.provide`), and the substrate
+ * only ever sees this contract — resolved by id off a plugin host with no
+ * `as unknown as` at any call site.
+ */
+export interface DoctorService {
+    runDoctorChecks(options: RunDoctorChecksOptions): Promise<DoctorCheck[]>;
+}
+/**
+ * The typed capability id the doctor plugin provides and consumers require.
+ * Phantom-typed with {@link DoctorService} so `DoctorCap.require(host)` returns
+ * a `DoctorService` with no cast leaking to callers. Its string value is
+ * {@link DOCTOR_RUNNER_CAPABILITY_ID}, so it indexes the same host entry.
+ */
+export declare const DOCTOR: CapabilityId<DoctorService>;

package/dist/src/doctor.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/doctor.ts
+var DOCTOR_RUNNER_CAPABILITY_ID = "doctor.runner";
+var DOCTOR = makeCapabilityId(DOCTOR_RUNNER_CAPABILITY_ID);
+export {
+  DOCTOR_RUNNER_CAPABILITY_ID,
+  DOCTOR
+};

package/dist/src/drift.d.ts

@@ -0,0 +1,28 @@
+import { Schema } from "effect";
+export declare const DriftKind: Schema.Literals<readonly ["deleted-reference", "stale-anchor", "semantic-mismatch", "issue-mismatch"]>;
+export type DriftKind = typeof DriftKind.Type;
+export declare const DriftConfidence: Schema.Literals<readonly ["high", "medium", "low"]>;
+export type DriftConfidence = typeof DriftConfidence.Type;
+export declare const DriftFinding: Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["deleted-reference", "stale-anchor", "semantic-mismatch", "issue-mismatch"]>;
+    readonly docPath: Schema.Trim;
+    readonly line: Schema.NullOr<Schema.Int>;
+    readonly reference: Schema.NullOr<Schema.Trim>;
+    readonly detail: Schema.String;
+    readonly confidence: Schema.Literals<readonly ["high", "medium", "low"]>;
+}>;
+export type DriftFinding = typeof DriftFinding.Type;
+export declare const DriftReport: Schema.Struct<{
+    readonly generatedAt: Schema.String;
+    readonly scanned: Schema.Int;
+    readonly degraded: Schema.Boolean;
+    readonly findings: Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["deleted-reference", "stale-anchor", "semantic-mismatch", "issue-mismatch"]>;
+        readonly docPath: Schema.Trim;
+        readonly line: Schema.NullOr<Schema.Int>;
+        readonly reference: Schema.NullOr<Schema.Trim>;
+        readonly detail: Schema.String;
+        readonly confidence: Schema.Literals<readonly ["high", "medium", "low"]>;
+    }>>;
+}>;
+export type DriftReport = typeof DriftReport.Type;

package/dist/src/drift.js

@@ -0,0 +1,69 @@
+// @bun
+// packages/contracts/src/drift.ts
+import { Schema as Schema2 } from "effect";
+
+// packages/contracts/src/baseSchemas.ts
+import { Schema } from "effect";
+var TrimmedString = Schema.Trim;
+var TrimmedNonEmptyString = TrimmedString.check(Schema.isNonEmpty());
+var NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+var PositiveInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+var IsoDateTime = Schema.String;
+var makeEntityId = (brand) => TrimmedNonEmptyString.pipe(Schema.brand(brand));
+var ThreadId = makeEntityId("ThreadId");
+var ProjectId = makeEntityId("ProjectId");
+var WorkspaceId = makeEntityId("WorkspaceId");
+var GraphId = makeEntityId("GraphId");
+var TaskId = makeEntityId("TaskId");
+var RunId = makeEntityId("RunId");
+var SafePathSegment = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/)).pipe(Schema.brand("SafePathSegment"));
+var SafeRunId = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/)).pipe(Schema.brand("SafeRunId"));
+var SafeGitRefComponent = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/)).pipe(Schema.brand("SafeGitRefComponent"));
+var EngineRuntimeId = makeEntityId("EngineRuntimeId");
+var ConversationId = makeEntityId("ConversationId");
+var ActionId = makeEntityId("ActionId");
+var ArtifactId = makeEntityId("ArtifactId");
+var WorktreeId = makeEntityId("WorktreeId");
+var ValidationResultId = makeEntityId("ValidationResultId");
+var ReviewResultId = makeEntityId("ReviewResultId");
+var CommandId = makeEntityId("CommandId");
+var EventId = makeEntityId("EventId");
+var MessageId = makeEntityId("MessageId");
+var TurnId = makeEntityId("TurnId");
+var ProviderItemId = makeEntityId("ProviderItemId");
+var RuntimeSessionId = makeEntityId("RuntimeSessionId");
+var RuntimeItemId = makeEntityId("RuntimeItemId");
+var RuntimeRequestId = makeEntityId("RuntimeRequestId");
+var RuntimeTaskId = makeEntityId("RuntimeTaskId");
+var ApprovalRequestId = makeEntityId("ApprovalRequestId");
+var CheckpointRef = makeEntityId("CheckpointRef");
+var RemoteEndpointId = makeEntityId("RemoteEndpointId");
+
+// packages/contracts/src/drift.ts
+var DriftKind = Schema2.Literals([
+  "deleted-reference",
+  "stale-anchor",
+  "semantic-mismatch",
+  "issue-mismatch"
+]);
+var DriftConfidence = Schema2.Literals(["high", "medium", "low"]);
+var DriftFinding = Schema2.Struct({
+  kind: DriftKind,
+  docPath: TrimmedNonEmptyString,
+  line: Schema2.NullOr(PositiveInt),
+  reference: Schema2.NullOr(TrimmedNonEmptyString),
+  detail: Schema2.String,
+  confidence: DriftConfidence
+});
+var DriftReport = Schema2.Struct({
+  generatedAt: IsoDateTime,
+  scanned: NonNegativeInt,
+  degraded: Schema2.Boolean,
+  findings: Schema2.Array(DriftFinding)
+});
+export {
+  DriftReport,
+  DriftKind,
+  DriftFinding,
+  DriftConfidence
+};