@h-rig/contracts 0.0.0-e2e-live.20260630085347

package/dist/src/github.d.ts

@@ -0,0 +1,295 @@
+/**
+ * Pure GitHub-provider contract types.
+ *
+ * This is the neutral home for the GitHub SCM-provider data model so that the
+ * @rig/github-provider-plugin (which owns the implementation), the
+ * @rig/task-sources-plugin (which consumes the credential-provider abstraction),
+ * and any future dumb runtime substrate can all reference the same vocabulary
+ * without a substrate->plugin import cycle. These types carry no behaviour and
+ * import nothing — exactly like `memory.ts` / `lifecycle-capabilities.ts`.
+ *
+ * The plugin registers its executable GitHub-provider service under
+ * {@link GITHUB_PROVIDER_CAPABILITY_ID} on `contributes.capabilities[].run`; a
+ * dumb substrate consumer would resolve it by id from a plugin host built from
+ * the project's rig.config via a typed port — the same seam shape proven by
+ * the memory/lifecycle capability ports. (Today the only substrate-facing
+ * GitHub primitive — reading a token from an env-pointed state file — stays in
+ * @rig/runtime/control-plane/github/token-env as a dumb reader; the policy that
+ * produces that token lives in this plugin.)
+ */
+import type { CapabilityId } from "./capability-id";
+/** Capability id the GitHub-provider plugin registers its service factory under. */
+export declare const GITHUB_PROVIDER_CAPABILITY_ID = "github.provider";
+export type GitHubCredentialPurpose = "selected-repo" | "admin-fallback";
+export type GitHubCredentialSource = "signed-in-user" | "host-admin-fallback";
+export type GitHubCredentialProviderOptions = {
+    /**
+     * Session-scoped tokens keyed as:
+     * `user:<userId>|repo:<owner>/<repo>|workspace:<workspaceId>`.
+     * This intentionally models the app/session auth boundary; host tokens are
+     * not used for normal selected-repo operations.
+     */
+    sessionTokens?: Readonly<Record<string, string>>;
+    hostToken?: string | null;
+};
+export type ResolveGitHubTokenInput = {
+    owner: string;
+    repo: string;
+    workspaceId: string;
+    userId?: string;
+    purpose: GitHubCredentialPurpose;
+};
+export type ResolvedGitHubToken = {
+    token: string;
+    source: GitHubCredentialSource;
+};
+export interface GitHubCredentialProvider {
+    resolveGitHubToken(input: ResolveGitHubTokenInput): Promise<ResolvedGitHubToken>;
+}
+/** Options the state-file-backed credential provider accepts. */
+export type GitHubStateCredentialProviderOptions = {
+    stateFile?: string;
+    stateDir?: string;
+};
+export type GitHubAuthStatus = {
+    readonly signedIn: boolean;
+    readonly login: string | null;
+    readonly userId: string | null;
+    readonly scopes: readonly string[];
+    readonly selectedRepo: string | null;
+    readonly oauthConfigured: boolean;
+    readonly tokenSource: "oauth-device" | "manual-token" | "env" | null;
+};
+export type GitHubUserInfo = {
+    readonly login: string;
+    readonly id: string;
+    readonly scopes?: readonly string[];
+};
+export type GitHubRepositoryProbe = {
+    readonly ok: boolean;
+    readonly owner: string;
+    readonly repo: string;
+    readonly status: number;
+    readonly authenticated: boolean;
+    readonly authenticationRequired: boolean;
+    readonly fullName: string | null;
+    readonly private: boolean | null;
+    readonly message: string;
+    readonly scopes: readonly string[];
+};
+export interface GitHubProjectSummary {
+    id: string;
+    number: number;
+    title: string;
+    url?: string;
+}
+export interface GitHubProjectStatusField {
+    id: string;
+    name: string;
+    options: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+export type GitHubDeviceFlowPending = {
+    readonly pollId: string;
+    readonly deviceCode: string;
+    readonly expiresAt: string;
+    readonly intervalSeconds: number;
+};
+export type GitHubAuthStore = {
+    readonly stateFile: string;
+    readonly status: (options?: {
+        oauthConfigured?: boolean;
+    }) => GitHubAuthStatus;
+    readonly readToken: () => string | null;
+    readonly saveToken: (input: {
+        readonly token: string;
+        readonly tokenSource: "oauth-device" | "manual-token";
+        readonly login?: string | null;
+        readonly userId?: string | null;
+        readonly scopes?: readonly string[];
+        readonly selectedRepo?: string | null;
+    }) => void;
+    readonly createApiSession: () => {
+        token: string;
+        login: string | null;
+        userId: string | null;
+    };
+    readonly readApiSession: (token: string) => {
+        login: string | null;
+        userId: string | null;
+    } | null;
+    readonly copyToProjectRoot: (projectRoot: string) => void;
+    readonly copyToLocalProjectRoot: (projectRoot: string) => void;
+    readonly savePendingDevice: (input: GitHubDeviceFlowPending) => void;
+    readonly saveSelectedRepo: (selectedRepo: string | null) => void;
+    readonly readPendingDevice: (pollId: string) => GitHubDeviceFlowPending | null;
+    readonly clearPendingDevice: (pollId?: string) => void;
+};
+export type GitHubFormPostResult = {
+    readonly status: number;
+    readonly payload: Record<string, unknown>;
+};
+export type GitHubFormPoster = (endpoint: string, body: Record<string, string>) => Promise<GitHubFormPostResult>;
+export type GitHubUserFetcher = (token: string) => Promise<GitHubUserInfo>;
+export type GitHubGraphQLFetch = (query: string, variables: Record<string, unknown>, token: string) => Promise<unknown>;
+export type GitHubTokenSaveResult = {
+    readonly ok: true;
+} & GitHubAuthStatus;
+export type GitHubDeviceFlowStartResult = {
+    readonly ok: true;
+    readonly pollId: string;
+    readonly userCode: string | null;
+    readonly verificationUri: string | null;
+    readonly expiresIn: number;
+    readonly intervalSeconds: number;
+};
+export type GitHubDeviceFlowPollResult = ({
+    readonly ok: true;
+    readonly status: "signed-in";
+} & GitHubAuthStatus) | {
+    readonly ok: false;
+    readonly status: "expired";
+    readonly error: string;
+} | {
+    readonly ok: false;
+    readonly status: "pending";
+    readonly intervalSeconds: number;
+} | {
+    readonly ok: false;
+    readonly status: "slow-down";
+    readonly intervalSeconds: number;
+} | {
+    readonly ok: false;
+    readonly status: "error";
+    readonly error: string;
+};
+export type GitHubRepoPermissionsResult = {
+    readonly ok: false;
+    readonly signedIn: false;
+    readonly canOpenPullRequest: false;
+    readonly reason: "not-authenticated";
+} | {
+    readonly ok: true;
+    readonly signedIn: true;
+    readonly login: string | null;
+    readonly scopes: readonly string[];
+    readonly canOpenPullRequest: boolean;
+    readonly pullRequests: boolean;
+    readonly push: boolean;
+    readonly reason: "stored-token" | "token-scope-unverified";
+};
+/**
+ * The executable surface the GitHub-provider capability `run()` returns. The
+ * provider owns the GitHub implementation; sibling plugins resolve this service
+ * from the configured project host instead of importing the provider package.
+ */
+export interface GitHubProviderService {
+    detectGhLogin(input?: {
+        readonly projectRoot?: string | undefined;
+    }): string | null;
+    readGhAuthToken(input?: {
+        readonly projectRoot?: string | undefined;
+    }): string;
+    refreshGhProjectScopesAndReadToken(input?: {
+        readonly projectRoot?: string | undefined;
+        readonly scopes?: readonly string[] | undefined;
+    }): string | null;
+    createCredentialProvider(options?: GitHubCredentialProviderOptions): GitHubCredentialProvider;
+    createEnvGitHubCredentialProvider(): GitHubCredentialProvider;
+    createStateGitHubCredentialProvider(options?: GitHubStateCredentialProviderOptions): GitHubCredentialProvider;
+    createGitHubAuthStore(projectRoot: string): GitHubAuthStore;
+    resolveGitHubAuthStatus(input: {
+        readonly projectRoot: string;
+        readonly oauthConfigured?: boolean;
+    }): GitHubAuthStatus;
+    saveGitHubTokenForProject(input: {
+        readonly projectRoot: string;
+        readonly token: string;
+        readonly tokenSource?: "oauth-device" | "manual-token";
+        readonly selectedRepo?: string | null;
+        readonly fetchUser?: GitHubUserFetcher;
+    }): Promise<GitHubTokenSaveResult>;
+    beginGitHubDeviceFlow(input: {
+        readonly projectRoot: string;
+        readonly clientId: string;
+        readonly scope?: string;
+        readonly selectedRepo?: string | null;
+        readonly postForm?: GitHubFormPoster;
+    }): Promise<GitHubDeviceFlowStartResult>;
+    pollGitHubDeviceFlow(input: {
+        readonly projectRoot: string;
+        readonly clientId: string;
+        readonly pollId: string;
+        readonly selectedRepo?: string | null;
+        readonly postForm?: GitHubFormPoster;
+        readonly fetchUser?: GitHubUserFetcher;
+    }): Promise<GitHubDeviceFlowPollResult>;
+    checkGitHubRepoPermissions(input: {
+        readonly projectRoot: string;
+        readonly oauthConfigured?: boolean;
+    }): GitHubRepoPermissionsResult;
+    probeGitHubRepository(input: {
+        readonly owner: string;
+        readonly repo: string;
+        readonly token: string | null;
+        readonly scopes: readonly string[];
+        readonly fetchRepository?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    }): Promise<GitHubRepositoryProbe>;
+    listGitHubProjects(input: {
+        readonly owner: string;
+        readonly token: string;
+        readonly first?: number;
+        readonly fetchGraphQL?: GitHubGraphQLFetch;
+    }): Promise<GitHubProjectSummary[]>;
+    resolveProjectStatusField(input: {
+        readonly projectId: string;
+        readonly token: string;
+        readonly fetchGraphQL?: GitHubGraphQLFetch;
+    }): Promise<GitHubProjectStatusField>;
+}
+/** The capability `run` shape the plugin registers: a zero-arg service factory. */
+export type GitHubProviderServiceRun = () => GitHubProviderService;
+/**
+ * Typed capability id, phantom-typed with {@link GitHubProviderService} so
+ * consumers (task-sources/doctor/init) resolve it off the host with no cast.
+ * String value is {@link GITHUB_PROVIDER_CAPABILITY_ID}.
+ */
+export declare const GITHUB_PROVIDER: CapabilityId<GitHubProviderService>;
+/** Capability id the issue-triage provider registers its runner under. */
+export declare const ISSUE_TRIAGE_CAPABILITY_ID = "cap:issue-triage";
+/** Pure input to a triage pass: which project + an optional reason label. */
+export type IssueTriageInput = {
+    readonly projectRoot: string;
+    readonly reason?: string;
+};
+/**
+ * Pure summary of a triage pass. Contracts-owned mirror of the plugin's
+ * `IssueAnalysisTriageRunResult` so substrate consumers read the outcome
+ * without importing the plugin. Structurally compatible with the impl result.
+ */
+export type IssueTriageResult = {
+    readonly ok: true;
+    readonly enabled: boolean;
+    readonly reason: string;
+    readonly sourceId: string | null;
+    readonly sourceKind: string | null;
+    readonly analyzedIssues: number;
+    readonly metadataPatches: number;
+    readonly labelsAdded: number;
+    readonly labelsRemoved: number;
+    readonly generatedIssues: number;
+    readonly writeBackRefreshes: number;
+    readonly refreshedIssueCount: number | null;
+    readonly skippedReason?: "no-config" | "disabled";
+};
+/** The cohesive triage operation the CLI surface depends on. Async (does IO). */
+export interface IssueTriageService {
+    runTriage(input: IssueTriageInput): Promise<IssueTriageResult>;
+}
+/**
+ * Typed capability id, phantom-typed with {@link IssueTriageService}. String
+ * value is {@link ISSUE_TRIAGE_CAPABILITY_ID}.
+ */
+export declare const ISSUE_TRIAGE: CapabilityId<IssueTriageService>;

package/dist/src/github.js

@@ -0,0 +1,17 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/github.ts
+var GITHUB_PROVIDER_CAPABILITY_ID = "github.provider";
+var GITHUB_PROVIDER = makeCapabilityId(GITHUB_PROVIDER_CAPABILITY_ID);
+var ISSUE_TRIAGE_CAPABILITY_ID = "cap:issue-triage";
+var ISSUE_TRIAGE = makeCapabilityId(ISSUE_TRIAGE_CAPABILITY_ID);
+export {
+  ISSUE_TRIAGE_CAPABILITY_ID,
+  ISSUE_TRIAGE,
+  GITHUB_PROVIDER_CAPABILITY_ID,
+  GITHUB_PROVIDER
+};

package/dist/src/graph.d.ts

@@ -0,0 +1,360 @@
+import { Schema } from "effect";
+import type { CapabilityId } from "./capability-id";
+export declare const TaskStatus: Schema.Literals<readonly ["draft", "open", "ready", "queued", "running", "in_progress", "under_review", "blocked", "unknown", "completed", "failed", "cancelled", "closed"]>;
+export type TaskStatus = typeof TaskStatus.Type;
+export declare const GraphSummary: Schema.Struct<{
+    readonly id: Schema.brand<Schema.Trim, "GraphId">;
+    readonly workspaceId: Schema.brand<Schema.Trim, "WorkspaceId">;
+    readonly title: Schema.Trim;
+    readonly description: Schema.NullOr<Schema.String>;
+    readonly createdAt: Schema.String;
+    readonly updatedAt: Schema.String;
+}>;
+export type GraphSummary = typeof GraphSummary.Type;
+export declare const TaskSummary: Schema.Struct<{
+    readonly id: Schema.brand<Schema.Trim, "TaskId">;
+    readonly workspaceId: Schema.brand<Schema.Trim, "WorkspaceId">;
+    readonly graphId: Schema.NullOr<Schema.brand<Schema.Trim, "GraphId">>;
+    readonly externalId: Schema.NullOr<Schema.Trim>;
+    readonly title: Schema.Trim;
+    readonly description: Schema.String;
+    readonly status: Schema.Literals<readonly ["draft", "open", "ready", "queued", "running", "in_progress", "under_review", "blocked", "unknown", "completed", "failed", "cancelled", "closed"]>;
+    readonly priority: Schema.NullOr<Schema.Int>;
+    readonly role: Schema.NullOr<Schema.Trim>;
+    readonly scope: Schema.$Array<Schema.Trim>;
+    readonly validationKeys: Schema.$Array<Schema.Trim>;
+    readonly sourceIssueId: Schema.optional<Schema.NullOr<Schema.Trim>>;
+    readonly dependencies: Schema.optional<Schema.$Array<Schema.Trim>>;
+    readonly parentChildDeps: Schema.optional<Schema.$Array<Schema.Trim>>;
+    readonly metadata: Schema.Unknown;
+    readonly createdAt: Schema.String;
+    readonly updatedAt: Schema.String;
+}>;
+export type TaskSummary = typeof TaskSummary.Type;
+export declare const QueueEntry: Schema.Struct<{
+    readonly taskId: Schema.brand<Schema.Trim, "TaskId">;
+    readonly score: Schema.Int;
+    readonly unblockCount: Schema.Int;
+    readonly position: Schema.Int;
+}>;
+export type QueueEntry = typeof QueueEntry.Type;
+export declare const DependencyEdgeType: Schema.Literals<readonly ["blocks", "parent-child", "related"]>;
+export type DependencyEdgeType = typeof DependencyEdgeType.Type;
+export declare const DependencyEdge: Schema.Struct<{
+    readonly fromTaskId: Schema.brand<Schema.Trim, "TaskId">;
+    readonly toTaskId: Schema.brand<Schema.Trim, "TaskId">;
+    readonly type: Schema.Literals<readonly ["blocks", "parent-child", "related"]>;
+}>;
+export type DependencyEdge = typeof DependencyEdge.Type;
+export declare const BlockerClass: Schema.Literals<readonly ["not-blocked", "task-blocked", "human-decision", "human-approval", "external-input", "unknown"]>;
+export type BlockerClass = typeof BlockerClass.Type;
+export declare const ActionRiskTier: Schema.Literals<readonly ["t1-read", "t2-reversible", "t3-external", "t4-irreversible"]>;
+export type ActionRiskTier = typeof ActionRiskTier.Type;
+export declare const BlockerClassification: Schema.Struct<{
+    readonly taskId: Schema.brand<Schema.Trim, "TaskId">;
+    readonly blockerClass: Schema.Literals<readonly ["not-blocked", "task-blocked", "human-decision", "human-approval", "external-input", "unknown"]>;
+    readonly actionRiskTier: Schema.NullOr<Schema.Literals<readonly ["t1-read", "t2-reversible", "t3-external", "t4-irreversible"]>>;
+    readonly rationale: Schema.String;
+    readonly source: Schema.Literals<readonly ["elimination", "label", "status", "llm"]>;
+    readonly autoApplied: Schema.Boolean;
+}>;
+export type BlockerClassification = typeof BlockerClassification.Type;
+export declare const DependencyNode: Schema.Struct<{
+    readonly taskId: Schema.brand<Schema.Trim, "TaskId">;
+    readonly title: Schema.Trim;
+    readonly status: Schema.Literals<readonly ["draft", "open", "ready", "queued", "running", "in_progress", "under_review", "blocked", "unknown", "completed", "failed", "cancelled", "closed"]>;
+    readonly priority: Schema.NullOr<Schema.Int>;
+    readonly assignee: Schema.NullOr<Schema.Trim>;
+    readonly blockedBy: Schema.$Array<Schema.brand<Schema.Trim, "TaskId">>;
+    readonly blocks: Schema.$Array<Schema.brand<Schema.Trim, "TaskId">>;
+    readonly blockingDepth: Schema.Int;
+    readonly blockerClass: Schema.NullOr<Schema.Literals<readonly ["not-blocked", "task-blocked", "human-decision", "human-approval", "external-input", "unknown"]>>;
+    readonly actionRiskTier: Schema.NullOr<Schema.Literals<readonly ["t1-read", "t2-reversible", "t3-external", "t4-irreversible"]>>;
+    readonly epicKey: Schema.NullOr<Schema.Trim>;
+    readonly groupKey: Schema.optional<Schema.NullOr<Schema.Trim>>;
+    readonly externalId: Schema.optional<Schema.NullOr<Schema.Trim>>;
+    readonly sourceIssueId: Schema.optional<Schema.NullOr<Schema.Trim>>;
+    readonly scope: Schema.optional<Schema.$Array<Schema.Trim>>;
+    readonly validationKeys: Schema.optional<Schema.$Array<Schema.Trim>>;
+}>;
+export type DependencyNode = typeof DependencyNode.Type;
+export declare const TaskGraphLane: Schema.Struct<{
+    readonly key: Schema.Trim;
+    readonly label: Schema.Trim;
+    readonly rowIndex: Schema.Int;
+    readonly x: Schema.Number;
+    readonly y: Schema.Number;
+    readonly width: Schema.Int;
+    readonly height: Schema.Int;
+    readonly color: Schema.String;
+    readonly taskCount: Schema.Int;
+}>;
+export type TaskGraphLane = typeof TaskGraphLane.Type;
+export declare const TaskGraphStage: Schema.Struct<{
+    readonly index: Schema.Int;
+    readonly label: Schema.Trim;
+    readonly x: Schema.Number;
+    readonly width: Schema.Int;
+}>;
+export type TaskGraphStage = typeof TaskGraphStage.Type;
+export declare const TaskGraphNode: Schema.Struct<{
+    readonly id: Schema.Trim;
+    readonly taskId: Schema.brand<Schema.Trim, "TaskId">;
+    readonly task: Schema.optional<Schema.Struct<{
+        readonly id: Schema.brand<Schema.Trim, "TaskId">;
+        readonly workspaceId: Schema.brand<Schema.Trim, "WorkspaceId">;
+        readonly graphId: Schema.NullOr<Schema.brand<Schema.Trim, "GraphId">>;
+        readonly externalId: Schema.NullOr<Schema.Trim>;
+        readonly title: Schema.Trim;
+        readonly description: Schema.String;
+        readonly status: Schema.Literals<readonly ["draft", "open", "ready", "queued", "running", "in_progress", "under_review", "blocked", "unknown", "completed", "failed", "cancelled", "closed"]>;
+        readonly priority: Schema.NullOr<Schema.Int>;
+        readonly role: Schema.NullOr<Schema.Trim>;
+        readonly scope: Schema.$Array<Schema.Trim>;
+        readonly validationKeys: Schema.$Array<Schema.Trim>;
+        readonly sourceIssueId: Schema.optional<Schema.NullOr<Schema.Trim>>;
+        readonly dependencies: Schema.optional<Schema.$Array<Schema.Trim>>;
+        readonly parentChildDeps: Schema.optional<Schema.$Array<Schema.Trim>>;
+        readonly metadata: Schema.Unknown;
+        readonly createdAt: Schema.String;
+        readonly updatedAt: Schema.String;
+    }>>;
+    readonly rowKey: Schema.Trim;
+    readonly rowLabel: Schema.Trim;
+    readonly rowIndex: Schema.Int;
+    readonly stage: Schema.Int;
+    readonly x: Schema.Number;
+    readonly y: Schema.Number;
+    readonly width: Schema.Int;
+    readonly height: Schema.Int;
+    readonly color: Schema.optional<Schema.String>;
+    readonly taskCode: Schema.optional<Schema.NullOr<Schema.String>>;
+    readonly strippedTitle: Schema.optional<Schema.String>;
+    readonly depsIn: Schema.optional<Schema.Int>;
+    readonly depsOut: Schema.optional<Schema.Int>;
+    readonly runCount: Schema.optional<Schema.Int>;
+    readonly hasApprovals: Schema.optional<Schema.Boolean>;
+    readonly hasPendingUserInput: Schema.optional<Schema.Boolean>;
+    readonly hasRejectedReview: Schema.optional<Schema.Boolean>;
+    readonly hasFailedValidations: Schema.optional<Schema.Boolean>;
+    readonly artifactCount: Schema.optional<Schema.Int>;
+}>;
+export type TaskGraphNode = typeof TaskGraphNode.Type;
+export declare const TaskGraphEdge: Schema.Struct<{
+    readonly id: Schema.Trim;
+    readonly sourceId: Schema.Trim;
+    readonly targetId: Schema.Trim;
+    readonly color: Schema.String;
+    readonly kind: Schema.Literals<readonly ["blocking", "parent-child"]>;
+}>;
+export type TaskGraphEdge = typeof TaskGraphEdge.Type;
+export declare const TaskGraphLayout: Schema.Struct<{
+    readonly lanes: Schema.$Array<Schema.Struct<{
+        readonly key: Schema.Trim;
+        readonly label: Schema.Trim;
+        readonly rowIndex: Schema.Int;
+        readonly x: Schema.Number;
+        readonly y: Schema.Number;
+        readonly width: Schema.Int;
+        readonly height: Schema.Int;
+        readonly color: Schema.String;
+        readonly taskCount: Schema.Int;
+    }>>;
+    readonly stages: Schema.$Array<Schema.Struct<{
+        readonly index: Schema.Int;
+        readonly label: Schema.Trim;
+        readonly x: Schema.Number;
+        readonly width: Schema.Int;
+    }>>;
+    readonly nodes: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.Trim;
+        readonly taskId: Schema.brand<Schema.Trim, "TaskId">;
+        readonly task: Schema.optional<Schema.Struct<{
+            readonly id: Schema.brand<Schema.Trim, "TaskId">;
+            readonly workspaceId: Schema.brand<Schema.Trim, "WorkspaceId">;
+            readonly graphId: Schema.NullOr<Schema.brand<Schema.Trim, "GraphId">>;
+            readonly externalId: Schema.NullOr<Schema.Trim>;
+            readonly title: Schema.Trim;
+            readonly description: Schema.String;
+            readonly status: Schema.Literals<readonly ["draft", "open", "ready", "queued", "running", "in_progress", "under_review", "blocked", "unknown", "completed", "failed", "cancelled", "closed"]>;
+            readonly priority: Schema.NullOr<Schema.Int>;
+            readonly role: Schema.NullOr<Schema.Trim>;
+            readonly scope: Schema.$Array<Schema.Trim>;
+            readonly validationKeys: Schema.$Array<Schema.Trim>;
+            readonly sourceIssueId: Schema.optional<Schema.NullOr<Schema.Trim>>;
+            readonly dependencies: Schema.optional<Schema.$Array<Schema.Trim>>;
+            readonly parentChildDeps: Schema.optional<Schema.$Array<Schema.Trim>>;
+            readonly metadata: Schema.Unknown;
+            readonly createdAt: Schema.String;
+            readonly updatedAt: Schema.String;
+        }>>;
+        readonly rowKey: Schema.Trim;
+        readonly rowLabel: Schema.Trim;
+        readonly rowIndex: Schema.Int;
+        readonly stage: Schema.Int;
+        readonly x: Schema.Number;
+        readonly y: Schema.Number;
+        readonly width: Schema.Int;
+        readonly height: Schema.Int;
+        readonly color: Schema.optional<Schema.String>;
+        readonly taskCode: Schema.optional<Schema.NullOr<Schema.String>>;
+        readonly strippedTitle: Schema.optional<Schema.String>;
+        readonly depsIn: Schema.optional<Schema.Int>;
+        readonly depsOut: Schema.optional<Schema.Int>;
+        readonly runCount: Schema.optional<Schema.Int>;
+        readonly hasApprovals: Schema.optional<Schema.Boolean>;
+        readonly hasPendingUserInput: Schema.optional<Schema.Boolean>;
+        readonly hasRejectedReview: Schema.optional<Schema.Boolean>;
+        readonly hasFailedValidations: Schema.optional<Schema.Boolean>;
+        readonly artifactCount: Schema.optional<Schema.Int>;
+    }>>;
+    readonly edges: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.Trim;
+        readonly sourceId: Schema.Trim;
+        readonly targetId: Schema.Trim;
+        readonly color: Schema.String;
+        readonly kind: Schema.Literals<readonly ["blocking", "parent-child"]>;
+    }>>;
+    readonly totalWidth: Schema.Int;
+    readonly totalHeight: Schema.Int;
+    readonly taskCount: Schema.Int;
+}>;
+export type TaskGraphLayout = typeof TaskGraphLayout.Type;
+export declare const DependencyGraphModel: Schema.Struct<{
+    readonly graphId: Schema.brand<Schema.Trim, "GraphId">;
+    readonly nodes: Schema.$Array<Schema.Struct<{
+        readonly taskId: Schema.brand<Schema.Trim, "TaskId">;
+        readonly title: Schema.Trim;
+        readonly status: Schema.Literals<readonly ["draft", "open", "ready", "queued", "running", "in_progress", "under_review", "blocked", "unknown", "completed", "failed", "cancelled", "closed"]>;
+        readonly priority: Schema.NullOr<Schema.Int>;
+        readonly assignee: Schema.NullOr<Schema.Trim>;
+        readonly blockedBy: Schema.$Array<Schema.brand<Schema.Trim, "TaskId">>;
+        readonly blocks: Schema.$Array<Schema.brand<Schema.Trim, "TaskId">>;
+        readonly blockingDepth: Schema.Int;
+        readonly blockerClass: Schema.NullOr<Schema.Literals<readonly ["not-blocked", "task-blocked", "human-decision", "human-approval", "external-input", "unknown"]>>;
+        readonly actionRiskTier: Schema.NullOr<Schema.Literals<readonly ["t1-read", "t2-reversible", "t3-external", "t4-irreversible"]>>;
+        readonly epicKey: Schema.NullOr<Schema.Trim>;
+        readonly groupKey: Schema.optional<Schema.NullOr<Schema.Trim>>;
+        readonly externalId: Schema.optional<Schema.NullOr<Schema.Trim>>;
+        readonly sourceIssueId: Schema.optional<Schema.NullOr<Schema.Trim>>;
+        readonly scope: Schema.optional<Schema.$Array<Schema.Trim>>;
+        readonly validationKeys: Schema.optional<Schema.$Array<Schema.Trim>>;
+    }>>;
+    readonly edges: Schema.$Array<Schema.Struct<{
+        readonly fromTaskId: Schema.brand<Schema.Trim, "TaskId">;
+        readonly toTaskId: Schema.brand<Schema.Trim, "TaskId">;
+        readonly type: Schema.Literals<readonly ["blocks", "parent-child", "related"]>;
+    }>>;
+    readonly layout: Schema.Struct<{
+        readonly lanes: Schema.$Array<Schema.Struct<{
+            readonly key: Schema.Trim;
+            readonly label: Schema.Trim;
+            readonly rowIndex: Schema.Int;
+            readonly x: Schema.Number;
+            readonly y: Schema.Number;
+            readonly width: Schema.Int;
+            readonly height: Schema.Int;
+            readonly color: Schema.String;
+            readonly taskCount: Schema.Int;
+        }>>;
+        readonly stages: Schema.$Array<Schema.Struct<{
+            readonly index: Schema.Int;
+            readonly label: Schema.Trim;
+            readonly x: Schema.Number;
+            readonly width: Schema.Int;
+        }>>;
+        readonly nodes: Schema.$Array<Schema.Struct<{
+            readonly id: Schema.Trim;
+            readonly taskId: Schema.brand<Schema.Trim, "TaskId">;
+            readonly task: Schema.optional<Schema.Struct<{
+                readonly id: Schema.brand<Schema.Trim, "TaskId">;
+                readonly workspaceId: Schema.brand<Schema.Trim, "WorkspaceId">;
+                readonly graphId: Schema.NullOr<Schema.brand<Schema.Trim, "GraphId">>;
+                readonly externalId: Schema.NullOr<Schema.Trim>;
+                readonly title: Schema.Trim;
+                readonly description: Schema.String;
+                readonly status: Schema.Literals<readonly ["draft", "open", "ready", "queued", "running", "in_progress", "under_review", "blocked", "unknown", "completed", "failed", "cancelled", "closed"]>;
+                readonly priority: Schema.NullOr<Schema.Int>;
+                readonly role: Schema.NullOr<Schema.Trim>;
+                readonly scope: Schema.$Array<Schema.Trim>;
+                readonly validationKeys: Schema.$Array<Schema.Trim>;
+                readonly sourceIssueId: Schema.optional<Schema.NullOr<Schema.Trim>>;
+                readonly dependencies: Schema.optional<Schema.$Array<Schema.Trim>>;
+                readonly parentChildDeps: Schema.optional<Schema.$Array<Schema.Trim>>;
+                readonly metadata: Schema.Unknown;
+                readonly createdAt: Schema.String;
+                readonly updatedAt: Schema.String;
+            }>>;
+            readonly rowKey: Schema.Trim;
+            readonly rowLabel: Schema.Trim;
+            readonly rowIndex: Schema.Int;
+            readonly stage: Schema.Int;
+            readonly x: Schema.Number;
+            readonly y: Schema.Number;
+            readonly width: Schema.Int;
+            readonly height: Schema.Int;
+            readonly color: Schema.optional<Schema.String>;
+            readonly taskCode: Schema.optional<Schema.NullOr<Schema.String>>;
+            readonly strippedTitle: Schema.optional<Schema.String>;
+            readonly depsIn: Schema.optional<Schema.Int>;
+            readonly depsOut: Schema.optional<Schema.Int>;
+            readonly runCount: Schema.optional<Schema.Int>;
+            readonly hasApprovals: Schema.optional<Schema.Boolean>;
+            readonly hasPendingUserInput: Schema.optional<Schema.Boolean>;
+            readonly hasRejectedReview: Schema.optional<Schema.Boolean>;
+            readonly hasFailedValidations: Schema.optional<Schema.Boolean>;
+            readonly artifactCount: Schema.optional<Schema.Int>;
+        }>>;
+        readonly edges: Schema.$Array<Schema.Struct<{
+            readonly id: Schema.Trim;
+            readonly sourceId: Schema.Trim;
+            readonly targetId: Schema.Trim;
+            readonly color: Schema.String;
+            readonly kind: Schema.Literals<readonly ["blocking", "parent-child"]>;
+        }>>;
+        readonly totalWidth: Schema.Int;
+        readonly totalHeight: Schema.Int;
+        readonly taskCount: Schema.Int;
+    }>;
+    readonly cycles: Schema.$Array<Schema.$Array<Schema.brand<Schema.Trim, "TaskId">>>;
+    readonly unresolvedRefs: Schema.$Array<Schema.Trim>;
+    readonly degraded: Schema.Boolean;
+    readonly generatedAt: Schema.String;
+}>;
+export type DependencyGraphModel = typeof DependencyGraphModel.Type;
+/** Capability id the dependency-graph plugin registers its project-graph builder under. */
+export declare const GRAPH_PROJECT_CAPABILITY_ID = "rig.graph.project";
+/** Pure input to the project-graph builder: which workspace to analyze. */
+export type GraphProjectInput = {
+    readonly projectRoot: string;
+};
+/** The cohesive project-graph operation the substrate depends on. Async (does IO). */
+export interface GraphProjectService {
+    buildProjectGraph(input: GraphProjectInput): Promise<DependencyGraphModel>;
+}
+/** Typed capability id; string value is {@link GRAPH_PROJECT_CAPABILITY_ID}. */
+export declare const GRAPH_PROJECT: CapabilityId<GraphProjectService>;
+/** Capability id the dependency-graph plugin registers its task selector under. */
+export declare const TASK_SELECTION_CAPABILITY_ID = "cap:task-selection";
+/** Pure filters narrowing which tasks are eligible for selection. */
+export type TaskSelectionFilters = {
+    readonly assignee?: string;
+    readonly state?: "open" | "closed";
+    readonly search?: string;
+};
+/** Pure input to task selection: which workspace + optional filters. */
+export type TaskSelectionInput = {
+    readonly projectRoot: string;
+    readonly filters?: TaskSelectionFilters;
+};
+/** Pure result of task selection: the next ready task + the ready set it came from. */
+export type TaskSelectionResult = {
+    readonly selected: TaskSummary | null;
+    readonly ready: readonly TaskSummary[];
+};
+/** The cohesive task-selection operation the CLI surface depends on. Async (does IO). */
+export interface TaskSelectionService {
+    selectNextReadyTask(input: TaskSelectionInput): Promise<TaskSelectionResult>;
+}
+/** Typed capability id; string value is {@link TASK_SELECTION_CAPABILITY_ID}. */
+export declare const TASK_SELECTION: CapabilityId<TaskSelectionService>;