@h-rig/contracts 0.0.6-alpha.18 → 0.0.6-alpha.181

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

@@ -0,0 +1,339 @@
+/**
+ * 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,
+ * - `RepoGitBinaryService` under {@link REPO_GIT_BINARY_CAPABILITY_ID} for
+ *   the repo-owned rig-git helper binary, and
+ * - `RepoTrackerPersistenceService` under {@link REPO_TRACKER_PERSISTENCE_CAPABILITY_ID}
+ *   for mechanical tracker snapshot reads and owner-supplied mutation persistence.
+ *
+ * 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";
+import type { SyncedTrackerSnapshot, ReadSyncedTrackerOptions } from "./task-data";
+import type { CanonicalTaskLifecycleStatus, TaskStateMetadata } from "./task-state-metadata";
+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 sourceFilePath: string;
+    readonly executable?: boolean;
+} | {
+    readonly path: string;
+    readonly delete: true;
+};
+export type RepoNativeGitPendingFile = {
+    readonly path: string;
+    readonly status: string;
+};
+export type RepoNativeGitCommandResult = {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+};
+export type RepoNativeGitRunOptions = {
+    /** Project root used to derive runtime git environment/secrets when different from repoPath. */
+    readonly projectRoot?: string;
+    readonly input?: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+};
+export type RepoNativeGitCommitOptions = {
+    readonly message: string;
+    readonly allowEmpty?: boolean;
+    /** Explicit repo-relative paths to stage. Provider may use pathspec files to avoid argv limits. */
+    readonly paths?: readonly string[];
+    /** Stage all repo changes except excludes when no explicit paths are provided. */
+    readonly stageAll?: boolean;
+    readonly excludePathspecs?: readonly string[];
+    readonly projectRoot?: string;
+};
+export type RepoNativeGitCommitResult = {
+    readonly committed: boolean;
+    readonly status: string;
+    readonly stagedChangeCount: number;
+    readonly stagedPathCount: number;
+};
+export type RepoNativeGitCheckoutOptions = {
+    readonly createIfMissing?: boolean;
+    readonly resetIfDetachedExisting?: boolean;
+    readonly projectRoot?: string;
+};
+export type RepoNativeGitPushBranchOptions = {
+    readonly remote?: string;
+    readonly setUpstream?: boolean;
+    readonly forceWithLease?: boolean;
+    readonly projectRoot?: string;
+};
+export type RepoNativeGitRemoteDispatchCheckoutInput = {
+    /**
+     * Shell expression for the checkout path, e.g. "$CHECKOUT" or "$HOME/.rig/checkouts/repo".
+     * The caller owns quoting this path expression before passing it across the seam.
+     */
+    readonly checkoutExpression: string;
+    /** Shell expression that points at the materialized github-auth.json temp file. */
+    readonly authStateFileExpression: string;
+    /** Shell expression that points at a temp executable credential-helper file. */
+    readonly credentialHelperFileExpression: string;
+    readonly originUrl?: string | null;
+    readonly operatorHead: string;
+};
+/**
+ * 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. Lifecycle and other consumers keep policy decisions but
+ * delegate checkout/stage/commit/fetch/push mechanics through this capability.
+ */
+export interface RepoNativeGitService {
+    run(repoPath: string, args: readonly string[], options?: RepoNativeGitRunOptions): RepoNativeGitCommandResult;
+    branchName(repoPath: string, projectRoot?: string): string | null;
+    headOid(repoPath: string, projectRoot?: string): string | null;
+    githubOriginSlug(repoPath: string, projectRoot?: string): string | null;
+    changeCount(repoPath: string, projectRoot?: string): number | null;
+    pendingFiles(repoPath: string, projectRoot?: string): readonly RepoNativeGitPendingFile[] | null;
+    fileHasChanges(repoPath: string, filePath: string, projectRoot?: string): boolean | null;
+    checkoutBranch(repoPath: string, branch: string, options?: RepoNativeGitCheckoutOptions): RepoNativeGitCommandResult;
+    commit(repoPath: string, options: RepoNativeGitCommitOptions): RepoNativeGitCommitResult;
+    pushBranch(repoPath: string, branch: string, options?: RepoNativeGitPushBranchOptions): RepoNativeGitCommandResult;
+    remoteDispatchCheckoutShell(input: RepoNativeGitRemoteDispatchCheckoutInput): readonly string[];
+    fetchRef(repoPath: string, remote: string, branch: string): string;
+    readBlobAtRef(repoPath: string, ref: string, path: string): string;
+    readBlobBytesAtRef(repoPath: string, ref: string, path: string): Uint8Array;
+    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;
+    recordTaskRepoCommits(projectRoot: string, taskId: string): void;
+    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>;
+export type RepoTrackerPersistenceMutationResult = {
+    readonly outcome: "applied" | "noop";
+    readonly snapshot: SyncedTrackerSnapshot;
+    readonly commitOid: string | null;
+};
+export type RepoTrackerPersistenceMutation = {
+    readonly taskId: string;
+    readonly lifecycleStatus: CanonicalTaskLifecycleStatus;
+    readonly metadata?: TaskStateMetadata | null;
+    /** Mechanical owner-supplied compare-and-set precondition. */
+    readonly expectedLifecycleStatus?: CanonicalTaskLifecycleStatus | readonly CanonicalTaskLifecycleStatus[];
+};
+export type RepoTrackerPersistenceMutationsInput = {
+    readonly projectRoot: string;
+    readonly mutations: readonly RepoTrackerPersistenceMutation[];
+    readonly reason?: string;
+};
+export interface RepoTrackerPersistenceService {
+    readSnapshot(projectRoot: string, options?: ReadSyncedTrackerOptions): SyncedTrackerSnapshot;
+    persistMutations(input: RepoTrackerPersistenceMutationsInput): RepoTrackerPersistenceMutationResult;
+}
+export declare const REPO_TRACKER_PERSISTENCE_CAPABILITY_ID = "repos.tracker-persistence";
+export declare const REPO_TRACKER_PERSISTENCE: CapabilityId<RepoTrackerPersistenceService>;
+/** 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,37 @@
+// @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 REPO_TRACKER_PERSISTENCE_CAPABILITY_ID = "repos.tracker-persistence";
+var REPO_TRACKER_PERSISTENCE = makeCapabilityId(REPO_TRACKER_PERSISTENCE_CAPABILITY_ID);
+var MANAGED_REPO_SERVICE_CAPABILITY_ID = "managed-repos.service";
+var MANAGED_REPO_SERVICE_CAPABILITY = makeCapabilityId(MANAGED_REPO_SERVICE_CAPABILITY_ID);
+export {
+  REPO_TRACKER_PERSISTENCE_CAPABILITY_ID,
+  REPO_TRACKER_PERSISTENCE,
+  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
+};

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
+};

package/dist/src/model.d.ts

@@ -0,0 +1,13 @@
+import { Schema } from "effect";
+/**
+ * Provider model vocabulary shared by the transport contract.
+ *
+ * Concrete model catalogs, aliases, defaults, and reasoning-effort policy are
+ * runtime/provider ownership concerns and live in `@rig/provider-plugin/model`.
+ * The contract layer intentionally accepts opaque model slugs/options so new
+ * provider packages can evolve without changing the floor package.
+ */
+export declare const ModelSlug: Schema.String;
+export type ModelSlug = typeof ModelSlug.Type;
+export declare const ProviderModelOptions: Schema.$Record<Schema.String, Schema.Unknown>;
+export type ProviderModelOptions = typeof ProviderModelOptions.Type;

package/dist/src/model.js

@@ -1,64 +1,9 @@
 // @bun
 // packages/contracts/src/model.ts
 import { Schema } from "effect";
-var CODEX_REASONING_EFFORT_OPTIONS = ["xhigh", "high", "medium", "low"];
-var CodexModelOptions = Schema.Struct({
-  reasoningEffort: Schema.optional(Schema.Literals(CODEX_REASONING_EFFORT_OPTIONS)),
-  fastMode: Schema.optional(Schema.Boolean)
-});
-var ClaudeModelOptions = Schema.Struct({});
-var ProviderModelOptions = Schema.Struct({
-  codex: Schema.optional(CodexModelOptions),
-  claude: Schema.optional(ClaudeModelOptions)
-});
-var MODEL_OPTIONS_BY_PROVIDER = {
-  codex: [
-    { slug: "gpt-5.4", name: "GPT-5.4" },
-    { slug: "gpt-5.3-codex", name: "GPT-5.3 Codex" },
-    { slug: "gpt-5.3-codex-spark", name: "GPT-5.3 Codex Spark" },
-    { slug: "gpt-5.2-codex", name: "GPT-5.2 Codex" },
-    { slug: "gpt-5.2", name: "GPT-5.2" }
-  ],
-  claude: [
-    { slug: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" },
-    { slug: "claude-opus-4-1", name: "Claude Opus 4.1" },
-    { slug: "claude-3-7-sonnet-latest", name: "Claude 3.7 Sonnet" }
-  ]
-};
-var DEFAULT_MODEL_BY_PROVIDER = {
-  codex: "gpt-5.4",
-  claude: "claude-sonnet-4-6"
-};
-var MODEL_SLUG_ALIASES_BY_PROVIDER = {
-  codex: {
-    "5.4": "gpt-5.4",
-    "5.3": "gpt-5.3-codex",
-    "gpt-5.3": "gpt-5.3-codex",
-    "5.3-spark": "gpt-5.3-codex-spark",
-    "gpt-5.3-spark": "gpt-5.3-codex-spark"
-  },
-  claude: {
-    sonnet: "claude-sonnet-4-6",
-    opus: "claude-opus-4-1",
-    "3.7-sonnet": "claude-3-7-sonnet-latest"
-  }
-};
-var REASONING_EFFORT_OPTIONS_BY_PROVIDER = {
-  codex: CODEX_REASONING_EFFORT_OPTIONS,
-  claude: []
-};
-var DEFAULT_REASONING_EFFORT_BY_PROVIDER = {
-  codex: "high",
-  claude: null
-};
+var ModelSlug = Schema.String;
+var ProviderModelOptions = Schema.Record(Schema.String, Schema.Unknown);
 export {
-  REASONING_EFFORT_OPTIONS_BY_PROVIDER,
   ProviderModelOptions,
-  MODEL_SLUG_ALIASES_BY_PROVIDER,
-  MODEL_OPTIONS_BY_PROVIDER,
-  DEFAULT_REASONING_EFFORT_BY_PROVIDER,
-  DEFAULT_MODEL_BY_PROVIDER,
-  CodexModelOptions,
-  ClaudeModelOptions,
-  CODEX_REASONING_EFFORT_OPTIONS
+  ModelSlug
 };