@piagent/platform 1.2.17 → 1.3.0-ie.9

package/.gitattributes

@@ -5,3 +5,4 @@
 *.json text eol=lf
 *.md text eol=lf
 docs-site/*.html text eol=lf
+benchmarks/e2-framework-v1/project/vendor/hono/dist/** -whitespace

package/CHANGELOG.md

@@ -2,6 +2,266 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
+## Unreleased
+
+No changes after the `v1.3.0-ie.9` candidate boundary.
+
+## v1.3.0-ie.9 - 2026-08-12
+
+### Installed-package runtime parity
+
+- Added a package-owned TypeScript loader for terminal entry points so the npm
+  installation can load the same audited TypeScript runtime that Pi loads,
+  even when the package lives under `node_modules`.
+- Made the global benchmark helper use the matching exact Pi package Git source
+  installed by `piagent-install --stable`. It refuses to invent Git identity or
+  run against a mismatched helper/package version.
+- Replaced the symlink-only binary smoke with a real packed-and-installed test:
+  all global commands print help from `node_modules`, and the installed benchmark
+  completes a provider-free dry run from an exact temporary Git source.
+- Preserved IE8 as the first successfully published package. Its helper,
+  installer, doctor and capability commands work, but the route and benchmark
+  binaries cannot load TypeScript from `node_modules`; IE9 supersedes it on the
+  npm `next` channel. Product/model behavior remains unchanged from IE7/IE8.
+
+## v1.3.0-ie.8 - 2026-08-12
+
+### Reproducible prerelease publishing
+
+- Made the tag-driven publish job fetch the complete Git/tag history required
+  by rollback tests and install the same `ripgrep` prerequisite used by the
+  native Ubuntu verification lane.
+- Preserved `v1.3.0-ie.7` as immutable failed-before-publish evidence. Its
+  workflow stopped during deterministic tests, before `npm publish`, so the
+  registry was not modified.
+- Kept the product runtime identical to IE7. The completed 108-session Luna
+  Medium benchmark remains exact IE7 runtime evidence and is not relabelled as
+  an exact IE8 benchmark; IE8 is a distribution-only correction.
+
+## v1.3.0-ie.7 - 2026-08-12
+
+### Source-derived public return-contract guidance
+
+- Extended the bounded return-representation classifier to recognize helper
+  parameters seeded from object properties, including stable graph traversals
+  that call `visit(item.name)` and later push that name into the public result.
+- Surfaces the existing names-versus-objects representation in the first model
+  turn before mutation. This preserves the public API without enabling a hard
+  semantic gate, adding a continuation, or changing the benchmark prompt,
+  variant, grader, outcome floor, or measured IE6 evidence.
+- Preserved the terminal IE6 production run as immutable NO-GO evidence. IE7
+  uses a new candidate digest and production seed and must pass a single paired
+  workspace-order canary before another full release benchmark is authorized.
+
+## v1.3.0-ie.6 - 2026-08-12
+
+### Candidate-only finite benchmark stop
+
+- Aligned the paired terminal stop with the production evaluator: a Piagent
+  outcome below the frozen floor stops after its pair, while a Codex-only miss
+  remains candidate-only dominance and does not prevent later coverage.
+- Kept helper wall-clock timing observational under parallel host load; exact
+  retrieval, token reduction, lifecycle, writer and privacy invariants remain
+  the release-gating properties.
+- Preserved the terminal `v1.3.0-ie.5` canary as immutable evidence; it is not
+  resumed or relabelled after this correction.
+
+## v1.3.0-ie.5 - 2026-08-12
+
+### Finite release benchmark and prerelease publishing
+
+- Added a release-only paired outcome stop that finishes the current Piagent/Codex
+  pair, records a terminal non-resumable receipt, and starts no later provider
+  session after an outcome falls below the frozen suite floor.
+- Bound prerelease packages to the npm `next` dist-tag in both package identity
+  and the tag-driven publish workflow, preserving `latest` for stable releases.
+- Preserved the failed `v1.3.0-ie.4` measurement as immutable evidence; no suite,
+  grader, prompt, or measured result was rewritten for this candidate.
+
+## v1.3.0-ie.4 - 2026-08-11
+
+### Symmetric native CI prerequisites
+
+- Installed the exact ripgrep test prerequisite on both Ubuntu and macOS CI.
+  This keeps the helper evaluation identical across native platforms; no
+  product gate, benchmark evaluator, or provider behavior was relaxed.
+- Kept the integration waits finite while giving the full parallel suite room
+  for native filesystem contention. The helper and immutable-snapshot product
+  assertions remain unchanged; only their test-harness deadlines moved.
+
+## v1.3.0-ie.3 - 2026-08-11
+
+### Deterministic cross-platform helper gate
+
+- Kept helper retrieval timing as an observational metric, but made the release
+  gate depend on exact retrieval correctness, model-visible token reduction,
+  lifecycle, budget, writer and privacy invariants. This removes filesystem and
+  process-startup timing noise from native Linux CI without weakening the
+  product property the helper is intended to provide.
+
+## v1.3.0-ie.2 - 2026-08-11
+
+### Runtime and release-gate refresh
+
+- Raised the exact Pi Coding Agent and Pi AI host pin to `0.84.1` and TypeBox
+  to `1.3.7`. The new host tree audits clean at moderate and above, replacing
+  the expired `0.82.0` advisory exception; provider-free host compatibility,
+  package lifecycle and release identity are re-gated on the new pin.
+- Scoped CodeQL away from the byte-pinned Hono benchmark fixture while keeping
+  all Piagent product and benchmark harness code analyzed, and made Ubuntu CI
+  install the ripgrep dependency exercised by helper evaluation.
+
+## v1.3.0-ie.1 - 2026-08-11
+
+### Intelligence-engine candidate
+
+- Added a deterministic Criterion Graph projection and bounded current-source
+  context delivery so Luna Medium can plan against operator criteria without a
+  repository-index dependency or an extra model turn. Mechanical task truth,
+  exact verification, current-tree evidence and permissions remain unchanged.
+- Kept every advanced capability in the package while broad defaults leave
+  solver and phase tools in shadow, acceptance and performance assurance
+  advisory, semantic repair off, helpers recommend-only and parent routing off.
+- Added a fail-closed IE6 release protocol for Piagent versus controlled Codex
+  CLI on Luna Medium: 18 production families, three repeats, two surfaces, 108
+  sessions, six-session inspected chunks, retry zero and explicit platform,
+  cohort, private-holdout, long-horizon and operator gates.
+- Preserved RC.1 and RC.2 as immutable historical NO-GO evidence. The IE train
+  uses its own prerelease identity and does not relabel or resume either RC.
+
+## v1.3.0-rc.2 - 2026-08-11
+
+### Finite FS6 correction
+
+- Added one intake-only efficiency correction after the exact RC.1 Migration
+  gate: map every operator criterion to implementation and focused-test
+  coverage, batch independent operations, and perform one criterion review
+  before the first exact verifier. No completion gate, continuation budget,
+  capability mode, benchmark evaluator, or scenario behavior was relaxed.
+- Bound the pinned Hono 4.13.1 zero-install E2 fixture into the clean source and
+  package, excluded the test-only `core-services.js` barrel from distribution,
+  and made the control-byte gate accept valid empty upstream JavaScript files
+  without weakening checks for non-empty binary source.
+
+## v1.3.0-rc.1 - 2026-08-11
+
+### Operator product journey
+
+- Added deterministic parent model routing with versioned
+  `low|medium|high|ultra` capability bands, explicit pin/default provenance,
+  intelligence/balance/cost objectives, exact authenticated-catalog matching,
+  and fail-closed shadow/recommend/auto modes. `piagent-route` provides the only
+  explicit prelaunch enforcement path; extension auto does not mutate the Pi
+  user default or switch models mid-conversation.
+- Added a bounded Windsurf-style retrieval route (read-only grep/find/read, up
+  to eight parallel searches and four rounds, recommendation-only), a 240-case
+  offline routing gate, and a resume-locked 144-session static-versus-adaptive
+  protocol dry-run. No authenticated benchmark is implied by these local gates.
+
+- Extended task preflight with stable human/JSON projections for intent, risk,
+  scope, runtime provenance, solver route, phases, tools, helper budget,
+  execution boundary, readiness, approvals, and blockers. Read-only and
+  authorization-sensitive requests never display implementation permission.
+- Extended `/piagent-status` with persisted task, trajectory, checkpoint,
+  verifier, recovery, helper, resume, terminal receipt, and bounded efficiency
+  evidence. Completion remains hard-gate dependent and same-runtime evidence is
+  described as operational assurance, not independent audit.
+- Added one `/piagent-inspector` namespace with an automatic compact status line
+  below Pi's native TUI footer and
+  menu views for task-versus-working-tree diff, test files and line counts,
+  tool/command outcomes, safety warnings, verifier evidence, and context budget.
+  It reuses existing lifecycle hooks, does not call a model, marks mixed dirty
+  baselines explicitly, and never invents per-tool token attribution.
+- Hardened terminal receipts to fail closed unless the current-tree completion
+  gate passes, and hardened RC local readiness so every published routing,
+  safety, helper/writer, recovery, phase-tool, and host-boundary gate is
+  decisive. The RC matrix pins each P0-P6 evidence input by SHA-256 and the
+  generated report records the verified bytes and composite input digest.
+- Extended offline doctor readiness and `/usage efficiency` with install/update
+  recovery guidance and exact-or-unavailable task metrics joined through hashed
+  session/task/run identity. Raw task text and child output are not retained;
+  unmeasurable time, tokens, cost, and invocation counts remain null.
+
+### Durable runtime evidence
+
+- Fixed automatic long-prompt intake, repository-aware scope resolution,
+  idempotent bounded task IDs, runtime verifier defaults, and full-prompt
+  acceptance extraction. Phase enforcement now uses dependency-ready work-plan
+  evidence, keeps provider tool schemas cache-stable, treats `shell`/`exec` as
+  `bash`, and applies one phase decision to direct, shell, patch, and MCP
+  mutation carriers. Manual/high-risk planning and every read-only task remain
+  mutation-free; exact verifiers and bounded repair retain their intended path.
+- Recalibrated the public capability suite around explicit contracts and 47
+  weighted critical atomic checks across 16 prompt clauses. Each clause has a
+  named killed mutation and sensitivity rationale; independently shaped search
+  and migration implementations pass without object-identity, module-provenance,
+  fixture-name, or representation coupling. Historical benchmark evidence is
+  retained unchanged and is not regraded as a new performance claim.
+- Hardened Piagent-versus-Codex benchmarking with named, candidate-only runtime
+  treatments preserved across dry-run, resume, replay, and reports. Token-saving
+  claims now fail closed unless controlled Codex isolation, model/thinking pins,
+  randomized paired order, and exact treatment provenance pass; reports expose
+  paired resolved/quality/safety outcomes and token ratios by benchmark band.
+- Stabilized Task Contract v2 with identity-bound journal checkpoints, strict
+  acceptance receipts, current-tree verification evidence, bounded retries, and
+  immutable terminal outcomes. Journal hashes and receipts are operational
+  evidence produced by the same runtime, not independent attestation.
+- Added adaptive context planning, cited repository-memory hints, model
+  capability facts, verification intelligence, and a fail-closed execution
+  backend descriptor. The parent model remains operator-pinned, no solver or
+  automatic parent routing is shipped, and unavailable isolation adapters do
+  not silently fall back to host mutation.
+- Added benchmark measurement schema v1 with exact-or-unavailable context usage
+  and bounded task/acceptance evidence. Route, phase, and helper measurements
+  remain absent until their later schemas and runtime behavior are implemented.
+- Extracted bounded registration adapters and operator catalogs from the Pi
+  composition root, locked the root against growth, and extended runtime
+  integrity/package coverage for the new modules.
+
+### Controlled RC readiness
+
+- Added a pinned RC evaluation matrix and local-only readiness evaluator across
+  quality/routing, security/privacy, reliability/performance, and disposable
+  install/migration/rollback gates. It records candidate content and catalog
+  digests without storing credentials or gaining release-write capabilities.
+- Added cross-process helper lock waiting/stale-lock recovery and synthetic
+  disk-full/permission-denied state tests after the concurrency gate exposed an
+  immediate-lock-failure race.
+- Retained conservative defaults: solver and phase tools stay shadow, recovery
+  stays on, helpers stay recommend, and parent routing/automatic workers stay
+  off. GA remains blocked on controlled cohorts, human usability, Linux,
+  candidate benchmark, RC package/identity, and explicit operator approval.
+
+### Bounded recovery and handoff
+
+- Added deterministic failure classification and a cross-attempt recovery
+  matrix with one source repair or exact transient retry ceiling. Environment,
+  provider, permission, policy, scope, and unknown failures never gain source
+  mutation authority; `PIAGENT_AUTO_RECOVERY=off` preserves the prior handoff
+  path.
+- Added owner-only Handoff v1 projections and safe resume reconstruction bound
+  to task/session identity, journal integrity, trajectory phase, the actual
+  current tree, and exact verifier evidence. Stale passes are invalidated;
+  corrupt or symlink-unsafe state blocks mutation.
+- Extended acceptance receipts with optional runtime-observed recovery
+  provenance. Criteria/status truth is unchanged and the receipt stores only
+  bounded digests, counts, dispositions, and state references rather than raw
+  logs or source.
+
+### Role-bound helpers
+
+- Added strict RolePolicy v1 and HelperRequest v1 contracts for retriever,
+  scout, planner, worker, reviewer, Oracle, and researcher roles. Requests bind
+  hashed parent identity, bounded scope/tools/model/effort/budgets/output/stops,
+  cannot broaden parent authority, and never delegate approvals.
+- Added deterministic authenticated-catalog role binding that preserves the
+  user-pinned parent and reports unavailable instead of silently substituting a
+  model or effort. Worker remains disabled by default.
+- Added owner-only Piagent-owned helper budgets with two-concurrent/three-total,
+  per-role and one-writer ceilings, deduplication, orphan recovery, terminal
+  cancellation, and digest-only usage receipts. `PIAGENT_HELPERS_MODE` defaults
+  to `recommend`; automatic worker delegation is not enabled.
+
 ## v1.2.17 - 2026-08-03
 
 ### Bilingual public documentation

package/README.md

@@ -81,6 +81,7 @@ Removal targets what is registered in Pi's settings rather than what the current
 - Subagent setup helpers for read-only scouting, planning, implementation, review, and risk challenge.
 - Chat image-path intake: paste a screenshot path from the project or a granted `additionalReadRoots` directory and the guard attaches it as `[image1]` before the model sees the prompt.
 - Trusted-run wrapper: `piagent-auto` launches Pi with `--approve` for the current run while keeping piagent guardrails active.
+- Fresh-task capability routing: `piagent-route` explains a catalog-verified low/medium/high/ultra recommendation; provider execution requires explicit `--execute --yes`, while in-extension auto routing remains fail-closed.
 - Runtime policy tools:
   - `piagent_permission_status`
   - `piagent_exec_policy_check`
@@ -94,7 +95,16 @@ Removal targets what is registered in Pi's settings rather than what the current
 - Accident-brake guardrails for protected paths, destructive shell commands, task contracts, context manifests, observed verification evidence, and trace records.
 - Session-bound Task Contract v2: one Pi session per task, bounded retry history,
   Git baseline-aware changed files, scope enforcement, all-command verification,
-  and an immutable terminal outcome.
+  strict acceptance receipts, identity-bound journal checkpoints, and an
+  immutable terminal outcome. These are same-runtime operational records, not
+  independent attestation.
+- Adaptive context planning uses Pi-reported model/thinking/context facts to set
+  a bounded context budget; cited repository-memory hints never replace current
+  source reads. The parent model stays operator-pinned—there is no automatic
+  parent routing or solver in this stabilization baseline.
+- Execution backends are explicit and fail closed: host execution is the
+  default, while a requested isolation backend without an installed adapter
+  blocks mutation instead of silently using the host.
 - Bounded owner-only local state with cross-process JSONL rotation and a shared
   symlink-safe boundary for task evidence, telemetry, traces, and captures.
 - Two-tier one-command benchmark: `core-v1` is a fast paired smoke gate, while
@@ -109,7 +119,9 @@ Removal targets what is registered in Pi's settings rather than what the current
   overall. Against controlled `codex-cli` on the same `gpt-5.6-sol`/`xhigh`
   matrix, Piagent used 51.11% fewer paired fresh tokens with a 95% ratio interval
   of `0.3809..0.6276`; see the [benchmark evidence](https://piagent.io.vn/benchmark)
-  and [methodology](docs/quality-benchmark.md).
+  and [methodology](docs/quality-benchmark.md). This is immutable historical
+  evidence; current production gates additionally require every task and score
+  band to exceed 9.5, so aggregate 9.58 alone is no longer sufficient.
 - Built-in profiles for frontend, backend, fullstack, BE-readonly/FE-write, data, DevOps, mobile, docs, Python, and Node TypeScript.
 - Versioned capability packs with deterministic catalog, profile resolution, integrity lock, and permission checks.
 
@@ -215,6 +227,7 @@ Everything below is typed inside a Pi session. `/commands` lists the full set; [
 | `/workflow be-to-fe <request>` | Backend or spec is read-only and the implementation target is frontend. Pair with `/profile be-readonly-fe`. |
 | `/workflow platform-improve <request>` | Package-level work: setup, MCP, model scope, memory, runtime policy, prompts, skills, subagents. |
 | `/fresh task|scout|be-to-fe <request>` | The current session is already heavy. Opens a new governed session and replays the compact workflow prompt. |
+| `/piagent-inspector` | Open one read-only menu for task files and line diff, commands and failures, safety warnings, and context budget. A four-row panel is always shown beside Pi's native footer and can be hidden for the session with `toggle`. |
 
 Short workflow aliases such as `/task`, `/scout`, `/be-to-fe`, `/commit`, and `/pr` still work for power users, but docs and onboarding teach `/workflow` as the default.
 

package/README.vi.md

@@ -34,6 +34,18 @@ Trong session Pi đầu tiên của project, chạy `/onboard`. Hằng ngày, d
 - Local state nằm trong `.pi/piagent-state/`, có owner-only permission và bounded retention.
 - Project-specific business logic nằm trong project profile hoặc adapter, không đưa vào core.
 
+Task Contract v2 hiện gắn task/session/run identity với current-tree verification,
+strict acceptance receipt, hash-chained journal checkpoint, retry có giới hạn và
+terminal outcome bất biến. Đây là operational record do cùng runtime tạo ra,
+không phải independent attestation.
+
+Adaptive Context Planner dùng model, thinking và context usage do Pi báo để đặt
+budget có giới hạn; repository-memory hint luôn có citation và không thay thế
+việc đọc source hiện tại. Parent model vẫn do operator pin: baseline ổn định này
+chưa ship solver hoặc automatic parent routing. Host execution là mặc định; nếu
+yêu cầu isolation backend chưa có adapter, mutation bị block thay vì âm thầm
+fallback về host.
+
 ## Command chính
 
 | Command | Mục đích |
@@ -43,6 +55,7 @@ Trong session Pi đầu tiên của project, chạy `/onboard`. Hằng ngày, d
 | `/permission` | Đổi permission mode trong session |
 | `/context` | Xem Context Engine, index, retrieval và telemetry |
 | `/usage` | Xem session, model, thinking và context usage |
+| `/piagent-inspector` | Mở menu read-only để xem task diff, command fail/block, safety warning và context budget; panel bốn dòng tự hiện sát footer native, `toggle` để ẩn trong session |
 | Pi native `/name` | Đặt tên session; Piagent nhận rename event để map Agent Watch/report |
 | `/memory` | Xem hoặc cập nhật explicit project memory |
 | `/onboard` | Khởi tạo project profile và context |
@@ -71,6 +84,12 @@ npm run architecture:check
 - [Operator manual tiếng Việt](docs/operator-manual-vietnamese.md)
 - [Command reference tiếng Việt](docs/command-reference-vietnamese.md)
 
+## Adaptive model routing
+
+Adaptive model routing cho fresh task dùng `piagent-route --prompt "<task>" --json`.
+Chỉ `--execute --yes` mới mở provider-backed Pi process; `/model`/CLI pin luôn
+được giữ và extension không đổi model giữa conversation.
+
 ## Verification
 
 ```bash

package/adapters/be-readonly-fe/profile.json

@@ -28,6 +28,7 @@
   ],
   "readOnlyPaths": [
     "backend/**",
+    "*backend*/**",
     "server/**",
     "api/**",
     "apps/api/**",
