@h-rig/contracts 0.0.6-alpha.164 → 0.0.6-alpha.166

package/dist/src/task-artifacts.d.ts

@@ -0,0 +1,33 @@
+import type { CapabilityId } from "./capability-id";
+import type { TaskArtifactReadResult } from "./task-data";
+export type TaskArtifactRef = {
+    readonly projectRoot: string;
+    readonly taskId?: string;
+};
+export type TaskArtifactListEntry = {
+    readonly path: string;
+    readonly sizeBytes: number;
+    readonly kind: "file" | "directory" | "other";
+    readonly modifiedAt?: string | null;
+};
+export type TaskArtifactWriteInput = TaskArtifactRef & {
+    readonly filename: string;
+    readonly content: string;
+};
+export type TaskArtifactReadInput = TaskArtifactRef & {
+    readonly filename: string;
+    readonly maxBytes?: number;
+};
+export type TaskArtifactWriteResult = {
+    readonly path: string;
+    readonly sizeBytes: number;
+};
+/** Task artifact directory/list/read/write vocabulary. */
+export interface TaskArtifactsService {
+    artifactDir(input: TaskArtifactRef): string;
+    listArtifacts(input: TaskArtifactRef): Promise<readonly TaskArtifactListEntry[]>;
+    readArtifact(input: TaskArtifactReadInput): Promise<TaskArtifactReadResult>;
+    writeArtifact(input: TaskArtifactWriteInput): Promise<TaskArtifactWriteResult>;
+}
+export declare const TASK_ARTIFACTS_CAPABILITY_ID = "task-state.artifacts";
+export declare const TASK_ARTIFACTS: CapabilityId<TaskArtifactsService>;

package/dist/src/task-artifacts.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/task-artifacts.ts
+var TASK_ARTIFACTS_CAPABILITY_ID = "task-state.artifacts";
+var TASK_ARTIFACTS = makeCapabilityId(TASK_ARTIFACTS_CAPABILITY_ID);
+export {
+  TASK_ARTIFACTS_CAPABILITY_ID,
+  TASK_ARTIFACTS
+};

package/dist/src/task-context-renderer.d.ts

@@ -0,0 +1,29 @@
+import type { CapabilityId } from "./capability-id";
+import type { RuntimeInstructionProvider } from "./provider-instructions";
+import type { RigTask, TaskRecord } from "./task-source";
+export type TaskContextRenderInput = {
+    readonly projectRoot: string;
+    readonly taskId?: string;
+    readonly task?: RigTask | TaskRecord | null;
+    readonly provider?: RuntimeInstructionProvider;
+};
+export type TaskScopeRenderInput = TaskContextRenderInput & {
+    readonly expandFiles?: boolean;
+};
+export type TaskPromptContextSection = {
+    readonly title: string;
+    readonly content: string;
+};
+export type TaskPromptContext = {
+    readonly taskId: string | null;
+    readonly sections: readonly TaskPromptContextSection[];
+};
+/** Provider/prompt-owned task info, scope, and dependency rendering vocabulary. */
+export interface TaskContextRendererService {
+    renderTaskInfo(input: TaskContextRenderInput): Promise<TaskPromptContextSection>;
+    renderTaskScope(input: TaskScopeRenderInput): Promise<TaskPromptContextSection>;
+    renderTaskDependencies(input: TaskContextRenderInput): Promise<TaskPromptContextSection>;
+    renderPromptContext(input: TaskContextRenderInput): Promise<TaskPromptContext>;
+}
+export declare const TASK_CONTEXT_RENDERER_CAPABILITY_ID = "provider.task-context-renderer";
+export declare const TASK_CONTEXT_RENDERER: CapabilityId<TaskContextRendererService>;

package/dist/src/task-context-renderer.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/task-context-renderer.ts
+var TASK_CONTEXT_RENDERER_CAPABILITY_ID = "provider.task-context-renderer";
+var TASK_CONTEXT_RENDERER = makeCapabilityId(TASK_CONTEXT_RENDERER_CAPABILITY_ID);
+export {
+  TASK_CONTEXT_RENDERER_CAPABILITY_ID,
+  TASK_CONTEXT_RENDERER
+};

package/dist/src/task-data.d.ts

