SDK transaction guards and extension runtime parity

Merged
UN
3mo ago
+1309-150

Summary

  • add capability-gated, fail-closed beforeMutation extension hooks with canonical before/after documents, changed fields, stable diagnostics, and a host-bound read-only SDK
  • enforce guards across create, update, annotations, close, delete, restore, and structured transactions without item/history side effects on denial
  • inject the production-shaped SDK into extension command tests and add typed override seams
  • make active extension item types resolve consistently across the complete lifecycle
  • regenerate SDK/contracts/error catalogs, performance budgets, extension documentation, and the package-owned changelog

Project management

Fixes #853
Fixes #854
Fixes #855

Verification

  • full all-source suite: 413 files, 6,666 tests, 100% statements/branches/functions/lines
  • typecheck, ESLint, jscpd, static quality/docstrings, contracts, SDK surface, performance, security secret scan, and production dependency audit pass
  • isolated packed-package consumer created an item through context.sdk.client, enforced a mutation guard, and resolved the packed executable through local, npx --no-install, and bunx --no-install paths
  • PM health and history drift checks pass; package-owned pm-changelog 2026.8.1 output is stable

Compatibility note

The production-shaped test harness intentionally loads the native PmClient service graph. Its measured cold-import cost is isolated to @unbrained/pm-cli/sdk/testing and recorded in the regenerated reviewed budget; runtime entrypoints remain unchanged.

Summary by Sourcery

Introduce transactional before-mutation extension guards with a host-bound read-only SDK, and align extension runtime, item lifecycle, and test harness behavior with production semantics.

New Features:

  • Add capability-gated fail-closed beforeMutation hooks that can approve or deny item and history mutations based on canonical before/after documents, changed fields, and a read-only SDK.
  • Expose a minimal mutation-guard SDK with item get/list tracking services to extension hooks and authoring surfaces.
  • Extend the extension blueprint, capability derivation, and define* helpers to support the new beforeMutation hook surface and related contracts.
  • Provide test-harness support for invoking mutation guards and for injecting the real host-bound SDK (or typed overrides) into command dispatch.

Bug Fixes:

  • Ensure item type resolution for close, locate, and related lifecycle operations honors extension-registered custom types across all mutation paths.

Enhancements:

  • Centralize mutation-guard decision validation and error reporting into structured, stable diagnostics in the extension runtime.
  • Wire before-mutation guards into create, update, delete, restore, annotations, and structured transaction flows so denied mutations have no item or history side effects.
  • Track beforeMutation registrations in activation summaries, capability usage attribution, rollback handling, and hook-count reporting.
  • Tighten the extension loader and testing utilities around optional hook registries and hook-kind lookups.
  • Refresh performance budgets for SDK entrypoint import costs, reflecting the updated testing harness runtime.
  • Update extension author and testing documentation to describe transactional mutation guards, the host-bound SDK in tests, and mutation-guard exercise patterns.

Documentation:

  • Document the beforeMutation lifecycle hook, its canonical context payload, and fail-closed semantics in extension authoring guides.
  • Clarify test harness behavior for command dispatch with real SDK injection and for invoking mutation guards through the production-aligned runtime.
  • Update SDK performance documentation with new entrypoint import measurements reflecting the testing harness changes.

Tests:

  • Add a comprehensive extension mutation platform test suite covering SDK injection, guard decision normalization, denial behavior, and invariants enforced across item lifecycle operations.
  • Extend existing loader, compose, and define-builder tests to account for the new beforeMutation hook surface and updated hook-count expectations.

Chores:

  • Regenerate SDK public surface, contracts fixtures, error code catalog entries, performance budgets, and PM history/issue artifacts to reflect the new mutation-guard and testing capabilities.

Summary by cubic

Adds capability-gated beforeMutation guards to enforce extension invariants across item transactions with fail‑closed, stable diagnostics and a 5s timeout. Also injects a real host-bound SDK into extension command tests, unifies extension item-type resolution, and routes mutation guard testing through a dedicated helper.

  • New Features

    • Transactional beforeMutation guard with canonical before/after docs, changed fields, and operation; exposes a host-bound read‑only SDK; denial aborts with stable error codes (extension_mutation_guard_*); guard execution is bounded to 5s and fails closed.
    • Test harness injects a real host-bound SDK by default with a typed override seam; adds defineBeforeMutationHook, blueprint beforeMutation support, ExtensionMutationGuardSdk, and clarifies tracker‑root semantics.

  • Bug Fixes

    • Core mutation locators honor extension-registered item types across create/update/annotate/close/delete/restore and structured transaction paths; delete canonicalization preserves active extension metadata.
    • Generic hook runners now reject beforeMutation; tests invoke guards via the dedicated mutation-guard helper, preserving fail‑closed behavior for both registered and legacy empty registries.