@h-rig/contracts 0.0.6-alpha.17 → 0.0.6-alpha.170

package/dist/src/keybindings.d.ts

@@ -0,0 +1,71 @@
+import { Schema } from "effect";
+export declare const MAX_KEYBINDING_VALUE_LENGTH = 64;
+export declare const MAX_WHEN_EXPRESSION_DEPTH = 64;
+export declare const MAX_SCRIPT_ID_LENGTH = 24;
+export declare const MAX_KEYBINDINGS_COUNT = 256;
+export declare const SCRIPT_RUN_COMMAND_PATTERN: Schema.TemplateLiteral<readonly [Schema.Literal<"script.">, Schema.String, Schema.Literal<".run">]>;
+export declare const KeybindingCommand: Schema.Union<readonly [Schema.Literals<readonly ["terminal.toggle", "terminal.split", "terminal.new", "terminal.close", "diff.toggle", "chat.new", "chat.newLocal", "editor.openFavorite"]>, Schema.TemplateLiteral<readonly [Schema.Literal<"script.">, Schema.String, Schema.Literal<".run">]>]>;
+export type KeybindingCommand = typeof KeybindingCommand.Type;
+export declare const KeybindingRule: Schema.Struct<{
+    readonly key: Schema.Trim;
+    readonly command: Schema.Union<readonly [Schema.Literals<readonly ["terminal.toggle", "terminal.split", "terminal.new", "terminal.close", "diff.toggle", "chat.new", "chat.newLocal", "editor.openFavorite"]>, Schema.TemplateLiteral<readonly [Schema.Literal<"script.">, Schema.String, Schema.Literal<".run">]>]>;
+    readonly when: Schema.optional<Schema.Trim>;
+}>;
+export type KeybindingRule = typeof KeybindingRule.Type;
+export declare const KeybindingsConfig: Schema.$Array<Schema.Struct<{
+    readonly key: Schema.Trim;
+    readonly command: Schema.Union<readonly [Schema.Literals<readonly ["terminal.toggle", "terminal.split", "terminal.new", "terminal.close", "diff.toggle", "chat.new", "chat.newLocal", "editor.openFavorite"]>, Schema.TemplateLiteral<readonly [Schema.Literal<"script.">, Schema.String, Schema.Literal<".run">]>]>;
+    readonly when: Schema.optional<Schema.Trim>;
+}>>;
+export type KeybindingsConfig = typeof KeybindingsConfig.Type;
+export declare const KeybindingShortcut: Schema.Struct<{
+    readonly key: Schema.Trim;
+    readonly metaKey: Schema.Boolean;
+    readonly ctrlKey: Schema.Boolean;
+    readonly shiftKey: Schema.Boolean;
+    readonly altKey: Schema.Boolean;
+    readonly modKey: Schema.Boolean;
+}>;
+export type KeybindingShortcut = typeof KeybindingShortcut.Type;
+export declare const KeybindingWhenNode: Schema.Schema<KeybindingWhenNode>;
+export type KeybindingWhenNode = {
+    type: "identifier";
+    name: string;
+} | {
+    type: "not";
+    node: KeybindingWhenNode;
+} | {
+    type: "and";
+    left: KeybindingWhenNode;
+    right: KeybindingWhenNode;
+} | {
+    type: "or";
+    left: KeybindingWhenNode;
+    right: KeybindingWhenNode;
+};
+export declare const ResolvedKeybindingRule: Schema.Struct<{
+    readonly command: Schema.Union<readonly [Schema.Literals<readonly ["terminal.toggle", "terminal.split", "terminal.new", "terminal.close", "diff.toggle", "chat.new", "chat.newLocal", "editor.openFavorite"]>, Schema.TemplateLiteral<readonly [Schema.Literal<"script.">, Schema.String, Schema.Literal<".run">]>]>;
+    readonly shortcut: Schema.Struct<{
+        readonly key: Schema.Trim;
+        readonly metaKey: Schema.Boolean;
+        readonly ctrlKey: Schema.Boolean;
+        readonly shiftKey: Schema.Boolean;
+        readonly altKey: Schema.Boolean;
+        readonly modKey: Schema.Boolean;
+    }>;
+    readonly whenAst: Schema.optional<Schema.Schema<KeybindingWhenNode>>;
+}>;
+export type ResolvedKeybindingRule = typeof ResolvedKeybindingRule.Type;
+export declare const ResolvedKeybindingsConfig: Schema.$Array<Schema.Struct<{
+    readonly command: Schema.Union<readonly [Schema.Literals<readonly ["terminal.toggle", "terminal.split", "terminal.new", "terminal.close", "diff.toggle", "chat.new", "chat.newLocal", "editor.openFavorite"]>, Schema.TemplateLiteral<readonly [Schema.Literal<"script.">, Schema.String, Schema.Literal<".run">]>]>;
+    readonly shortcut: Schema.Struct<{
+        readonly key: Schema.Trim;
+        readonly metaKey: Schema.Boolean;
+        readonly ctrlKey: Schema.Boolean;
+        readonly shiftKey: Schema.Boolean;
+        readonly altKey: Schema.Boolean;
+        readonly modKey: Schema.Boolean;
+    }>;
+    readonly whenAst: Schema.optional<Schema.Schema<KeybindingWhenNode>>;
+}>>;
+export type ResolvedKeybindingsConfig = typeof ResolvedKeybindingsConfig.Type;