@@ -1,23 +1,33 @@
 /**
- * The TASK-DATA capability seam.
+ * The TASK_DATA compatibility-facade seam.
  *
- * Floor-neutral vocab + a single `CapabilityId<TaskDataService>` describing the
- * task-DATA reads and task-command behaviours the lifecycle, scheduler,
- * isolation provisioning, repos, workspace, and CLI surfaces consume. The
- * READ/normalize/validate POLICY behind each method (synchronize task-config,
- * strip metadata, tracker projection, validator dispatch, artifact IO) is owned
- * by `@rig/task-sources-plugin`, which `defineCapability(TASK_DATA_SERVICE_CAPABILITY).provide`s
- * the impl. Consumers `resolve`/`require` it off a built plugin host (or read the
- * boot-installed singleton) WITHOUT importing the provider plugin — this is the
- * seam that replaces the cross-plugin `import("@rig/task-sources-plugin/...")`
- * impl imports (SEAM-ONLY §6.4).
+ * Floor-neutral vocab + a single `CapabilityId<TaskDataService>` for legacy
+ * task-data reads and task-command behaviours consumed by lifecycle, scheduler,
+ * isolation provisioning, repos, workspace, and CLI surfaces. Source adapters
+ * own real source IO through their dedicated seams; local task state, metadata,
+ * artifact IO, and tracker reads own their semantic capabilities in
+ * `@rig/task-state-plugin`.
  *
- * Pure: types + one branded id, no behaviour.
+ * Ownership intent: `@rig/task-io-plugin` is the target owner for this legacy
+ * facade because it aggregates task/source IO for old consumers. The temporary
+ * provider shim remains in `@rig/task-state-plugin` only because capability
+ * provider factories run as `FeatureCapability.run(undefined)` with no
+ * `PluginHost`/resolver context; the narrower task-state/artifact/tracker
+ * capabilities are not boot-installed, and this facade still includes
+ * synchronous methods. Without a host-aware provider seam, task-io cannot compose
+ * `TASK_STATE_STORE`, `TASK_ARTIFACTS`, and `TASK_TRACKER_STATE` without a
+ * forbidden plugin-to-plugin implementation import.
+ *
+ * Consumers `resolve`/`require` task data off a built plugin host (or read the
+ * boot-installed singleton) WITHOUT importing the provider plugin. When provider
+ * execution becomes host-aware, move only the facade provider to task-io and keep
+ * the semantic state/artifact/tracker services in task-state.
+ *
+ * Pure: types + one branded legacy id, no behaviour.
  */
 import type { CapabilityId } from "./capability-id";
 import type { TaskConfigEntry, TaskRecord, RegisteredTaskSource, TaskSourceUpdate } from "./task-source";
 import type { TaskRecordReader } from "./isolation";
