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

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,128 @@
+/**
+ * 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";
+/** 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 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 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 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 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,25 @@
+// @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 COMPLETION_VERIFICATION_CAPABILITY_ID = "default-lifecycle.completion-verification";
+var RUN_CLOSEOUT_CAPABILITY_ID = "default-lifecycle.run-closeout";
+var LIFECYCLE_GIT_AGENT_CAPABILITY_ID = "default-lifecycle.git-agent";
+var TASK_VERIFY_CAPABILITY = makeCapabilityId(TASK_VERIFY_CAPABILITY_ID);
+var COMPLETION_VERIFICATION_CAPABILITY = makeCapabilityId(COMPLETION_VERIFICATION_CAPABILITY_ID);
+var LIFECYCLE_GIT_AGENT = makeCapabilityId(LIFECYCLE_GIT_AGENT_CAPABILITY_ID);
+var RUN_CLOSEOUT_CAPABILITY = makeCapabilityId(RUN_CLOSEOUT_CAPABILITY_ID);
+export {
+  TASK_VERIFY_CAPABILITY_ID,
+  TASK_VERIFY_CAPABILITY,
+  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,136 @@
+/**
+ * Pure managed-repo and repo-operation 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, and
+ * - `RepoOperationsService` under {@link REPO_OPERATIONS_CAPABILITY_ID} for
+ *   task repo pinning, baseline reset, and project-main pre-run sync.
+ *
+ * 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";
+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 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 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,17 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/managed-repos.ts
+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,
+  MANAGED_REPO_SERVICE_CAPABILITY_ID,
+  MANAGED_REPO_SERVICE_CAPABILITY
+};

package/dist/src/memory.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Pure memory-service contract types.
+ *
+ * These types are the neutral home for the shared-memory data model so that the
+ * dumb runtime substrate (hooks, harness-cli, isolation, rig-agent) and the
+ * @rig/memory-plugin that owns the implementation can both reference them
+ * without a substrate->plugin import cycle. They carry no behaviour and import
+ * nothing — exactly like `lifecycle-capabilities.ts`.
+ *
+ * The plugin registers its executable `MemoryService` impl under the typed
+ * capability id {@link MEMORY} (whose string value is
+ * {@link MEMORY_SERVICE_CAPABILITY_ID}); the runtime resolves it by id from
+ * `pluginHost.listExecutableCapabilities()` via the `defineCapability` seam
+ * (`@rig/core/capability`), re-exported from the thin
+ * `@rig/runtime/control-plane/memory-service-port`.
+ */
+import type { CapabilityId } from "./capability-id";
+import type { RuntimeMemoryRetrievalConfig, RuntimeTaskContext } from "./runtime-task-context";
+/** Capability id the memory plugin registers its `MemoryService` factory under. */
+export declare const MEMORY_SERVICE_CAPABILITY_ID = "memory.service";
+export declare const NO_MATCH_RETRIEVAL_CANONICAL_KEY = "__memory_recall__:none";
+export type MemoryDbStatement = {
+    sql: string;
+    args?: unknown[];
+};
+export type MemoryDbExecuteResult = {
+    rows: Array<Record<string, unknown>>;
+    rowsAffected?: number;
+};
+export type MemoryDbTransaction = {
+    execute(statement: MemoryDbStatement | string, args?: unknown[]): Promise<MemoryDbExecuteResult>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    close(): void;
+};
+export type MemoryDbClient = {
+    execute(statement: MemoryDbStatement | string, args?: unknown[]): Promise<MemoryDbExecuteResult>;
+    transaction(mode: "write"): Promise<MemoryDbTransaction>;
+    close(): void;
+};
+export type MemoryEventType = "observed" | "promoted" | "corrected" | "superseded" | "retracted" | "reinforced" | "retrieved" | "feedback_recorded";
+export type MemoryStatus = "active" | "superseded" | "retracted";
+export type RetrievalFeedbackOutcome = "helpful" | "ignored" | "incorrect";
+type MemoryEventBase = {
+    eventId: string;
+    canonicalKey: string;
+    sourceRunId?: string | null;
+    sourceTaskId?: string | null;
+    branch?: string | null;
+    createdAt: string;
+};
+type MemoryProjectionSeed = {
+    summary: string;
+    kind: string;
+    category?: string | null;
+    confidence: number;
+    details?: Record<string, unknown> | null;
+};
+export type MemoryEventInput = (MemoryEventBase & MemoryProjectionSeed & {
+    eventType: "observed";
+}) | (MemoryEventBase & MemoryProjectionSeed & {
+    eventType: "promoted";
+    sourceCanonicalKey: string;
+}) | (MemoryEventBase & MemoryProjectionSeed & {
+    eventType: "corrected";
+    sourceCanonicalKey: string;
+}) | (MemoryEventBase & {
+    eventType: "superseded";
+    replacementCanonicalKey: string;
+}) | (MemoryEventBase & {
+    eventType: "retracted";
+}) | (MemoryEventBase & {
+    eventType: "reinforced";
+    confidence: number;
+}) | (MemoryEventBase & {
+    eventType: "retrieved";
+    retrievalQuery: string;
+    retrievalRank: number;
+}) | (MemoryEventBase & {
+    eventType: "feedback_recorded";
+    feedbackOutcome: RetrievalFeedbackOutcome;
+    retrievalRank: number;
+    retrievalQuery?: string | null;
+});
+export type MemoryEventMetadata = {
+    sourceCanonicalKey?: string | null;
+    replacementCanonicalKey?: string | null;
+    retrievalQuery?: string | null;
+    retrievalRank?: number | null;
+    feedbackOutcome?: RetrievalFeedbackOutcome | null;
+    summary?: string | null;
+    kind?: string | null;
+    category?: string | null;
+    confidence?: number | null;
+    details?: Record<string, unknown> | null;
+};
+export type MemoryEventRow = {
+    eventId: string;
+    eventType: MemoryEventType;
+    canonicalKey: string;
+    summary: string;
+    createdAt: string;
+};
+export type MemoryItemRow = {
+    canonicalKey: string;
+    summary: string;
+    kind: string | null;
+    category: string | null;
+    status: MemoryStatus;
+    confidence: number;
+    sourceRunId: string | null;
+    sourceTaskId: string | null;
+    branch: string | null;
+    details: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt: string;
+    lastEventId: string;
+    supersededBy: string | null;
+    embedding: number[] | null;
+};
+export type MemoryQueryOptions = {
+    canonicalKey?: string;
+    includeInactive?: boolean;
+};
+export type MemoryDb = {
+    path: string;
+    client: MemoryDbClient;
+    close(): Promise<void>;
+};
+/** A scored, ranked shared-memory item returned by the retrieval query. */
+export type MemoryQueryResult = {
+    canonicalKey: string;
+    summary: string;
+    kind: string | null;
+    category: string | null;
+    confidence: number;
+    updatedAt: string;
+    score: number;
+    lexicalScore: number;
+    vectorScore: number;
+    recencyScore: number;
+};
+/** Embeds text into vectors for memory retrieval; provider-agnostic. */
+export type MemoryEmbedder = {
+    embed(texts: string[]): Promise<number[][]>;
+};
+/** A materialized read-only snapshot of the canonical project-memory database. */
+export type CanonicalMemorySnapshot = {
+    repoPath: string;
+    baseOid: string;
+    dbPath: string;
+    createdFresh: boolean;
+    cleanup(): Promise<void>;
+};
+/**
+ * Minimal telemetry sink the memory command emits run events through. The
+ * substrate's concrete event bus (`@rig/runtime` `EventBusLike`) is a superset
+ * and is structurally assignable to this; the memory contract only depends on
+ * `emit`, so the pure contract stays free of any runtime/behaviour import.
+ */
+export interface MemoryCommandEventSink {
+    emit<TPayload extends Record<string, unknown>>(type: string, payload: TPayload): Promise<unknown>;
+}
+/** Options for the agent-facing `rig-agent memory <verb>` command dispatch. */
+export type ExecuteMemoryCommandOptions = {
+    projectRoot: string;
+    taskId: string;
+    runtimeContext: RuntimeTaskContext | null;
+    args: string[];
+    eventBus?: MemoryCommandEventSink;
+};
+/** The retrieval-query shape the substrate passes through to the impl. */
+export type MemoryQueryPortInput = {
+    query: string;
+    limit?: number;
+    retrieval?: RuntimeMemoryRetrievalConfig;
+};
+/**
+ * The cohesive set of shared-memory operations the runtime consumers depend on.
+ * This is pure capability VOCAB: the `@rig/memory-plugin` provides a concrete
+ * impl (statically checked against this interface via `MemoryCap.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 MemoryService {
+    executeMemoryCommand(options: ExecuteMemoryCommandOptions): Promise<string>;
+    readCanonicalMemoryDb(projectRoot: string): Promise<CanonicalMemorySnapshot>;
+    openMemoryDb(dbPath: string): Promise<MemoryDb>;
+    queryRelevantMemory(db: MemoryDb, input: MemoryQueryPortInput): Promise<MemoryQueryResult[]>;
+    formatMemoryQueryResults(results: MemoryQueryResult[]): string;
+}
+/**
+ * The typed capability id the memory plugin provides and consumers require.
+ * Phantom-typed with `MemoryService` so `MemoryCap.require(host)` returns a
+ * `MemoryService` with no cast leaking to callers. Its string value is
+ * {@link MEMORY_SERVICE_CAPABILITY_ID}, so it indexes the same host entry.
+ */
+export declare const MEMORY: CapabilityId<MemoryService>;
+export {};

package/dist/src/memory.js

@@ -0,0 +1,15 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/memory.ts
+var MEMORY_SERVICE_CAPABILITY_ID = "memory.service";
+var NO_MATCH_RETRIEVAL_CANONICAL_KEY = "__memory_recall__:none";
+var MEMORY = makeCapabilityId(MEMORY_SERVICE_CAPABILITY_ID);
+export {
+  NO_MATCH_RETRIEVAL_CANONICAL_KEY,
+  MEMORY_SERVICE_CAPABILITY_ID,
+  MEMORY
+};