package/dist/src/keybindings.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/layout.d.ts

@@ -0,0 +1,49 @@
+/** Directory name for a project's checked-in rig definition (`<root>/rig`). */
+export declare const RIG_DEFINITION_DIRNAME = "rig";
+/** Directory name for rig's per-project state (`<root>/.rig`). */
+export declare const RIG_STATE_DIRNAME = ".rig";
+/** Directory name for run artifacts (`<workspace>/artifacts`). */
+export declare const RIG_ARTIFACTS_DIRNAME = "artifacts";
+export type RigLayout = {
+    projectRoot: string;
+    monorepoRoot: string;
+    definitionRoot: string;
+    runtimeWorkspaceRoot: string;
+    stateRoot: string;
+    artifactsRoot: string;
+    configPath: string;
+    taskConfigPath: string;
+    policyDir: string;
+    policyFile: string;
+    pluginsDir: string;
+    hooksDir: string;
+    toolsDir: string;
+    templatesDir: string;
+    validationDir: string;
+    stateDir: string;
+    logsDir: string;
+    notificationsDir: string;
+    runtimeDir: string;
+    distDir: string;
+    binDir: string;
+    pluginBinDir: string;
+    keybindingsPath: string;
+    controlPlaneEventsFile: string;
+};
+export type RuntimeWorkspaceLayout = {
+    workspaceDir: string;
+    rigRoot: string;
+    stateDir: string;
+    logsDir: string;
+    artifactsRoot: string;
+    runtimeDir: string;
+    homeDir: string;
+    tmpDir: string;
+    cacheDir: string;
+    sessionDir: string;
+    binDir: string;
+    distDir: string;
+    pluginBinDir: string;
+    contextPath: string;
+    controlPlaneEventsFile: string;
+};

package/dist/src/layout.js

@@ -0,0 +1,10 @@
+// @bun
+// packages/contracts/src/layout.ts
+var RIG_DEFINITION_DIRNAME = "rig";
+var RIG_STATE_DIRNAME = ".rig";
+var RIG_ARTIFACTS_DIRNAME = "artifacts";
+export {
+  RIG_STATE_DIRNAME,
+  RIG_DEFINITION_DIRNAME,
+  RIG_ARTIFACTS_DIRNAME
+};

