@plumbus/core 0.7.1 → 0.8.0-beta.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @plumbus/core changelog
 
+## 0.8.0-beta.0 — 2026-09-11 — core 0.8 beta family
+
+### Upgrade boundary
+
+- Beta prerelease of the coordinated core 0.8 family (core 0.8.x, UI 0.9.x, MCP 0.7.x, voice 0.6.x, other add-ons 0.3.x), published under the branch-named npm dist-tag `plumbus-next` (`latest` stays on the 0.7 family). Previous caret ranges exclude it; install the whole family together and follow the [0.8 upgrade notes](../../docs/upgrading-core-0.8.md). Internal peers use prerelease-inclusive ranges (for example `>=0.8.0-beta.0 <0.9.0`) until the family goes stable.
+
+### Breaking
+
+- **Flow compensations never run with worker privileges.** When an execution's stored auth snapshot is missing or invalid, compensation steps are not executed as the worker; the engine records a failed `compensate` history entry and a `flow.compensation_skipped` audit event for operator review, matching the step path.
+- **`plumbus e2e --port`**, **`plumbus worker --health-port`**, and **`plumbus mcp serve --http --port`** require an explicit port (or `PLUMBUS_E2E_PORT` / `PLUMBUS_WORKER_HEALTH_PORT` / `PLUMBUS_MCP_PORT`). `createServer({ port })` is required to listen. No default 3000/3001 is assumed.
+- **`plumbus ui generate` requires `--out-dir` or a detected frontend.** It no longer writes to `.plumbus/generated/ui` as a last-resort default. Detection still uses a monorepo `frontend/` package, an existing `frontend/` directory, or `frontend`/`web`/`client`/`app` with `tsconfig.json`. Explicit `--out-dir .plumbus/generated/ui` still works.
+- **Action-risk vocabulary is now the four-tier canonical set** — `analytical`, `limited-reversible`, `consequential`, `prohibited`. `read-only` is retired (it was the analytical tier under its former name) and joins `RETIRED_ACTION_RISK_VALUES`; `defineCapability` rejects it like every other retired value. `ActionRiskTier.ReadOnly` is gone; use `ActionRiskTier.Analytical`. **`prohibited` is normative**: the approval gate refuses a prohibited capability outright (new gate code `prohibited-capability`) before any approval lookup, `ApprovalService.requestApproval` rejects `riskClass: 'prohibited'` (an approval must not make a prohibited action permissible), and `defineCapability` rejects `exposeAs` on a prohibited capability so it is never exposed as an MCP tool or API route. New helper: `isProhibitedRiskTier`.
+
+### Added
+
+- **`AIValidationError` is exported from the package root.** The class always carried `usage` (accumulated across every retry the validation loop paid for), `model`, and `provider`, and the docs always said to catch it — but it was never re-exported from the barrel, so a host could not name the class and the sunk spend of a validation-exhausted call was unreadable outside `ai-service`. It now sits beside `AIRefusalError`, `AIIncompleteOutputError`, and `AIInvalidRequestError`. Matters to any host that keeps its own cost ledger instead of installing `onAICostRecorded`. Docs: [AI integration](../../docs/ai/ai-integration.md).
+- **`createMemoryCredentialCatalog`** — host-declared named credential types and opaque bindings. The catalog stores type shapes, names, refs, and public labels; the host resolver supplies field values at `reveal`. Secret fields are read with `secret(name)` and never appear in JSON, `util.inspect`, or catalog errors. No built-in types. Optional on `createPlumbusRuntime({ credentials })` and on `createServer({ credentials })`. HTTP boot loads `export const credentials` from `app/server.ts` through `loadServerExtensions`. The catalog is retained on `PlumbusServer.credentials` and is never logged. Published at `@plumbus/core` and `@plumbus/core/credentials` (`dist/credentials/index.js`). Docs: [Credential catalog](../../docs/sdk-reference/credential-catalog.md).
+- **Compiled-flow disk reload** — `loadCompiledFlowRegistryFromDirectory` / `tryLoadCompiledFlowRegistryFromDirectory` read `plumbus compile-flows` JSON, recompute `definitionDigest`, and refuse a mismatch. `createServer` and `createWorkerPool` load `{cwd}/.plumbus/compiled-flows` when that tree has JSON, or an explicit `compiledRegistry` / `compiledFlowsDirectory`. Docs: [Flows — compiled definitions](../../docs/core-concepts/flows.md).
+- **`applyDataPlaneMigrations({ target, migrationsFolder })`** — host helper that opens one named tenant database through `openDataPlaneConnection` (owner role), runs existing `applyMigrations`, and always closes the pool. Result includes `database` when the target named one.
+- **`plumbus migrate apply --database <name>`** — same path from the CLI (config host/user, named database). Also on `push` / `rollback` / `reconcile`. `--create-db` now creates that named database when `--database` is set. JSON apply output includes `"database"`.
+- **Docs:** [Tenant data planes](../../docs/sdk-reference/tenant-data-planes.md) — provision, migrate as owner, resolve as runtime. [Credential catalog](../../docs/sdk-reference/credential-catalog.md) — host-declared types, opaque refs, no secrets in logs.
+
+### Fixed
+
+- **Prompt `{{key}}` fill is literal and single-pass.** `buildPromptText` no longer uses `String.replaceAll` with a string replacement (which interprets `$`, `$'`, `` $` ``, `$&`, `$1`) and no longer re-scans substituted values for later `{{key}}` tokens. Values that contain those characters or placeholder-shaped text stay inert. Shared helper: `fillPromptTemplate`. Docs: [AI integration](../../docs/ai/ai-integration.md).
+
+### Changed
+
+- **`plumbus generate` writes OpenAPI 3.1.0** for `.plumbus/generated/openapi.json`, with JSON Schema 2020-12 type-array nullables (`type: ["string", "null"]`) instead of OpenAPI 3.0 `nullable: true`. Conversion is the same pass `@plumbus/api` uses for `--openapi-version 3.1.0` (now owned by core so generate does not load the partner package). Partner `plumbus api generate openapi` remains 3.0.3 unless that flag is set.
+- **`plumbus generate` no longer writes leftover `clients/` fetch/hook files.** Re-running generate deletes `.plumbus/generated/clients/` if that tree is still present. Typed fetch clients and React hooks come from `plumbus ui generate`.
+- **`plumbus migrate` connections** go through `openDataPlaneConnection` (bounded pool of 1, `application_name: plumbus-migrate`, empty passwords omitted). Connection failures surface the factory's redacted message.
+- **`plumbus ui generate` emits fetch clients, React hooks, and form hints only for `exposeAs: ['api']` capabilities** (event handlers omitted). Operator-only capabilities are not given HTTP wrappers.
+
+### Schedule planes for the flow scheduler
+
+- `FlowSchedule.plane` (`'spine' | 'tenants'`): where a scheduled flow's row lives and whose data plane its run gets.
+- `WorkerPoolConfig.schedulePlanes` and `app/server.ts` `export const schedulePlanes`: tenant planes for the scheduler alone, for hosts that route tenant data themselves; flows, events and the outbox keep the pool plane.
+- The scheduler syncs and polls the pool only when a registered flow is scheduled on the spine, tolerates a plane it cannot resolve or read, and reports the driver's cause.
+
 ## 0.7.1 — 2026-09-10
 
 ### Fixed

package/README.md

@@ -120,6 +120,7 @@ export const classifyTicket = definePrompt({
 | `@plumbus/core/testing` | Test utilities — `runCapability`, `simulateFlow`, `mockAI`, `createTestContext` |
 | `@plumbus/core/zod` | Re-exported Zod (consumers should not install Zod separately) |
 | `@plumbus/core/vitest` | Vitest config helpers |
+| `@plumbus/core/credentials` | Host-declared credential catalog (`createMemoryCredentialCatalog`) |
 
 ## CLI
 
@@ -131,7 +132,7 @@ plumbus generate              # Regenerate artifacts from contracts
 plumbus verify                # Run governance rules
 plumbus certify <profile>     # Run compliance assessment (GDPR, PCI-DSS, etc.)
 plumbus migrate generate      # Generate database migration
-plumbus migrate apply         # Apply pending migrations
+plumbus migrate apply         # Apply pending migrations (`--database` for a named tenant DB)
 plumbus init --agent all      # Generate AI agent wiring files
 ```