@happyvertical/smrt-core 0.57.29 → 0.57.31

package/AGENTS.md

@@ -15,6 +15,7 @@ and repository rules.
 | `src/data-query.ts` | Transport-neutral bounded query normalization | [agents/data-query.md](agents/data-query.md) |
 | `src/schema/`, `src/migrations/`, `src/cascade.ts`, `src/system/` | DDL parity, indexes, migrations, delete integrity, retention | [agents/schema-paths.md](agents/schema-paths.md) |
 | `src/postgres-permissions.ts` | Explicit PostgreSQL ACL plans and atomic reconciliation | [deployment permission contract](../../docs/content/postgres-permissions.md) |
+| `src/migrations/deployment-phase-tracker.ts` | Permanent checksummed PostgreSQL deployment steps, atomic markers and explicit external-effect reconciliation | [agents/deployment-phases.md](agents/deployment-phases.md) |
 | `src/change-feed.ts` | Durable changes, cursors, table versions, retention | [agents/change-feed.md](agents/change-feed.md) |
 | `src/change-feed-authz.ts` | Consumer table/row change-feed authorization hooks (#3020) | [agents/change-feed.md](agents/change-feed.md) |
 | `src/change-signals.ts` | Signal bus, replica fan-out, SSE | [agents/change-signals.md](agents/change-signals.md) |

package/agents/build-knowledge.md

@@ -121,6 +121,14 @@ that declares `svelte` anyway only loses an optional context import.
 Transitive-only object modules are loaded through `importSmrtDependency()`
 from their provider's context, which needs no root import.
 
+Selective SSR compilation compares a JavaScript barrel's `svelte` export target
+against the package instance visible from its actual importer. pnpm may install
+the same version in multiple peer contexts; the app-root package directory is
+not the identity of a transitive import. Read that importer's installed export
+map and root together, preserving exact target matching. Plain server entries
+remain external; do not fix peer-context resolution by deduplicating app
+packages or bundling every server export (#4318).
+
 Not covered by contract: a package whose root is a Svelte entry AND whose
 `@smrt()` objects are exported only from that root. The object loop must then
 import the root (it is the only module exporting the constructors) — statically

package/agents/deployment-phases.md

@@ -0,0 +1,71 @@
+# Durable deployment data steps
+
+`DeploymentPhaseTracker`, exported from `@happyvertical/smrt-core/migrations`,
+is a PostgreSQL-only deployment data-step API. SQL schema steps continue to use
+`MigrationTracker`, including its checksums and concurrent-index recovery.
+
+A permanent `_smrt_deployment_steps` ledger keys each step by `application`,
+`environment`, and stable `stepId`. Reusing an ID with a different checksum or
+execution mode fails before its work or inspection executes. A release identifier
+alone is not a stable step ID: otherwise later releases replay old data changes.
+There is no retention. Preserve this table when restoring data; deleting markers
+permits replay. Checkpoints must never contain secrets. `MAX_DEPLOYMENT_CHECKPOINT_BYTES` limits
+serialized checkpoint JSON to 16 KiB measured in UTF-8 bytes, including quotes
+and JSON syntax. Oversized or unserializable values fail with
+`INVALID_CHECKPOINT` before their ledger query; the prior durable checkpoint is
+preserved. Values follow `JSON.stringify` conventions: undefined/null checkpoints
+normalize to null, nonfinite numbers become null, object properties containing
+undefined/functions/symbols are omitted, and those array elements become null.
+Circular references, BigInt, and top-level functions/symbols are rejected.
+A checkpoint rejection does not undo prior external effects: reconciliation
+still determines whether they completed or may safely resume.
+
+Every execution requires `checkSafety(connection)`: a read-only callback that
+throws unless runtime/static schema agreement and writer quiescence have been
+proved. It runs after acquiring the scope lock and before any ledger DDL or data
+write, including a replay. The caller owns platform fencing and complete writer
+inventory; an advisory lock excludes cooperating deployment runners, not runtime
+writers. Guards must not open transactions or change session/lock state.
+
+The adapter must expose public `acquireSession()`. A session advisory lock
+serializes every step in the same application/environment; the same pinned
+session executes data writes and markers. Lock acquisition times out after
+`lockTimeoutMs` (default 30 seconds). Other adapters fail closed. DDL provision
+runs outside the data transaction under a separate initialization lock. The
+migration role needs schema CREATE and ledger read/write permissions.
+
+`runTransactionalStep(options, async tx => { ... })` exposes a query-only handle
+on that pinned session. Use **only that handle** for all transactional mutations.
+Data and the completed marker commit together. A thrown callback rolls both back;
+a lost COMMIT response is never retried internally. On retry, the committed marker
+skips work, or the absent marker permits a fresh transaction. Do not issue
+transaction control, DDL requiring autocommit, session configuration or advisory
+lock changes inside callbacks. Work outside this handle is not made atomic.
+
+`runReconciledStep({ ...options, inspect, apply })` commits a running marker before
+calling either callback. `inspect(context)` must independently classify actual
+effects as `complete`, `safe-to-resume`, or `needs-repair`. It runs on fresh and
+interrupted attempts. Only `safe-to-resume` permits `apply(context)`, and another
+inspection must prove complete afterward. `saveCheckpoint(json)` persists a
+running checkpoint before external effects; `context.checkpoint` exposes the
+latest value. Each effect must tolerate the interval between performing it and
+saving its checkpoint. No blind shell-command replay is provided.
+
+A failure records needs-repair if the session survives; process/connection death
+can leave running. Both are unresolved and require inspection on the next attempt.
+`getStepStatus(key)` is read-only and reports the durable status without guessing
+whether a running owner is alive. A reconciler may prove a needs-repair attempt
+safe to resume after an operator repairs the underlying problem. A callback that
+cannot determine safety must return needs-repair and refuse further mutation.
+
+External effects cannot be atomically fenced by a PostgreSQL connection:
+`assertActive()` checks the pinned session, but it cannot stop an already-running
+shell command or fence an external service after connection loss. Applications
+must supply service-specific fencing/idempotency and truthful inspection, or
+require manual repair. This API makes no exactly-once claim for external effects.
+
+Focused validation: `pnpm --filter @happyvertical/smrt-core exec vitest run
+src/migrations/__tests__/deployment-phase-tracker-postgres.optional.test.ts` with
+`SMRT_TEST_POSTGRES_URL` pointing to an isolated PostgreSQL database. Tests use
+separate pools to exercise serialization, atomic marker/data rollback and commit,
+checksum refusal, and ambiguous nontransactional recovery.

package/agents/generators.md

@@ -457,3 +457,29 @@ model-level validation, and regenerate RLS policies when adopting a changed
 binding.
 
 Custom actions retain the `{ action, result }` response envelope.
+
+## Collection-hosted REST factory identity (#4320)
+
+Generated collection custom-action handlers resolve their executable collection
+using the declaring resource's exact qualified registration key. Keep that
+factory key separate from the item model's qualified type/policy metadata:
+item collection slugs still govern permissions, and ordinary model routes keep
+their own factory lookup. A resource in another package must neither rebuild
+an item identity under its package nor steal the item's existing package when
+its collection decorator merges configuration. Registration and generated
+factory selection share one identity resolver; never install global aliases to
+repair an inferred or bundled class name.
+
+Every collection hosting a generated REST action receives its exact constructor
+binding even with `cli: false` or omitted CLI configuration. This runtime-only
+binding does not add discovery metadata: named HTTP CLI resources keep their
+existing explicit-include eligibility. Constructor-only qualified receivers keep
+their own collection-cache identity while resolving backing item metadata, so
+ordinary model factories cannot reuse a different resource receiver. Neither
+CLI nor MCP discovery gains a resource or default CRUD surface from this binding.
+
+When consumer registration owns external packages (`smrtDependencies`), its
+`.smrt/register.js` binds external REST action receivers using the resolved
+canonical/provider-context export. The SvelteKit registration module continues
+to delegate external imports there; external bindings also add no discovery
+metadata and do not depend on CLI inclusion.

package/dist/consumer-plugin/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/consumer-plugin/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAa,MAAM,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,EAEL,KAAK,6BAA6B,EACnC,MAAM,2BAA2B,CAAC;AAYnC,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,uCAAuC,CAAC;AAqB/C,OAAO,EACL,kCAAkC,EAClC,KAAK,sCAAsC,EAC3C,KAAK,8BAA8B,EACnC,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,2BAA2B,CAAC;AAiJnC;;;GAGG;AACH,UAAU,oBAAoB;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,oBAAoB,GAAG,SAAS,GAC5C,OAAO,CAcT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,oBAAoB,GAAG,SAAS,GAC5C,MAAM,GAAG,SAAS,CAEpB;AAED;;;;GAIG;AACH,MAAM,WAAW,4BACf,SAAQ,OAAO,CACb,IAAI,CACF,gBAAgB,EACd,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,aAAa,GACb,gBAAgB,CACnB,CACF;IACD,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,uCAAuC;IACvC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,6BAA6B,CAAC;IACnD;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,4BAA4B,CAAC;IACnD;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oDAAoD;IACpD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4BAA4B;IAC5B,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAmXD;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAykBtE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/consumer-plugin/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAa,MAAM,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,EAEL,KAAK,6BAA6B,EACnC,MAAM,2BAA2B,CAAC;AAYnC,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,uCAAuC,CAAC;AAqB/C,OAAO,EACL,kCAAkC,EAClC,KAAK,sCAAsC,EAC3C,KAAK,8BAA8B,EACnC,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,2BAA2B,CAAC;AAiJnC;;;GAGG;AACH,UAAU,oBAAoB;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,oBAAoB,GAAG,SAAS,GAC5C,OAAO,CAcT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,oBAAoB,GAAG,SAAS,GAC5C,MAAM,GAAG,SAAS,CAEpB;AAED;;;;GAIG;AACH,MAAM,WAAW,4BACf,SAAQ,OAAO,CACb,IAAI,CACF,gBAAgB,EACd,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,aAAa,GACb,gBAAgB,CACnB,CACF;IACD,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,uCAAuC;IACvC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,6BAA6B,CAAC;IACnD;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,4BAA4B,CAAC;IACnD;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oDAAoD;IACpD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4BAA4B;IAC5B,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAmXD;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,MAAM,CA2lBtE"}

package/dist/consumer-plugin/index.js

@@ -1,6 +1,6 @@
 import "../scanner/types.js";
 import { canonicalSvelteKitPath } from "../vite-plugin/sveltekit-path.js";
-import { clearGeneratedSvelteKitRouteFiles, reconcileSvelteKitRouteGitignore } from "../vite-plugin/sveltekit-generator.js";
+import { clearGeneratedSvelteKitRouteFiles, reconcileSvelteKitRouteGitignore, resolveApiActionSet } from "../vite-plugin/sveltekit-generator.js";
 import { generateWebModule, isCollectionManifestClass, resolveCollectionItemObject } from "../vite-plugin/web-collections.js";
 import { publishArtifactFiles } from "./artifact-publication.js";
 import { resolveFileKnowledgeConfig } from "../knowledge-config.js";
@@ -523,7 +523,10 @@ function smrtConsumer(options = {}) {
 					skipSelf: true
 				});
 				const compile = resolved?.id.endsWith(".svelte") || resolved?.id.endsWith(".css");
-				const compileSvelteBarrel = resolvesToSvelteCondition(packageName, selectivePackage.packageJson, selectivePackage.packageRoot, id, resolved?.id);
+				const importerPath = importer?.split("?")[0];
+				const packageJsonPath = importerPath && path$1.isAbsolute(importerPath) ? findInstalledPackageJson(packageName, path$1.dirname(importerPath)) : void 0;
+				const packageJson = packageJsonPath ? readInstalledPackageJson(packageJsonPath) : selectivePackage.packageJson;
+				const compileSvelteBarrel = packageJson && resolvesToSvelteCondition(packageName, packageJson, packageJsonPath ? path$1.dirname(packageJsonPath) : selectivePackage.packageRoot, id, resolved?.id);
 				if (!compile && !compileSvelteBarrel) return {
 					id,
 					external: true
@@ -953,7 +956,10 @@ async function generateRegistrationFile(manifest, projectRoot) {
 			itemBinding: exportBinding
 		});
 		importedEntryCount++;
-		if (isCollectionClass(def)) continue;
+		if (isCollectionClass(def)) {
+			if (resolveApiActionSet(def, manifest).size > 0) registrations.push(`if (${exportBinding}) ObjectRegistry.registerCollection(${JSON.stringify(qualifiedName)}, ${exportBinding});`);
+			continue;
+		}
 		const logicalName = def.className || exportName;
 		registrationManifests[objectName] = {
 			...manifest,