-import type { RuntimeInstructionProvider } from "./provider-instructions";
 import type { CanonicalTaskLifecycleStatus, TaskStateMetadataEnvelope } from "./task-state-metadata";
 /** Result of a bounded artifact-file read (preview + truncation metadata). */
 export type TaskArtifactReadResult = {
@@ -75,6 +85,11 @@ export type SyncedTrackerSnapshot = {
 export type ReadSyncedTrackerOptions = {
     allowLocalFallback?: boolean;
 };
+export type SourceAwareTaskConfigReadOptions = {
+    readonly configPath?: string;
+    readonly ghBinary?: string;
+    readonly allowLocalTaskConfigStatusFallback?: boolean;
+};
 /** Result of resolving a single task through the configured task source. */
 export type TaskSourceTaskReadResult = {
     configured: boolean;
@@ -106,45 +121,6 @@ export type TaskSourceLifecycleUpdateResult = {
     status: unknown;
     projectSync?: unknown;
 };
-/** Input for rendering a task-run lifecycle status comment. */
-export type TaskRunLifecycleCommentInput = {
-    runId: string;
-    status: string;
-    summary: string;
-    runtimeWorkspace?: string | null;
-    logsDir?: string | null;
-    sessionDir?: string | null;
-    errorText?: string | null;
-};
-/** Boundary subset of the source-aware task-config reader options. */
-export type SourceAwareTaskConfigReadOptions = {
-    configPath?: string;
-    allowLocalTaskConfigStatusFallback?: boolean;
-};
-/**
- * The lifecycle status values a run reflects to the task source.
- * Mirrors the type defined in @rig/task-sources-plugin/source-lifecycle —
- * lives here so @rig/run-exec can use it through the TaskDataService seam
- * without a cross-plugin impl import.
- */
-export type RunTaskSourceLifecycleStatus = "running" | "under_review" | "ci_fixing" | "merging" | "closed" | "cancelled" | "needs_attention";
-/**
- * The run identity fields passed when reflecting a run lifecycle event to the
- * task source.
- */
-export type RunTaskSourceLifecycleRun = {
-    runId?: string | null;
-    taskId?: string | null;
-    sourceTask?: unknown;
-    worktreePath?: string | null;
-    logRoot?: string | null;
-    sessionPath?: string | null;
-    errorText?: string | null;
-};
-/** Optional overrides for a run lifecycle update. */
-export type RunTaskSourceLifecycleOptions = {
-    errorText?: string | null;
-};
 /** Context for building a plugin-backed task-record reader. */
 export type PluginTaskRecordReaderContext = {
     taskSourceRegistry: {
@@ -160,17 +136,22 @@ export type PluginTaskRecordReaderOptions = {
     sourceKind?: string;
 };
 /**
- * The task-DATA service contributed by `@rig/task-sources-plugin`. Every method
- * is keyed by `projectRoot` (the service is stateless), so it is safe to install
- * as a boot singleton and read synchronously by substrate consumers.
+ * Legacy TASK_DATA compatibility facade.
+ *
+ * The shape intentionally remains broad while callers migrate to narrower
+ * semantic capabilities. Every method is keyed by `projectRoot` (the service is
+ * stateless), so the current provider can be installed as a boot singleton and
+ * read synchronously by substrate consumers.
  */
 export interface TaskDataService {
     currentTaskId(projectRoot: string): string;
     readTaskConfig(projectRoot: string): Record<string, TaskConfigEntry>;
     readSourceTaskConfig(projectRoot: string): Record<string, TaskConfigEntry>;
+    readValidationDescriptions(projectRoot: string): Record<string, string>;
     lookupTask(projectRoot: string, input: string): string;
     artifactDirForId(projectRoot: string, id: string): string;
-    taskInfo(projectRoot: string, taskId?: string, runtimeProviderOverride?: RuntimeInstructionProvider): Promise<void>;
+    /** @deprecated Third argument is ignored; runtime/provider instruction ownership lives outside TASK_DATA. */
+    taskInfo(projectRoot: string, taskId?: string, deprecatedRuntimeProviderOverride?: unknown): Promise<void>;
     taskDeps(projectRoot: string, taskId?: string): Promise<void>;
     taskStatus(projectRoot: string): void;
     taskScope(projectRoot: string, expandFiles: boolean, taskId?: string): Promise<void>;
@@ -182,7 +163,6 @@ export interface TaskDataService {
         taskId?: string;
         dryRun?: boolean;
     }): TaskReopenSummary;
-    taskValidate(projectRoot: string, taskId?: string, validatorRegistry?: unknown): Promise<boolean>;
     taskArtifacts(projectRoot: string, taskId?: string): void;
     taskArtifactDir(projectRoot: string, taskId?: string): string;
     taskArtifactWrite(projectRoot: string, filename: string, content: string, taskId?: string): void;
@@ -200,27 +180,6 @@ export interface TaskDataService {
         sourceTask?: SourceTaskIdentity | null;
         update: TaskSourceUpdate;
     }): Promise<TaskSourceLifecycleUpdateResult>;
-    buildTaskRunLifecycleComment(input: TaskRunLifecycleCommentInput): string;
-    /**
-     * Compat fallback: push an update to a github-issues-backed task by parsing
-     * its `owner/repo#n` source-issue id. Returns false when the id does not match
-     * the taskId. Exposed on the seam so the kernel agent-launch executor can apply
-     * the source-aware compatibility update without importing the provider plugin.
-     */
-    updateGithubIssueTaskBySourceIssueId(sourceIssueId: string | null | undefined, taskId: string, update: TaskSourceUpdate): boolean;
-    /**
-     * Compat fallback: push a status/comment update through the source-aware
-     * task-config (github-issues, files, or legacy task-config). Returns false when
-     * no writable source is configured. Seam-exposed for the kernel executor.
-     */
-    updateSourceAwareTaskConfigTask(projectRoot: string, taskId: string, update: TaskSourceUpdate): boolean;
-    /**
-     * Reflect a run lifecycle event (start/stop/closeout) to the configured task
-     * source. Returns null when no taskId is present or no source is configured.
-     * Exposed on the seam so @rig/run-exec can call it without importing
-     * @rig/task-sources-plugin impl files directly (SEAM-ONLY §6.4).
-     */
-    updateRunTaskSourceLifecycle(projectRoot: string, run: RunTaskSourceLifecycleRun, status: RunTaskSourceLifecycleStatus, summary: string, options?: RunTaskSourceLifecycleOptions): Promise<TaskSourceLifecycleUpdateResult | null>;
     createLegacyTaskConfigRecordReader(projectRoot: string, options?: {
         configPath?: string;
     }): TaskRecordReader;
@@ -230,7 +189,7 @@ export interface TaskDataService {
     listReadyTaskIdsFromTracker(snapshot: SyncedTrackerSnapshot): string[];
     normalizeTaskLifecycleStatus(status: unknown): CanonicalTaskLifecycleStatus | null;
 }
-/** Stable id string for the task-data service capability. */
+/** Stable legacy id string for the TASK_DATA compatibility facade. */
 export declare const TASK_DATA_SERVICE_CAPABILITY_ID = "task-sources.task-data";
 /**
  * The branded task-data capability id. `defineCapability(TASK_DATA_SERVICE_CAPABILITY)`

package/dist/src/task-source.d.ts

@@ -3,9 +3,8 @@ import type { TaskSourceRegistration } from "./plugin";
 import type { TaskBrowserConfig } from "./browser";
 /**
  * A single entry in the on-disk task-config map (`.rig/task-config.json`).
- * Floor-neutral DATA shape. The READ/normalize POLICY (synchronize, strip
- * metadata, validation-description extraction) is owned by
- * @rig/task-sources-plugin (`task-state`), NOT the floor.
+ * Floor-neutral DATA shape. Read/normalize/local-state policy is intentionally
+ * outside this contract and belongs to the plugin that provides that domain.
  */
 export type TaskConfigEntry = {
     title?: string;
@@ -34,10 +33,9 @@ export interface TaskRecord {
 }
 /**
  * The NORMALIZED, surface-facing task shape (the projection consumers read).
- * The TYPE is floor-neutral vocab and lives here in contracts; the
- * normalization POLICY that produces it (field-mapping a raw `TaskRecord` into
- * this shape — title/body/url/dependency fallback chains) is owned by
- * @rig/task-sources-plugin (`toRigTask`), NOT by the floor.
+ * The TYPE is floor-neutral vocab and lives here in contracts; the normalization
+ * implementation is provided by the task IO owner, not by the source-adapter
+ * plugin.
  */
 export type RigTask = {
     readonly id: string;
@@ -56,11 +54,23 @@ export type RigTask = {
 };
 /** Alias retained for call sites that accept any task-like projection. */
 export type TaskLike = RigTask;
+export type TaskSourceLabelUpdate = {
+    readonly add?: readonly string[];
+    readonly remove?: readonly string[];
+};
 /**
- * A registered task source adapter — combines the plugin-level registration
- * metadata with the runtime-callable interface.
+ * Explicit provider-owned source update payload. Reflection code should
+ * project intent into these concrete source write values before calling adapters.
  */
-export interface TaskSourceUpdate {
+export interface TaskSourceProjectedUpdate {
+    labels?: TaskSourceLabelUpdate;
+    sourceFields?: Record<string, string | null | undefined>;
+    close?: boolean;
+    assignToDefault?: boolean;
+}
+/** Generic provider-owned source update payload. */
+export interface TaskSourceUpdate extends TaskSourceProjectedUpdate {
+    /** @deprecated Prefer explicit projected update fields for source writeback. */
     status?: TaskRecord["status"];
     title?: string;
     body?: string;
@@ -75,6 +85,31 @@ export interface TaskSourceCreateInput {
     metadata?: Record<string, unknown>;
 }
 export type TaskSourceCreateResult = TaskRecord;
+export type TaskSourceUpdateRequest = {
+    readonly projectRoot: string;
+    readonly taskId: string;
+    readonly sourceId?: string | null;
+    readonly sourceKind?: string | null;
+    readonly update: TaskSourceUpdate;
+};
+export type TaskSourceUpdateResult = {
+    readonly taskId: string;
+    readonly updated: boolean;
+    readonly sourceId?: string | null;
+    readonly sourceKind?: string | null;
+    readonly result?: unknown;
+};
+/**
+ * Generic source-adapter writeback port. The legacy id string is retained, but
+ * implementations should only dispatch to configured source adapters; local task
+ * state, normalized task IO, source reflection, and validation policy are
+ * owned by their respective plugins.
+ */
+export interface TaskSourceUpdateService {
+    updateTask(input: TaskSourceUpdateRequest): Promise<TaskSourceUpdateResult>;
+}
+export declare const TASK_SOURCE_UPDATE_CAPABILITY_ID = "task-sources.update";
+export declare const TASK_SOURCE_UPDATE: CapabilityId<TaskSourceUpdateService>;
 export interface RegisteredTaskSource extends TaskSourceRegistration {
     list(): Promise<readonly TaskRecord[]>;
     get?(id: string): Promise<TaskRecord | undefined>;
@@ -88,10 +123,9 @@ export type TaskIoCreateResult = {
     readonly result: unknown;
 };
 /**
- * Source-owned task IO projection seam. Providers normalize raw task-source
- * records into RigTask and adapt generic task creation payloads to the
- * configured source; consumers resolve this instead of importing @rig/core
- * task-source glue.
+ * Normalized task IO projection seam. The historical id string is retained for
+ * compatibility, but this capability is owned/provided by @rig/task-io-plugin;
+ * source-adapter plugins should contribute adapters and source writeback only.
  */
 export interface TaskIoService {
     listTasks(projectRoot: string): Promise<readonly RigTask[]>;

package/dist/src/task-source.js

@@ -5,9 +5,13 @@ function makeCapabilityId(id) {
 }
 
 // packages/contracts/src/task-source.ts
+var TASK_SOURCE_UPDATE_CAPABILITY_ID = "task-sources.update";
+var TASK_SOURCE_UPDATE = makeCapabilityId(TASK_SOURCE_UPDATE_CAPABILITY_ID);
 var TASK_IO_SERVICE_CAPABILITY_ID = "task-sources.task-io";
 var TASK_IO_SERVICE_CAPABILITY = makeCapabilityId(TASK_IO_SERVICE_CAPABILITY_ID);
 export {
+  TASK_SOURCE_UPDATE_CAPABILITY_ID,
+  TASK_SOURCE_UPDATE,
   TASK_IO_SERVICE_CAPABILITY_ID,
   TASK_IO_SERVICE_CAPABILITY
 };

package/dist/src/task-state-store.d.ts

@@ -0,0 +1,16 @@
+import type { CapabilityId } from "./capability-id";
+import type { TaskConfigEntry } from "./task-source";
+import type { TaskStateMetadataEnvelope } from "./task-state-metadata";
+/** Local `.rig` task state/config/metadata only; no runtime/provider guidance. */
+export interface TaskStateStoreService {
+    readCurrentTaskId(projectRoot: string): string | null;
+    writeCurrentTaskId(projectRoot: string, taskId: string | null): void;
+    readTaskConfig(projectRoot: string): Record<string, TaskConfigEntry>;
+    writeTaskConfig(projectRoot: string, entries: Record<string, TaskConfigEntry>): void;
+    readSourceTaskConfig(projectRoot: string): Record<string, TaskConfigEntry>;
+    writeSourceTaskConfig(projectRoot: string, entries: Record<string, TaskConfigEntry>): void;
+    readTaskStateMetadata(projectRoot: string): TaskStateMetadataEnvelope | null;
+    writeTaskStateMetadata(projectRoot: string, envelope: TaskStateMetadataEnvelope): void;
+}
+export declare const TASK_STATE_STORE_CAPABILITY_ID = "task-state.store";
+export declare const TASK_STATE_STORE: CapabilityId<TaskStateStoreService>;

package/dist/src/task-state-store.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/task-state-store.ts
+var TASK_STATE_STORE_CAPABILITY_ID = "task-state.store";
+var TASK_STATE_STORE = makeCapabilityId(TASK_STATE_STORE_CAPABILITY_ID);
+export {
+  TASK_STATE_STORE_CAPABILITY_ID,
+  TASK_STATE_STORE
+};

package/dist/src/task-tracker-state.d.ts

@@ -0,0 +1,106 @@
+import type { CapabilityId } from "./capability-id";
+import type { CanonicalTaskLifecycleStatus, TaskStateMetadata, TaskStateMetadataEnvelope } from "./task-state-metadata";
+import type { SyncedTrackerSnapshot, ReadSyncedTrackerOptions } from "./task-data";
+export declare const TASK_TRACKER_LIFECYCLE_STATUSES: readonly ["draft", "open", "ready", "queued", "in_progress", "under_review", "blocked", "completed", "cancelled"];
+export declare const TASK_TRACKER_STALE_CLAIM_MS: number;
+export type TaskTrackerPolicyDecision = {
+    readonly allowed: boolean;
+    readonly code?: "claim-conflict" | "status-conflict";
+    readonly reason?: string;
+};
+export type TrackerPullRequestEvidence = {
+    readonly branchName?: string | null;
+    readonly prNumber?: number | null;
+    readonly prUrl?: string | null;
+    readonly isOpen?: boolean;
+    readonly isMerged?: boolean;
+    readonly reviewState?: string | null;
+};
+export type TrackerReconcileEvidence = {
+    readonly now?: string;
+    readonly closeoutPassed?: boolean;
+    readonly pr?: TrackerPullRequestEvidence | null;
+    readonly activeOwnerIds?: readonly string[];
+};
+export type TaskReconciliationProjection = {
+    readonly valid: boolean;
+    readonly reasons: readonly string[];
+    readonly isStale: boolean;
+    readonly wouldReconcileTo: CanonicalTaskLifecycleStatus | null;
+    readonly nextMetadata: TaskStateMetadata | null;
+};
+export type TaskTrackerReconciliationPolicyInput = {
+    readonly lifecycleStatus: CanonicalTaskLifecycleStatus;
+    readonly metadata: TaskStateMetadata | null;
+    readonly evidence?: TrackerReconcileEvidence;
+    /**
+     * Explicit clock input keeps the lifecycle-owned projection deterministic.
+     */
+    readonly nowIso: string;
+};
+export type TaskTrackerClaimTransitionPolicyInput = {
+    readonly taskId: string;
+    readonly lifecycleStatus: CanonicalTaskLifecycleStatus;
+    readonly expectedStatus?: CanonicalTaskLifecycleStatus;
+};
+export type TaskTrackerLifecycleTransitionPolicyInput = {
+    readonly taskId: string;
+    readonly lifecycleStatus: CanonicalTaskLifecycleStatus;
+    readonly allowedFrom?: readonly CanonicalTaskLifecycleStatus[];
+};
+export interface TaskTrackerReconciliationPolicyService {
+    projectReconciliation(input: TaskTrackerReconciliationPolicyInput): TaskReconciliationProjection;
+    canUpdateLifecycle(input: TaskTrackerLifecycleTransitionPolicyInput): TaskTrackerPolicyDecision;
+}
+export declare const TASK_TRACKER_RECONCILIATION_POLICY_CAPABILITY_ID = "lifecycle.task-tracker-reconciliation-policy";
+export declare const TASK_TRACKER_RECONCILIATION_POLICY: CapabilityId<TaskTrackerReconciliationPolicyService>;
+export interface TaskTrackerReadinessPolicyService {
+    listReadyTaskIds(snapshot: SyncedTrackerSnapshot): readonly string[];
+    canClaimTask(input: TaskTrackerClaimTransitionPolicyInput): TaskTrackerPolicyDecision;
+}
+export declare const TASK_TRACKER_READINESS_POLICY_CAPABILITY_ID = "scheduler.task-tracker-readiness-policy";
+export declare const TASK_TRACKER_READINESS_POLICY: CapabilityId<TaskTrackerReadinessPolicyService>;
+export type TaskTrackerStateUpdateInput = {
+    readonly projectRoot: string;
+    readonly taskId: string;
+    readonly lifecycleStatus: CanonicalTaskLifecycleStatus;
+    readonly metadata?: TaskStateMetadata | null;
+    /** @deprecated OWNER-TODO: remove when callers pass reconciliation evidence only to TASK_TRACKER_RECONCILIATION_POLICY. */
+    readonly evidence?: TrackerReconcileEvidence;
+};
+export type TaskTrackerStateClaimInput = {
+    readonly projectRoot: string;
+    readonly taskId: string;
+    readonly ownerId: string;
+    readonly runId?: string | null;
+    readonly now?: string;
+};
+/**
+ * Tracker repository locator seam.
+ *
+ * Task-state owns tracker persistence and metadata storage only. Lifecycle and
+ * scheduler policy capabilities own reconciliation, stale-claim, readiness, and
+ * transition decisions; contracts provides the pure vocabulary/capability ids.
+ */
+export interface TaskTrackerRepoLocatorService {
+    resolveTrackerRepoPath(projectRoot: string): string;
+}
+export declare const TASK_TRACKER_REPO_LOCATOR_CAPABILITY_ID = "task-state.tracker-repo-locator";
+export declare const TASK_TRACKER_REPO_LOCATOR: CapabilityId<TaskTrackerRepoLocatorService>;
+/** Tracker snapshot/persistence API. Keep this shape stable for legacy callers. */
+export interface TaskTrackerStateService {
+    readSnapshot(projectRoot: string, options?: ReadSyncedTrackerOptions): SyncedTrackerSnapshot;
+    /** @deprecated Use TASK_TRACKER_READINESS_POLICY. OWNER-TODO: remove after scheduler queue consumers switch seams. */
+    listReadyTaskIds(snapshot: SyncedTrackerSnapshot): readonly string[];
+    normalizeStatus(status: unknown): CanonicalTaskLifecycleStatus | null;
+    /** @deprecated Use TASK_TRACKER_RECONCILIATION_POLICY. OWNER-TODO: remove after lifecycle consumers switch seams. */
+    projectReconciliation(input: {
+        readonly lifecycleStatus: CanonicalTaskLifecycleStatus;
+        readonly metadata: TaskStateMetadata | null;
+        readonly evidence?: TrackerReconcileEvidence;
+    }): TaskReconciliationProjection;
+    claimTask(input: TaskTrackerStateClaimInput): TaskStateMetadataEnvelope | Promise<TaskStateMetadataEnvelope>;
+    updateLifecycle(input: TaskTrackerStateUpdateInput): TaskStateMetadataEnvelope | Promise<TaskStateMetadataEnvelope>;
+}
+export declare const TASK_TRACKER_STATE_CAPABILITY_ID = "task-state.tracker-state";
+export declare const TASK_TRACKER_STATE: CapabilityId<TaskTrackerStateService>;

package/dist/src/task-tracker-state.js

@@ -0,0 +1,39 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/task-tracker-state.ts
+var TASK_TRACKER_LIFECYCLE_STATUSES = [
+  "draft",
+  "open",
+  "ready",
+  "queued",
+  "in_progress",
+  "under_review",
+  "blocked",
+  "completed",
+  "cancelled"
+];
+var TASK_TRACKER_STALE_CLAIM_MS = 24 * 60 * 60 * 1000;
+var TASK_TRACKER_RECONCILIATION_POLICY_CAPABILITY_ID = "lifecycle.task-tracker-reconciliation-policy";
+var TASK_TRACKER_RECONCILIATION_POLICY = makeCapabilityId(TASK_TRACKER_RECONCILIATION_POLICY_CAPABILITY_ID);
+var TASK_TRACKER_READINESS_POLICY_CAPABILITY_ID = "scheduler.task-tracker-readiness-policy";
+var TASK_TRACKER_READINESS_POLICY = makeCapabilityId(TASK_TRACKER_READINESS_POLICY_CAPABILITY_ID);
+var TASK_TRACKER_REPO_LOCATOR_CAPABILITY_ID = "task-state.tracker-repo-locator";
+var TASK_TRACKER_REPO_LOCATOR = makeCapabilityId(TASK_TRACKER_REPO_LOCATOR_CAPABILITY_ID);
+var TASK_TRACKER_STATE_CAPABILITY_ID = "task-state.tracker-state";
+var TASK_TRACKER_STATE = makeCapabilityId(TASK_TRACKER_STATE_CAPABILITY_ID);
+export {
+  TASK_TRACKER_STATE_CAPABILITY_ID,
+  TASK_TRACKER_STATE,
+  TASK_TRACKER_STALE_CLAIM_MS,
+  TASK_TRACKER_REPO_LOCATOR_CAPABILITY_ID,
+  TASK_TRACKER_REPO_LOCATOR,
+  TASK_TRACKER_RECONCILIATION_POLICY_CAPABILITY_ID,
+  TASK_TRACKER_RECONCILIATION_POLICY,
+  TASK_TRACKER_READINESS_POLICY_CAPABILITY_ID,
+  TASK_TRACKER_READINESS_POLICY,
+  TASK_TRACKER_LIFECYCLE_STATUSES
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h-rig/contracts",
-  "version": "0.0.6-alpha.164",
+  "version": "0.0.6-alpha.166",
   "type": "module",
   "description": "Rig package",
   "license": "UNLICENSED",