package/dist/src/lifecycle-capabilities.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Typed ports for the default-lifecycle bundle's verification services.
+ *
+ * The dumb runtime substrate (rig-agent, harness-cli) must NOT import the
+ * lifecycle bundle (substrate->plugin cycle). Instead the bundle plugin
+ * registers executable impls under these ids on its
+ * `contributes.capabilities[].run`, and the runtime resolves them by id from
+ * `pluginHost.listExecutableCapabilities()`. These pure types are the shared
+ * contract for that seam — they carry no behaviour and import nothing.
+ */
+import type { CapabilityId } from "./capability-id";
+import type { JournalCapability } from "./kernel";
+import type { RigAutomationConfig, StrictPrGreptileApiOptions } from "./control-plane-types";
+import type { RunCloseoutPhase, RunCloseoutPhaseOutcome } from "./run-journal";
+import type { TaskSourceUpdateResult } from "./task-source";
+/** Capability id the bundle registers its `taskVerify` orchestration under. */
+export declare const TASK_VERIFY_CAPABILITY_ID = "default-lifecycle.task-verify";
+/** Capability id the bundle registers its task validation runner under. */
+export declare const TASK_VALIDATION_CAPABILITY_ID = "default-lifecycle.task-validation";
+/** Capability id the bundle registers the completion-verification gate under. */
+export declare const COMPLETION_VERIFICATION_CAPABILITY_ID = "default-lifecycle.completion-verification";
+/** Capability id the bundle registers its run-worker closeout driver under. */
+export declare const RUN_CLOSEOUT_CAPABILITY_ID = "default-lifecycle.run-closeout";
+/** Capability id the bundle registers its lifecycle-owned task-source reflection under. */
+export declare const TASK_SOURCE_REFLECTION_CAPABILITY_ID = "default-lifecycle.task-source-reflection";
+/** Capability id the bundle registers its agent-facing git helper surface under. */
+export declare const LIFECYCLE_GIT_AGENT_CAPABILITY_ID = "default-lifecycle.git-agent";
+export interface TaskVerifyCapabilityInput {
+    readonly projectRoot: string;
+    readonly taskId?: string;
+}
+/** Resolves true when the task is approved, false when verification rejects. */
+export type TaskVerifyCapabilityRun = (input: TaskVerifyCapabilityInput) => Promise<boolean>;
+/**
+ * The typed capability id the bundle provides its task-verify run under, phantom-
+ * typed with {@link TaskVerifyCapabilityRun} so `defineCapability(TASK_VERIFY_CAPABILITY)`
+ * resolves to the run function with no cast leaking to callers. Its string value
+ * is {@link TASK_VERIFY_CAPABILITY_ID}, so it indexes the same host entry.
+ */
+export declare const TASK_VERIFY_CAPABILITY: CapabilityId<TaskVerifyCapabilityRun>;
+export interface TaskValidationCapabilityInput {
+    readonly projectRoot: string;
+    readonly taskId?: string;
+    readonly validatorRegistry?: unknown;
+}
+/** Resolves true when task validation passes or is skipped, false on validation failures. */
+export type TaskValidationCapabilityRun = (input: TaskValidationCapabilityInput) => Promise<boolean>;
+export declare const TASK_VALIDATION_CAPABILITY: CapabilityId<TaskValidationCapabilityRun>;
+export interface CompletionVerificationCapabilityInput {
+    readonly projectRoot: string;
+    readonly taskId?: string;
+}
+export interface CompletionVerificationCapabilityResult {
+    /** True when every completion gate passed; false when the gate blocks. */
+    readonly ok: boolean;
+}
+export type CompletionVerificationCapabilityRun = (input: CompletionVerificationCapabilityInput) => Promise<CompletionVerificationCapabilityResult>;
+/**
+ * The typed capability id the bundle provides its completion-verification gate
+ * under, phantom-typed with {@link CompletionVerificationCapabilityRun}. Its
+ * string value is {@link COMPLETION_VERIFICATION_CAPABILITY_ID}, so it indexes
+ * the same host entry.
+ */
+export declare const COMPLETION_VERIFICATION_CAPABILITY: CapabilityId<CompletionVerificationCapabilityRun>;
+export type LifecycleGitCommitOptions = {
+    projectRoot: string;
+    taskId?: string;
+    target: "monorepo" | "project" | "both";
+    message?: string;
+    allowEmpty: boolean;
+    scoped?: boolean;
+};
+export type LifecycleGitOpenPrOptions = {
+    projectRoot: string;
+    taskId?: string;
+    target?: "monorepo" | "project";
+    reviewer?: string;
+    base?: string;
+    title?: string;
+    body?: string;
+    draft?: boolean;
+};
+export type LifecycleGitOpenPrResult = {
+    url: string;
+    reviewer?: string;
+    reviewerSource?: "flag" | "task-config" | "changed-files" | "env";
+    target: "monorepo" | "project";
+    repoLabel: string;
+    branch: string;
+    base: string;
+};
+export type LifecycleGitAgentService = {
+    shouldScopeGitCommit(args: string[], hasTaskContext: boolean): boolean;
+    gitStatus(projectRoot: string, taskId?: string): void;
+    gitChanged(projectRoot: string, taskId: string | undefined, scoped: boolean): string[];
+    gitPreflight(projectRoot: string, taskId: string | undefined, strict: boolean): boolean;
+    gitSyncBranch(projectRoot: string, taskId?: string, targetRepo?: "monorepo" | "project"): void;
+    gitCommit(options: LifecycleGitCommitOptions): void;
+    gitSnapshot(projectRoot: string, taskId?: string, outputPath?: string): string;
+    gitOpenPr(options: LifecycleGitOpenPrOptions): LifecycleGitOpenPrResult;
+};
+export declare const LIFECYCLE_GIT_AGENT: CapabilityId<LifecycleGitAgentService>;
+export type RunTaskSourceReflectStatus = "under_review" | "ci_fixing" | "merging" | "closed" | "needs_attention";
+export type RunTaskSourceLifecycleStatus = "running" | RunTaskSourceReflectStatus | "cancelled";
+export type RunTaskSourceLifecycleRun = {
+    runId?: string | null;
+    taskId?: string | null;
+    sourceTask?: unknown;
+    worktreePath?: string | null;
+    logRoot?: string | null;
+    sessionPath?: string | null;
+    errorText?: string | null;
+};
+export type RunTaskSourceLifecycleOptions = {
+    errorText?: string | null;
+};
+export type TaskSourceReflectionInput = {
+    readonly projectRoot: string;
+    readonly taskId: string;
+    readonly sourceTask?: unknown;
+    readonly runId?: string | null;
+    /** Generic source status to write. Omit/null for comment-only reflection. */
+    readonly status?: string | null;
+    /** Status text rendered in the lifecycle comment; defaults to `status`. */
+    readonly commentStatus?: string | null;
+    readonly summary: string;
+    readonly runtimeWorkspace?: string | null;
+    readonly logsDir?: string | null;
+    readonly sessionDir?: string | null;
+    readonly errorText?: string | null;
+    readonly prUrl?: string | null;
+};
+export type TaskSourceMergedPrReflectionInput = {
+    readonly projectRoot: string;
+    readonly taskId: string;
+    readonly runId: string;
+    readonly prUrl: string;
+    readonly sourceTask?: unknown;
+};
+export type TaskSourceReflectionResult = TaskSourceUpdateResult & {
+    readonly status?: unknown;
+};
+export interface TaskSourceReflectionService {
+    reflectTaskSourceStatus(input: TaskSourceReflectionInput): Promise<TaskSourceReflectionResult | null>;
+    updateRunTaskSourceLifecycle(projectRoot: string, run: RunTaskSourceLifecycleRun, status: RunTaskSourceLifecycleStatus, summary: string, options?: RunTaskSourceLifecycleOptions): Promise<TaskSourceReflectionResult | null>;
+    closeMergedPr(input: TaskSourceMergedPrReflectionInput): Promise<TaskSourceReflectionResult | null>;
+}
+export declare const TASK_SOURCE_REFLECTION: CapabilityId<TaskSourceReflectionService>;
+export type RunCloseoutResultStatus = "merged" | "opened" | "skipped" | "needs-attention";
+export type RunCloseoutResult = {
+    status: RunCloseoutResultStatus;
+    prUrl?: string;
+    iterations: number;
+    feedback: readonly string[];
+};
+export type RunCloseoutValidationInput = {
+    projectRoot: string;
+    taskId: string;
+};
+export type RunCloseoutValidationRunner = (input: RunCloseoutValidationInput) => Promise<boolean> | boolean;
+export type RunCloseoutInput = {
+    projectRoot: string;
+    runId: string;
+    taskId: string;
+    branch: string;
+    workspace: string;
+    artifactRoot?: string | null;
+    config?: RigAutomationConfig | null;
+    sourceTask?: Record<string, unknown> | null;
+    steerPi: (message: string) => Promise<void>;
+    greptileApi?: StrictPrGreptileApiOptions;
+    runValidation?: RunCloseoutValidationRunner;
+    onValidationStart?: () => Promise<void> | void;
+    kernelJournal?: JournalCapability | null;
+    journalPhase: (phase: RunCloseoutPhase, outcome: RunCloseoutPhaseOutcome, detail?: string | null) => Promise<void> | void;
+    reflect: (status: RunTaskSourceReflectStatus, summary: string, options?: {
+        errorText?: string | null;
+    }) => Promise<void> | void;
+};
+export type RunCloseoutCapabilityRun = (input: RunCloseoutInput) => Promise<RunCloseoutResult>;
+/**
+ * The typed capability id the bundle provides its run-worker closeout driver
+ * under, so @rig/run-worker can close out by resolving the lifecycle capability
+ * instead of importing the lifecycle plugin implementation.
+ */
+export declare const RUN_CLOSEOUT_CAPABILITY: CapabilityId<RunCloseoutCapabilityRun>;

