agentic-orchestrator 0.1.28 → 0.2.0

package/specs/002-scope-aware-lease/data-model.md

@@ -0,0 +1,236 @@
+# Data Model: Scope-Aware Run Lease
+
+**Feature Branch**: `002-scope-aware-lease`
+
+---
+
+## New Types (additions to `apps/control-plane/src/core/runtime-sessions.ts`)
+
+### `LeaseScope`
+
+Represents the declared set of codebase sections a run expects to read or modify.
+
+| Field              | Type       | Required | Description                                                                                                   |
+| ------------------ | ---------- | -------- | ------------------------------------------------------------------------------------------------------------- |
+| `paths`            | `string[]` | ✅       | File-system paths relative to `repoRoot`. Prefix-matched for overlap detection. Trailing slash is normalized. |
+| `plan_section_ids` | `string[]` | ✅       | Plan section identifiers. Equality-matched (opaque strings, no hierarchy).                                    |
+
+**Invariants**:
+
+- Both arrays may be empty (explicit "touches nothing" declaration).
+- Paths must be relative to the repository root (no absolute paths, no `..` traversal).
+- Plan section IDs are opaque; no canonicalization applied.
+
+```typescript
+export interface LeaseScope {
+  paths: string[];
+  plan_section_ids: string[];
+}
+```
+
+---
+
+### `LeaseScopeDeclaration`
+
+Union type that captures all valid scope states.
+
+```typescript
+export type LeaseScopeDeclaration = LeaseScope | null;
+// null  → unknown/undeclared scope → conservative: conflicts with all active leases
+// LeaseScope with empty arrays → explicitly empty → conflicts with nothing
+// LeaseScope with entries → checked via prefix overlap / equality
+```
+
+**State semantics**:
+
+| Value                                 | Meaning                      | Blocks if any active lease? |
+| ------------------------------------- | ---------------------------- | --------------------------- |
+| `null`                                | Unknown scope (not declared) | Always blocks               |
+| `{ paths: [], plan_section_ids: [] }` | Touches nothing              | Never blocks                |
+| `{ paths: ["packages/auth/"], ... }`  | Specific scope               | Only if overlap detected    |
+
+---
+
+### `ActiveLeaseRecord`
+
+One entry in the global Lease Registry. Represents an active (or recently acquired) run lease.
+
+| Field               | Type                    | Required | Description                                                                             |
+| ------------------- | ----------------------- | -------- | --------------------------------------------------------------------------------------- |
+| `run_id`            | `string`                | ✅       | Unique identifier of the run (matches `RuntimeSessionsSnapshot.run_id`)                 |
+| `owner_instance_id` | `string`                | ✅       | Owning orchestrator instance identifier                                                 |
+| `instance_id`       | `string`                | ✅       | Kernel `instanceId` (config-path-derived hash); used for per-instance file correlation  |
+| `scope`             | `LeaseScopeDeclaration` | ✅       | Declared scope; `null` if undeclared                                                    |
+| `lease_expires_at`  | `string` (ISO-8601)     | ✅       | TTL expiry timestamp; entries with `lease_expires_at < now` are pruned on registry read |
+| `acquired_at`       | `string` (ISO-8601)     | ✅       | When the lease was first acquired                                                       |
+
+**Invariants**:
+
+- `run_id` + `owner_instance_id` together form a unique key in the registry.
+- Only one entry per `(run_id, owner_instance_id)` pair; upsert replaces on re-acquisition.
+- Entries are removed on explicit `releaseRunLease` or pruned when `lease_expires_at < now`.
+
+```typescript
+export interface ActiveLeaseRecord {
+  run_id: string;
+  owner_instance_id: string;
+  instance_id: string;
+  scope: LeaseScopeDeclaration;
+  lease_expires_at: string;
+  acquired_at: string;
+}
+```
+
+---
+
+### `LeaseRegistry`
+
+Top-level shape of `.aop/runtime/lease-registry.json`.
+
+| Field        | Type                  | Required | Description                                      |
+| ------------ | --------------------- | -------- | ------------------------------------------------ |
+| `leases`     | `ActiveLeaseRecord[]` | ✅       | All currently active (non-expired) lease entries |
+| `updated_at` | `string` (ISO-8601)   | ✅       | Last registry write timestamp; informational     |
+
+**Invariants**:
+
+- Registry is created on first lease acquisition; reads return `{ leases: [], updated_at: <now> }` if file is absent.
+- Registry is protected by the existing index lock (`.aop/features/.index.lock`).
+- Registry is pruned (expired entries removed) on every read inside `withIndexLock`.
+
+```typescript
+export interface LeaseRegistry {
+  leases: ActiveLeaseRecord[];
+  updated_at: string;
+}
+```
+
+---
+
+## Modified Types
+
+### `RuntimeSessionsSnapshot` (in `apps/control-plane/src/core/runtime-sessions.ts`)
+
+One optional field added:
+
+```typescript
+export interface RuntimeSessionsSnapshot {
+  run_id: string;
+  orchestrator_session_id: string;
+  provider: string;
+  model: string;
+  provider_config_ref_hash: string;
+  owner_instance_id: string;
+  lease_id: string;
+  started_at: string;
+  last_heartbeat_at: string;
+  lease_expires_at: string;
+  orchestrator_epoch?: number;
+  feature_sessions?: Record<string, RuntimeFeatureSessions>;
+  scope?: LeaseScopeDeclaration; // NEW: persisted scope declaration
+}
+```
+
+**Backward compatibility**: `scope` is optional. Existing persisted lease files without this field will deserialize as `scope: undefined`, which is normalized to `null` (conservative) before any conflict detection.
+
+---
+
+### `AcquireRunLeaseInput` (in `apps/control-plane/src/application/services/run-lease-service.ts`)
+
+```typescript
+export interface AcquireRunLeaseInput {
+  run_id: string;
+  owner_instance_id: string;
+  provider: string;
+  model: string;
+  provider_config_ref_hash: string;
+  takeover_stale_run?: boolean;
+  scope?: LeaseScopeDeclaration; // NEW: undefined normalizes to null (conservative)
+}
+```
+
+---
+
+### `ExpandRunLeaseScopeInput` (new, in `run-lease-service.ts`)
+
+```typescript
+export interface ExpandRunLeaseScopeInput {
+  run_id: string;
+  owner_instance_id: string;
+  additional_paths?: string[];
+  additional_plan_section_ids?: string[];
+}
+```
+
+---
+
+## New Error Code (in `apps/control-plane/src/core/error-codes.ts`)
+
+```typescript
+LEASE_SCOPE_CONFLICT: 'lease_scope_conflict',
+```
+
+**Error details shape** (when thrown from `acquireRunLease`):
+
+```typescript
+{
+  incoming_scope: LeaseScopeDeclaration;
+  blocking_run_id: string;
+  blocking_owner_instance_id: string;
+  conflicting_scope_entry: string; // first conflicting path or plan_section_id
+  retryable: true;
+  requires_human: false;
+}
+```
+
+---
+
+## Persistence Locations
+
+| Artifact                | Path                                       | Protected By                |
+| ----------------------- | ------------------------------------------ | --------------------------- |
+| Per-instance lease file | `.aop/runtime/<instanceId>/run-lease.json` | `withIndexLock`             |
+| Global lease registry   | `.aop/runtime/lease-registry.json`         | `withIndexLock` (same lock) |
+
+---
+
+## State Transitions
+
+### Lease Registry — entry lifecycle
+
+```
+[no entry]
+    │
+    ▼ acquireRunLease(scope)
+[ActiveLeaseRecord: scope = declared | null]
+    │
+    ├─► renewRunLease() ──► [lease_expires_at updated]
+    │
+    ├─► expandRunLeaseScope() ──► [scope updated (additive)]
+    │
+    └─► releaseRunLease() ──► [entry removed]
+         │
+         └─► TTL expiry (pruned on next registry read) ──► [entry removed]
+```
+
+### Scope overlap decision at acquisition
+
+```
+acquireRunLease(input):
+  scope = input.scope ?? null   ← normalize undefined → null
+
+  active = registry.leases (pruned of expired)
+
+  for each activeLease in active (excluding same run_id re-acquire):
+    if activeLease.scope === null OR scope === null:
+      → CONFLICT
+    if scope.paths.length === 0 AND scope.plan_section_ids.length === 0:
+      → no conflict (empty = touches nothing)
+    if activeLease.scope.paths.length === 0 AND activeLease.scope.plan_section_ids.length === 0:
+      → no conflict
+    if pathsOverlap(scope.paths, activeLease.scope.paths):
+      → CONFLICT
+    if planSectionsOverlap(scope.plan_section_ids, activeLease.scope.plan_section_ids):
+      → CONFLICT
+  → GRANT
+```