@@ -47,6 +48,7 @@
     "**/*.pem",
     "**/*.key",
     "backend/**",
+    "*backend*/**",
     "server/**",
     "api/**",
     "apps/api/**",

package/architecture/layers.json

@@ -108,10 +108,23 @@
       "entrypoints": 800
     },
     "files": {
-      "packages/piagent-core/extensions/piagent-guard.ts": 8290,
+      "packages/piagent-core/extensions/piagent-guard.ts": 5000,
       "packages/piagent-core/extensions/policy-core.js": 2568,
       "packages/piagent-core/extensions/context-engine.js": 1342,
-      "scripts/benchmark-runner.mjs": 1432
+      "packages/piagent-core/benchmark/benchmark-core.js": 1034,
+      "scripts/benchmark-runner-core.mjs": 950
     }
-  }
+  },
+  "budgetExceptions": [
+    {
+      "file": "packages/piagent-core/extensions/piagent-guard.ts",
+      "approvedMaximum": 5000,
+      "targetMaximum": 5000,
+      "reviewedAt": "2026-08-08",
+      "expiresOn": "2026-08-22",
+      "ownerWorkItem": "CF-P4-03-prep",
+      "extraction": "Completed: tool and command registrations moved into bounded runtime modules before recovery-policy hook wiring; retain the 5,000-line ceiling while the remaining composition root is reduced toward GA.",
+      "review": "local-autopilot-reviewed; external maintainer approval is not implied"
+    }
+  ]
 }