package/dist/src/lifecycle-capabilities.js

@@ -0,0 +1,33 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/lifecycle-capabilities.ts
+var TASK_VERIFY_CAPABILITY_ID = "default-lifecycle.task-verify";
+var TASK_VALIDATION_CAPABILITY_ID = "default-lifecycle.task-validation";
+var COMPLETION_VERIFICATION_CAPABILITY_ID = "default-lifecycle.completion-verification";
+var RUN_CLOSEOUT_CAPABILITY_ID = "default-lifecycle.run-closeout";
+var TASK_SOURCE_REFLECTION_CAPABILITY_ID = "default-lifecycle.task-source-reflection";
+var LIFECYCLE_GIT_AGENT_CAPABILITY_ID = "default-lifecycle.git-agent";
+var TASK_VERIFY_CAPABILITY = makeCapabilityId(TASK_VERIFY_CAPABILITY_ID);
+var TASK_VALIDATION_CAPABILITY = makeCapabilityId(TASK_VALIDATION_CAPABILITY_ID);
+var COMPLETION_VERIFICATION_CAPABILITY = makeCapabilityId(COMPLETION_VERIFICATION_CAPABILITY_ID);
+var LIFECYCLE_GIT_AGENT = makeCapabilityId(LIFECYCLE_GIT_AGENT_CAPABILITY_ID);
+var TASK_SOURCE_REFLECTION = makeCapabilityId(TASK_SOURCE_REFLECTION_CAPABILITY_ID);
+var RUN_CLOSEOUT_CAPABILITY = makeCapabilityId(RUN_CLOSEOUT_CAPABILITY_ID);
+export {
+  TASK_VERIFY_CAPABILITY_ID,
+  TASK_VERIFY_CAPABILITY,
+  TASK_VALIDATION_CAPABILITY_ID,
+  TASK_VALIDATION_CAPABILITY,
+  TASK_SOURCE_REFLECTION_CAPABILITY_ID,
+  TASK_SOURCE_REFLECTION,
+  RUN_CLOSEOUT_CAPABILITY_ID,
+  RUN_CLOSEOUT_CAPABILITY,
+  LIFECYCLE_GIT_AGENT_CAPABILITY_ID,
+  LIFECYCLE_GIT_AGENT,
+  COMPLETION_VERIFICATION_CAPABILITY_ID,
+  COMPLETION_VERIFICATION_CAPABILITY
+};