package/benchmarks/capability-v1/alternatives/fullstack-search-contract/apps/web/src/search-view.js

@@ -0,0 +1,14 @@
+const entities = { "&": "&amp;", "<": "&lt;", ">": "&gt;", "\"": "&quot;", "'": "&#39;" };
+
+function escaped(value) {
+  return String(value).replace(/[&<>"']/gu, (character) => entities[character]);
+}
+
+export function renderSearchResults(results) {
+  if (!Array.isArray(results)) throw new TypeError("results must be an array");
+  let html = '<ul aria-label="Search results">';
+  for (const result of results) {
+    html += `<li data-id="${escaped(result?.id ?? "")}">${escaped(result?.name ?? "")}</li>`;
+  }
+  return `${html}</ul>`;
+}

package/benchmarks/capability-v1/alternatives/fullstack-search-contract/packages/shared/src/search-contract.js

@@ -0,0 +1,8 @@
+export function normalizeQuery(value) {
+  const decomposed = String(value ?? "").normalize("NFD");
+  let unmarked = "";
+  for (const character of decomposed) {
+    if (!/\p{M}/u.test(character)) unmarked += character;
+  }
+  return unmarked.trim().split(/\s+/u).filter(Boolean).join(" ").toLowerCase();
+}

package/benchmarks/capability-v1/alternatives/fullstack-search-contract/services/catalog/src/search.js

@@ -0,0 +1,18 @@
+import { normalizeQuery } from "../../../packages/shared/src/search-contract.js";
+
+export function searchCatalog(items, query, options = {}) {
+  if (!Array.isArray(items) || !options || typeof options !== "object" || Array.isArray(options)) throw new TypeError("invalid search arguments");
+  const limit = options.limit ?? 20;
+  if (!Number.isSafeInteger(limit) || limit <= 0) throw new TypeError("invalid search limit");
+  const expected = normalizeQuery(query);
+  const matches = [];
+  for (const item of items) {
+    const fields = [item?.name];
+    if (Array.isArray(item?.tags)) {
+      for (const tag of item.tags) if (typeof tag === "string") fields.push(tag);
+    }
+    if (normalizeQuery(fields.join(" ")).includes(expected)) matches.push(item);
+    if (matches.length === limit) break;
+  }
+  return matches;
+}

package/benchmarks/capability-v1/alternatives/resumable-migration-runner/packages/migration/src/plan.js

@@ -0,0 +1,32 @@
+function validateSteps(steps) {
+  if (!Array.isArray(steps)) throw new TypeError("steps must be an array");
+  const byId = new Map();
+  for (const step of steps) {
+    if (!step || Array.isArray(step) || typeof step.id !== "string" || !step.id.trim() || typeof step.apply !== "function" || byId.has(step.id) || !Array.isArray(step.dependsOn ?? [])) {
+      throw new TypeError("invalid migration step");
+    }
+    byId.set(step.id, step);
+  }
+  for (const step of steps) {
+    if ((step.dependsOn ?? []).some((dependency) => typeof dependency !== "string" || !byId.has(dependency))) {
+      throw new TypeError("unknown migration dependency");
+    }
+  }
+  return byId;
+}
+
+export function migrationPlan(steps) {
+  validateSteps(steps);
+  const pending = new Set(steps.map((step) => step.id));
+  const completed = new Set();
+  const result = [];
+
+  while (pending.size) {
+    const next = steps.find((step) => pending.has(step.id) && (step.dependsOn ?? []).every((dependency) => completed.has(dependency)));
+    if (!next) throw new TypeError("migration cycle");
+    result.push(next);
+    completed.add(next.id);
+    pending.delete(next.id);
+  }
+  return result;
+}

package/benchmarks/capability-v1/alternatives/resumable-migration-runner/packages/migration/src/runner.js

@@ -0,0 +1,43 @@
+function validatePlannedSteps(steps) {
+  if (!Array.isArray(steps)) throw new TypeError("steps must be an array");
+  const byId = new Map();
+  for (const step of steps) {
+    if (!step || Array.isArray(step) || typeof step.id !== "string" || !step.id.trim() || typeof step.apply !== "function" || byId.has(step.id) || !Array.isArray(step.dependsOn ?? [])) {
+      throw new TypeError("invalid migration step");
+    }
+    byId.set(step.id, step);
+  }
+
+  const visited = new Set();
+  for (const step of steps) {
+    for (const dependency of step.dependsOn ?? []) {
+      if (typeof dependency !== "string" || !byId.has(dependency) || !visited.has(dependency)) {
+        throw new TypeError("steps must be in migration-plan order");
+      }
+    }
+    visited.add(step.id);
+  }
+  return byId;
+}
+
+export async function runMigration({ steps, checkpoint, apply }) {
+  if (!checkpoint || typeof checkpoint.read !== "function" || typeof checkpoint.write !== "function" || typeof apply !== "function") {
+    throw new TypeError("invalid migration runner input");
+  }
+  const byId = validatePlannedSteps(steps);
+  const stored = await checkpoint.read();
+  if (!Array.isArray(stored) || stored.some((id) => typeof id !== "string" || !byId.has(id)) || new Set(stored).size !== stored.length) {
+    throw new TypeError("invalid migration checkpoint");
+  }
+
+  const completed = [...stored];
+  const completedIds = new Set(completed);
+  for (const step of steps) {
+    if (completedIds.has(step.id)) continue;
+    await apply(step);
+    completedIds.add(step.id);
+    completed.push(step.id);
+    await checkpoint.write(completed.slice());
+  }
+  return { completed: completed.slice() };
+}

package/benchmarks/capability-v1/coverage.json

@@ -0,0 +1,52 @@
+{
+  "schemaVersion": 1,
+  "checks": {
+    "rollout-normalized-shape": "Run-private percentage and tenants prove exact keys, boolean coercion, trim, deduplication, and first-seen order.",
+    "rollout-input-immutable": "A deep pre-call snapshot is compared with the caller object after normalization.",
+    "rollout-new-object": "Identity comparison proves normalization does not return the caller object.",
+    "rollout-invalid-object": "Null, array, and primitive object partitions must each throw TypeError.",
+    "rollout-invalid-percentage": "Missing, negative, fractional, above-100, and unsafe-integer partitions must throw TypeError.",
+    "rollout-invalid-tenants": "Missing, non-array, non-string-member, and whitespace-only member partitions must throw TypeError.",
+    "rollout-tenant-override": "A run-private listed tenant with an otherwise losing bucket must be enabled.",
+    "rollout-percentage-boundaries": "Buckets zero, percentage-minus-one, percentage, and 99 exercise the exclusive threshold.",
+    "rollout-disabled-missing-subject": "Disabled rollout plus null and undefined subjects must all resolve false.",
+    "rollout-invalid-bucket": "Negative, fractional, 100, and non-finite buckets must each throw TypeError.",
+    "feature-access-reasons": "Disabled, nullish, override, percentage, not-eligible, and invalid-bucket partitions exercise every exact reason and propagation rule.",
+    "rollout-summary": "Unnormalized run-private input must be normalized into the exact summary string.",
+    "rollout-summary-validates": "An invalid percentage proves summary delegates to rollout validation.",
+    "query-normalization": "Precomposed and extended combining marks plus tabs, case, and repeated whitespace exercise the normalization pipeline.",
+    "query-nullish": "Null and undefined become empty while a number proves non-nullish stringification.",
+    "catalog-name-tag-order": "Name, string-tag, order, empty-query, and non-string-tag partitions are asserted independently.",
+    "catalog-input-immutable": "A deep pre-call snapshot is compared after catalog search.",
+    "catalog-limit-contract": "Omitted and empty options prove default 20; one and MAX_SAFE_INTEGER prove valid boundaries.",
+    "catalog-invalid-input": "Non-array items, null/array/primitive options, and six invalid limit classes must throw TypeError.",
+    "catalog-shared-normalizer": "The catalog source must import normalizeQuery from the shared contract module.",
+    "search-render-exact-escaping": "Exact markup asserts ids and names escape all five required characters.",
+    "search-render-order": "Two run-private ids prove ordered one-li-per-result output.",
+    "search-render-empty": "The empty array must produce the exact accessible empty list.",
+    "search-render-invalid-input": "Null and plain-object result partitions must throw TypeError.",
+    "lease-acquire-input-validation": "Empty/whitespace key-owner, four invalid-now classes, five invalid-ttl classes, and zero/MIN_VALUE valid boundaries are exercised.",
+    "lease-renew-input-validation": "Renew repeats every key-owner and numeric invalid partition plus zero/MIN_VALUE valid boundaries.",
+    "lease-release-current-input-validation": "Release and current each reject empty and whitespace-only identifiers.",
+    "lease-contention-inclusive-expiry": "A live competing owner loses at expiry-minus-one and wins exactly at expiry.",
+    "lease-same-owner-reacquire": "A live same owner reacquires and resets the exact expiry.",
+    "lease-renew-contract": "Wrong owner, live owner, exact new expiry, and inclusive expired boundary prove boolean renewal semantics.",
+    "lease-release-contract": "Wrong owner, current owner, and already-absent release calls prove exact booleans.",
+    "lease-snapshot-isolation": "Undefined absence and mutation of a returned snapshot prove no internal reference escapes.",
+    "with-lease-success-callback": "A bare callable renew argument, boolean renewal, result propagation, and cleanup are asserted.",
+    "with-lease-busy": "A live competing owner must cause a rejection containing busy.",
+    "with-lease-failure-cleanup": "An operation exception is preserved and the owned lease is removed in finally.",
+    "with-lease-owner-change-cleanup": "Replacement at exact expiry survives the prior owner's finally cleanup.",
+    "migration-step-validation": "Non-array, empty/whitespace/duplicate ids, and non-callable step apply partitions must throw TypeError.",
+    "migration-dependency-validation": "Non-array, unknown, and non-string dependency partitions must throw TypeError.",
+    "migration-cycle-validation": "Self-cycle and two-node cycle partitions must throw TypeError.",
+    "migration-stable-chain-order": "A reverse-declared run-private dependency chain must become prepare-transform-finalize.",
+    "migration-stable-ready-order": "Independent ready siblings and a newly ready earlier-index node prove stable Kahn selection.",
+    "migration-input-immutable": "Array identity/order and every dependency array are compared after planning.",
+    "migration-runner-input-validation": "Malformed runner fields, malformed steps, and two dependency-unsafe orderings must reject.",
+    "migration-checkpoint-validation": "Non-array state and an unknown run-private id must reject.",
+    "migration-skip-write-return": "Persisted prefix skipping, apply order, per-step fresh writes, exact return, and identity isolation are asserted.",
+    "migration-crash-resume": "A one-time middle-step crash proves checkpoint boundary and exact retry call sequence.",
+    "migration-return-isolation": "Mutating the returned completed array must not mutate the last persisted array."
+  }
+}