package/dist/src/managed-repos.d.ts

@@ -0,0 +1,239 @@
+/**
+ * Pure managed-repo, repo-operation, and repo-native git contract types + capability ids.
+ *
+ * `@rig/repos-plugin` owns the concrete implementations. It contributes:
+ * - `ManagedRepoService` under {@link MANAGED_REPO_SERVICE_CAPABILITY_ID} for
+ *   registry/layout/mirror state,
+ * - `RepoOperationsService` under {@link REPO_OPERATIONS_CAPABILITY_ID} for
+ *   task repo pinning, baseline reset, and project-main pre-run sync,
+ * - `RepoNativeGitService` under {@link REPO_NATIVE_GIT_CAPABILITY_ID} for
+ *   repo-native git command wrappers, and
+ * - `RepoGitBinaryService` under {@link REPO_GIT_BINARY_CAPABILITY_ID} for
+ *   the repo-owned rig-git helper binary.
+ *
+ * This module carries no behaviour and imports only pure sibling types, so
+ * consumers resolve typed ids through `@rig/core` without importing the provider
+ * plugin or the old kernel repo-ops facades.
+ */
+import type { CapabilityId } from "./capability-id";
+import type { RepoSourceRegistration } from "./plugin";
+import type { GitWorkingTreeFileChange } from "./git";
+import type { NativeToolchainBinaryArtifact, NativeToolchainTarget } from "./native-toolchain";
+export type ManagedRepoId = string;
+export type ManagedRepoAlias = string;
+export type ManagedRepoHealth = "missing" | "ready" | "stale" | "misconfigured";
+export type ManagedRepoRegistryEntry = {
+    id: ManagedRepoId;
+    alias: ManagedRepoAlias;
+    defaultBranch: string;
+    defaultRemoteUrl: string;
+    remoteEnvVar?: string;
+    checkoutEnvVar?: string;
+};
+export type ManagedRepoLayout = {
+    projectRoot: string;
+    repoId: ManagedRepoId;
+    alias: ManagedRepoAlias;
+    defaultBranch: string;
+    remoteUrl: string;
+    checkoutRoot: string;
+    worktreesRoot: string;
+    stateDir: string;
+    metadataRoot: string;
+    metadataRelativePath: string;
+    mirrorRoot: string;
+    mirrorStatePath: string;
+    mirrorStateRelativePath: string;
+};
+export type ManagedRepoMirrorState = {
+    version: 1;
+    repoId: ManagedRepoId;
+    remoteUrl: string;
+    defaultBranch: string;
+    initializedAt?: string;
+    lastSyncedAt?: string;
+    headRef?: string;
+    headCommit?: string;
+};
+export type ManagedRepoSyncResult = {
+    layout: ManagedRepoLayout;
+    headCommit: string;
+};
+/** A repo registration plus an optional computed local checkout path. */
+export interface RepoEntry extends RepoSourceRegistration {
+    /** Optional computed local checkout path (runtime-specific, may be set by caller). */
+    localPath?: string;
+}
+/** An immutable, id-indexed view over plugin-contributed repo sources. */
+export interface RepoRegistry {
+    getById(id: string): RepoEntry | undefined;
+    list(): readonly RepoEntry[];
+}
+/**
+ * The cohesive set of managed-repo operations the runtime substrate depends on.
+ * The plugin provides a concrete impl (statically checked against this interface
+ * via `defineCapability(MANAGED_REPO_SERVICE_CAPABILITY).provide`); the substrate
+ * only ever sees this port, resolved by id off a plugin host with no cast.
+ */
+export interface ManagedRepoService {
+    /** Replace the managed-repo singleton with the given entries (boot wiring). */
+    setManagedRepos(entries: readonly ManagedRepoRegistryEntry[]): void;
+    /** List the currently registered managed-repo entries. */
+    listManagedRepoEntries(): ManagedRepoRegistryEntry[];
+    /** Resolve a managed-repo id from its alias, or null when unknown. */
+    resolveManagedRepoIdByAlias(alias: string): ManagedRepoId | null;
+    /**
+     * Convert a plugin-contributed RepoSourceRegistration into the managed-repo
+     * entry shape; null for pure-listing registrations (no defaultBranch).
+     */
+    repoRegistrationToManagedEntry(reg: RepoSourceRegistration): ManagedRepoRegistryEntry | null;
+    /** Build an immutable id-indexed registry from repo source registrations. */
+    createRepoRegistry(entries: readonly RepoSourceRegistration[]): RepoRegistry;
+    /** Resolve a managed repo's on-disk layout by alias, or null when unknown. */
+    resolveManagedRepoLayoutByAlias(projectRoot: string, alias: string): ManagedRepoLayout | null;
+    /** Resolve the primary monorepo layout; throws when no managed repos exist. */
+    resolveMonorepoRepoLayout(projectRoot: string): ManagedRepoLayout;
+    /** Refresh + sync a managed repo's mirror, returning the resulting head. */
+    syncManagedRepo(projectRoot: string, repoId: ManagedRepoId): ManagedRepoSyncResult;
+}
+export type RepoPins = Record<string, string>;
+export type RepoNativeGitTreeCommitUpdate = {
+    readonly path: string;
+    readonly content: string;
+    readonly executable?: boolean;
+} | {
+    readonly path: string;
+    readonly delete: true;
+};
+/**
+ * Repo-owned native git command seam. Implementations live in `@rig/repos-plugin`;
+ * native-toolchain only builds/materializes binaries and does not own repo or git
+ * workflow semantics.
+ */
+export interface RepoNativeGitService {
+    fetchRef(repoPath: string, remote: string, branch: string): string;
+    readBlobAtRef(repoPath: string, ref: string, path: string): string;
+    writeTreeCommit(repoPath: string, baseRef: string, updates: readonly RepoNativeGitTreeCommitUpdate[], message: string): string;
+    pushRefWithLease(repoPath: string, localOid: string, remoteRef: string, expectedOldOid: string, remote?: string): string;
+}
+/**
+ * Repo-native git is intentionally named from repos contracts. The capability id
+ * remains `native-toolchain.git` for compatibility with already published
+ * providers/consumers; treat that string as a legacy wire id, not ownership.
+ */
+export declare const REPO_NATIVE_GIT_CAPABILITY_ID = "native-toolchain.git";
+export declare const REPO_NATIVE_GIT: CapabilityId<RepoNativeGitService>;
+/** @deprecated Use RepoNativeGitTreeCommitUpdate. */
+export type NativeGitTreeCommitUpdate = RepoNativeGitTreeCommitUpdate;
+/** @deprecated Use RepoNativeGitService. */
+export type NativeGitService = RepoNativeGitService;
+/** @deprecated Use REPO_NATIVE_GIT_CAPABILITY_ID; this is the legacy wire id. */
+export declare const NATIVE_TOOLCHAIN_GIT_CAPABILITY_ID = "native-toolchain.git";
+/** @deprecated Use REPO_NATIVE_GIT. */
+export declare const NATIVE_TOOLCHAIN_GIT: CapabilityId<RepoNativeGitService>;
+export interface RepoGitBinaryResolveInput {
+    readonly projectRoot?: string;
+    readonly target?: NativeToolchainTarget;
+}
+export interface RepoGitBinaryMaterializeInput {
+    readonly projectRoot: string;
+    readonly targetDir: string;
+    readonly target?: NativeToolchainTarget;
+}
+export interface RepoGitBinaryArtifact extends NativeToolchainBinaryArtifact {
+    readonly name: "rig-git";
+    readonly kind: "executable";
+    readonly commandName: string;
+}
+export interface RepoGitBinaryService {
+    gitHelperBinaryName(input?: RepoGitBinaryResolveInput): string;
+    resolveGitHelperBinary(input?: RepoGitBinaryResolveInput): RepoGitBinaryArtifact | null | Promise<RepoGitBinaryArtifact | null>;
+    materializeGitHelperBinary(input: RepoGitBinaryMaterializeInput): Promise<RepoGitBinaryArtifact>;
+}
+export declare const REPO_GIT_BINARY_CAPABILITY_ID = "repos.git-binary";
+export declare const REPO_GIT_BINARY: CapabilityId<RepoGitBinaryService>;
+export type ProjectMainPreRunSyncResult = {
+    status: "disabled";
+} | {
+    status: "skipped_not_main";
+    branch: string;
+} | {
+    status: "up_to_date";
+} | {
+    status: "local_ahead";
+    localAhead: number;
+} | {
+    status: "updated";
+    remoteAhead: number;
+};
+export type ProjectMainPreRunSyncOptions = {
+    projectRoot: string;
+    disabled?: boolean;
+    runBootstrap: () => Promise<void>;
+    syncMonorepo?: (projectRoot: string) => void | Promise<void>;
+};
+export type RepoChangeSetSelector = {
+    readonly kind: "task";
+    readonly taskId: string;
+    readonly scoped: boolean;
+} | {
+    readonly kind: "scope";
+    readonly paths: readonly string[];
+} | {
+    readonly kind: "workspace";
+};
+export type RepoChangeSetTarget = {
+    readonly kind: "project";
+    readonly projectRoot: string;
+} | {
+    readonly kind: "managed-repo";
+    readonly projectRoot: string;
+    readonly repoId: ManagedRepoId;
+} | {
+    readonly kind: "repo-root";
+    readonly repoRoot: string;
+    readonly projectRoot?: string;
+};
+export interface RepoChangeSetInput {
+    readonly projectRoot: string;
+    readonly selector: RepoChangeSetSelector;
+    readonly target?: RepoChangeSetTarget;
+}
+export interface RepoChangeSetFile extends GitWorkingTreeFileChange {
+    readonly repoRoot: string;
+    readonly repoId?: ManagedRepoId;
+}
+export interface RepoChangeSet {
+    readonly changedFiles: readonly RepoChangeSetFile[];
+    readonly pendingFiles: readonly RepoChangeSetFile[];
+}
+export interface RepoChangeSetService {
+    collectChangeSet(input: RepoChangeSetInput): RepoChangeSet | Promise<RepoChangeSet>;
+    changedFiles(input: RepoChangeSetInput): readonly RepoChangeSetFile[] | Promise<readonly RepoChangeSetFile[]>;
+    pendingFiles(input: RepoChangeSetInput): readonly RepoChangeSetFile[] | Promise<readonly RepoChangeSetFile[]>;
+}
+export declare const REPO_CHANGE_SET_CAPABILITY_ID = "repos.change-set";
+export declare const REPO_CHANGE_SET: CapabilityId<RepoChangeSetService>;
+export interface RepoOperationsService {
+    repoEnsure(projectRoot: string, taskId?: string): void;
+    repoPins(projectRoot: string, taskId?: string): RepoPins;
+    repoVerify(projectRoot: string, taskId?: string): boolean;
+    repoDiscover(projectRoot: string, taskId?: string): RepoPins;
+    repoBaseline(projectRoot: string, refresh?: boolean): RepoPins;
+    resetBaseline(projectRoot: string, keepTaskStatus: boolean): void;
+    ensureProjectMainFreshBeforeRun(options: ProjectMainPreRunSyncOptions): Promise<ProjectMainPreRunSyncResult>;
+}
+export declare const REPO_OPERATIONS_CAPABILITY_ID = "repos.operations";
+export declare const REPO_OPERATIONS_CAPABILITY: CapabilityId<RepoOperationsService>;
+/** The capability `run` shape the plugin registers: a (lazy) service factory. */
+export type ManagedRepoServiceCapabilityRun = () => ManagedRepoService | Promise<ManagedRepoService>;
+/** Capability id the managed-repo service plugin registers its factory under. */
+export declare const MANAGED_REPO_SERVICE_CAPABILITY_ID = "managed-repos.service";
+/**
+ * The typed capability id the repos plugin provides and consumers require.
+ * Phantom-typed with {@link ManagedRepoService} so
+ * `defineCapability(MANAGED_REPO_SERVICE_CAPABILITY).resolve(host)` returns a
+ * `ManagedRepoService` with no cast leaking to callers. Its string value is
+ * {@link MANAGED_REPO_SERVICE_CAPABILITY_ID}, so it indexes the same host entry.
+ */
+export declare const MANAGED_REPO_SERVICE_CAPABILITY: CapabilityId<ManagedRepoService>;

package/dist/src/managed-repos.js

@@ -0,0 +1,33 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/managed-repos.ts
+var REPO_NATIVE_GIT_CAPABILITY_ID = "native-toolchain.git";
+var REPO_NATIVE_GIT = makeCapabilityId(REPO_NATIVE_GIT_CAPABILITY_ID);
+var NATIVE_TOOLCHAIN_GIT_CAPABILITY_ID = REPO_NATIVE_GIT_CAPABILITY_ID;
+var NATIVE_TOOLCHAIN_GIT = REPO_NATIVE_GIT;
+var REPO_GIT_BINARY_CAPABILITY_ID = "repos.git-binary";
+var REPO_GIT_BINARY = makeCapabilityId(REPO_GIT_BINARY_CAPABILITY_ID);
+var REPO_CHANGE_SET_CAPABILITY_ID = "repos.change-set";
+var REPO_CHANGE_SET = makeCapabilityId(REPO_CHANGE_SET_CAPABILITY_ID);
+var REPO_OPERATIONS_CAPABILITY_ID = "repos.operations";
+var REPO_OPERATIONS_CAPABILITY = makeCapabilityId(REPO_OPERATIONS_CAPABILITY_ID);
+var MANAGED_REPO_SERVICE_CAPABILITY_ID = "managed-repos.service";
+var MANAGED_REPO_SERVICE_CAPABILITY = makeCapabilityId(MANAGED_REPO_SERVICE_CAPABILITY_ID);
+export {
+  REPO_OPERATIONS_CAPABILITY_ID,
+  REPO_OPERATIONS_CAPABILITY,
+  REPO_NATIVE_GIT_CAPABILITY_ID,
+  REPO_NATIVE_GIT,
+  REPO_GIT_BINARY_CAPABILITY_ID,
+  REPO_GIT_BINARY,
+  REPO_CHANGE_SET_CAPABILITY_ID,
+  REPO_CHANGE_SET,
+  NATIVE_TOOLCHAIN_GIT_CAPABILITY_ID,
+  NATIVE_TOOLCHAIN_GIT,
+  MANAGED_REPO_SERVICE_CAPABILITY_ID,
+  MANAGED_REPO_SERVICE_CAPABILITY
+};