@saacms/core 0.1.0

package/dist/runtime/cache.d.ts

@@ -0,0 +1,62 @@
+/**
+ * L4 read-through cache resolution for the runtime read paths.
+ *
+ * Per ADR 0021 §6 (cache hierarchy) + ADR 0023 amendment 2026-05-15
+ * (no-platform-dependency principle): caching MUST work with NO plugin
+ * installed. The in-isolate `Map` fallback below IS the correctness layer —
+ * the `@saacms/plugin-cache-kv` adapter (contributed via `services.cache`) is
+ * the cross-isolate efficiency upgrade, not a prerequisite.
+ *
+ * Core must NOT import `@saacms/plugin-cache-kv`; instead `resolveCache`
+ * duck-types a structural `CacheLike` against `getServices(c).cache`. Any
+ * object exposing `get`/`put` functions (the KV adapter's shape) is used
+ * directly; anything else falls back to the module-level Map.
+ *
+ * Tag schema (ADR 0021): `saacms:record:<slug>:<id>`,
+ * `saacms:collection:<slug>`, `saacms:openapi`, `saacms:openapi:role:<role>`.
+ * Write-through invalidation (ADR 0021): a successful write calls
+ * `purgeByTag` so stale entries are dropped immediately rather than waiting
+ * for TTL. Per ADR 0023 this MUST work without the plugin, so the in-isolate
+ * fallback maintains its own `tag → keys` reverse index.
+ */
+import type { Context } from "hono";
+/** What a `get` resolves to — mirrors the KV adapter's `KvCacheEntry`. */
+export interface CacheEntry<T = unknown> {
+    readonly value: T;
+    readonly tags: ReadonlyArray<string>;
+    readonly storedAt: string;
+}
+export interface CachePutOptions {
+    readonly tags?: ReadonlyArray<string>;
+    /** Seconds until the entry is treated as a miss. */
+    readonly expirationTtl?: number;
+}
+/**
+ * Structural cache contract. Deliberately a subset of `KvCacheAdapter`
+ * (`get` + `put` only) so the KV plugin's adapter satisfies it without core
+ * importing the plugin package.
+ */
+export interface CacheLike {
+    get<T = unknown>(key: string): Promise<CacheEntry<T> | null>;
+    put<T = unknown>(key: string, value: T, opts?: CachePutOptions): Promise<void>;
+    /**
+     * Drop every entry tagged `tag`. Mirrors `KvCacheAdapter.purgeByTag` so the
+     * KV plugin's adapter satisfies `CacheLike` without core importing it.
+     * Returns how many keys were removed (for observability/tests).
+     */
+    purgeByTag(tag: string): Promise<{
+        purgedKeys: number;
+    }>;
+}
+/** Test-only: clear fallback state so cases don't leak into each other. */
+export declare function __resetInIsolateCache(): void;
+/** Test-only: override the fallback clock (pass `null` to restore real time). */
+export declare function __setInIsolateClock(fn: (() => number) | null): void;
+/**
+ * Return the plugin-contributed cache when it structurally satisfies
+ * `CacheLike`, else the shared in-isolate fallback. Never returns `null` — a
+ * read route can always cache. A service exposing `get`/`put` but no
+ * `purgeByTag` is wrapped so invalidation degrades safely (ADR 0023).
+ */
+export declare function resolveCache(c: Context): CacheLike;
+//# sourceMappingURL=cache.d.ts.map

package/dist/runtime/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/runtime/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAGnC,0EAA0E;AAC1E,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;IACjB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACrC,oDAAoD;IACpD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IAC5D,GAAG,CAAC,CAAC,GAAG,OAAO,EACb,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,EACR,IAAI,CAAC,EAAE,eAAe,GACrB,OAAO,CAAC,IAAI,CAAC,CAAA;IAChB;;;;OAIG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACzD;AAoDD,2EAA2E;AAC3E,wBAAgB,qBAAqB,IAAI,IAAI,CAK5C;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,IAAI,GAAG,IAAI,CAEnE;AAmGD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,SAAS,CAIlD"}

package/dist/runtime/create-route.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `POST /api/saacms/v1/:collection` — Collection create endpoint per ADR 0018.
+ *
+ * The route resolves the Collection by slug, asserts a `RowStorageAdapter` is
+ * wired, enforces `application/json` content negotiation, parses + validates
+ * the request body against the Collection's Effect Schema, evaluates the
+ * Collection's `access.create` predicate with the validated input bound as
+ * `record` (ADR 0006 §1), inserts via `storage.rows.insert`, and returns a
+ * `201 Created` envelope with a `Location` header pointing at the new
+ * resource (RFC 9110 §10.2.2).
+ *
+ * Schema-validation failures surface as `422` with both a human-readable
+ * `detail` (Effect's `TreeFormatter`) and a structured `extensions.issues`
+ * array (`ArrayFormatter`) so callers can render per-field UI without
+ * re-parsing free-form text.
+ *
+ * Per ADR 0021 §6 the response carries `Cache-Control: no-store` — a
+ * successful write must never be served from a downstream cache.
+ *
+ * Every 4xx/5xx response is an RFC 9457 `application/problem+json` document
+ * via the shared `problemDetails` helper.
+ */
+import type { Env, Hono } from "hono";
+import type { SaacmsConfig } from "../schema/index.ts";
+export declare function mountCreateRoute<E extends Env>(app: Hono<E>, config: SaacmsConfig): void;
+//# sourceMappingURL=create-route.d.ts.map

package/dist/runtime/create-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-route.d.ts","sourceRoot":"","sources":["../../src/runtime/create-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAW,GAAG,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAQ9C,OAAO,KAAK,EAA4B,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAchF,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,GAAG,EAC5C,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,EACZ,MAAM,EAAE,YAAY,GACnB,IAAI,CAsNN"}

package/dist/runtime/delete-route.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `DELETE /api/saacms/v1/:collection/:id` — single-record delete endpoint.
+ *
+ * Idempotent per RFC 9110 §9.2.2: a `DELETE` on an absent resource is a 204 as
+ * long as the caller has not asserted an `If-Match` precondition. When an
+ * `If-Match` is supplied, the route enforces optimistic concurrency against
+ * the same weak ETag the read-route emits (`W/"<slug>:<id>:<updatedAt>"`).
+ *
+ * Every 4xx/5xx response is an RFC 9457 `application/problem+json` document
+ * (ADR 0018 §3) via the shared `problemDetails` helper.
+ */
+import type { Env, Hono } from "hono";
+import type { SaacmsConfig } from "../schema/index.ts";
+export declare function mountDeleteRoute<E extends Env>(app: Hono<E>, config: SaacmsConfig): void;
+//# sourceMappingURL=delete-route.d.ts.map

package/dist/runtime/delete-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delete-route.d.ts","sourceRoot":"","sources":["../../src/runtime/delete-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAW,GAAG,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAI9C,OAAO,KAAK,EAA4B,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAYhF,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,GAAG,EAC5C,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,EACZ,MAAM,EAAE,YAAY,GACnB,IAAI,CAoLN"}

package/dist/runtime/drafts-route.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `/api/saacms/v1/drafts/:pageId` — Page Draft persistence (CONTEXT.md
+ * "Drafts"; ADR 0025 Zone-1 self-serve; ADR 0018 §7 / ADR 0021 §6).
+ *
+ * A Page Draft is the in-flight Puck/Block `layout` tree for a Page id,
+ * owned by saacms in `config.storage.rows` against a reserved table slug
+ * `"saacms_drafts"` (the exact persistence move `pattern-route.ts` makes for
+ * Owner-saved Patterns — internal runtime state in the same `RowStorageAdapter`,
+ * NO schema/contract change). Per CONTEXT.md edits only ever *accumulate* in
+ * Drafts (free, no CI); Publish stays the single deliberate `saacms publish`.
+ *
+ * Load-bearing invariant — **no code path here can trigger Publish/commit/CI.**
+ * This module imports only storage + cache + Problem-Details + the
+ * `afterChange`/`afterDelete` event-phase hook moments (ADR 0013). It NEVER
+ * imports or reaches the publish/compile/git path, and it NEVER resolves the
+ * `beforePublish`/`afterPublish` moments. Saving a Draft is a row write and
+ * nothing else (asserted in `__tests__/drafts-route.test.ts`).
+ *
+ * Conventions mirrored from `create-route` / `pattern-route` / `read-route` /
+ * `update-route` (no machinery is re-implemented):
+ *
+ *  - Shared `problemDetails` (RFC 9457) on every 4xx/5xx.
+ *  - Weak-ETag `W/"saacms_drafts:<pageId>:<updatedAt>"` with
+ *    `If-Match`/412 optimistic concurrency (the multi-editor strategy per
+ *    ADR 0018 §7 / CONTEXT.md "Optimistic concurrency") and
+ *    `If-None-Match`/304 on GET — identical to read/update-route.
+ *  - `Cache-Control: no-store` on every response: a Draft is volatile,
+ *    per-Owner editor state; it must never be served from a downstream cache
+ *    (ADR 0026 §O5). There is deliberately NO L4 read-through here — a Draft
+ *    must always reflect the latest write; correctness over a TTL cache on
+ *    mutable editor state.
+ *  - **Non-enumeration (ADR 0026 §O2 / OWASP API #1).** A Draft that is
+ *    missing OR not accessible returns a 404 whose Problem-Details body is
+ *    byte-identical to the unknown-pageId 404 — an unauthenticated caller
+ *    cannot tell whether a Draft exists. Write denial (PUT/DELETE without a
+ *    logged-in editor) returns 403 (mirrors `pattern-route` / create-route's
+ *    Zone-1 "a logged-in editor is required" rule).
+ *
+ * Design choices specific to Drafts:
+ *
+ *  - **The Page id IS the row id.** One Draft per Page (`id = pageId`), so
+ *    `getById(table, pageId)` is the natural lookup and PUT is an upsert.
+ *  - **`tree` is stored as a JSON string.** The Draft tree is opaque editor
+ *    JSON; serialising it to a single `tree` TEXT column keeps the row a flat
+ *    scalar record (so it binds through any `RowStorageAdapter` unchanged) and
+ *    keeps this route the sole owner of the `saacms_drafts` contract.
+ *  - **Hand-rolled shape validation, no Effect Schema.** A Draft tree is not a
+ *    user-supplied Collection schema; the contract is fixed here (`{ nodes:
+ *    [...] }`, optional `root`), so a tiny inline validator is clearer.
+ */
+import type { Env, Hono } from "hono";
+import type { SaacmsConfig } from "../schema/index.ts";
+/** Persisted Draft row — a flat scalar record (`tree` is serialized JSON). */
+export interface DraftRow {
+    /** The Page id this Draft belongs to (one Draft per Page). */
+    id: string;
+    /** Serialized Draft tree JSON; opaque here. */
+    tree: string;
+    /** User id of the Owner/editor who last saved it; `null` if anon. */
+    createdBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare function mountDraftsRoute<E extends Env>(app: Hono<E>, config: SaacmsConfig): void;
+//# sourceMappingURL=drafts-route.d.ts.map

package/dist/runtime/drafts-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drafts-route.d.ts","sourceRoot":"","sources":["../../src/runtime/drafts-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAGH,OAAO,KAAK,EAAW,GAAG,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAG9C,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,oBAAoB,CAAA;AASjE,8EAA8E;AAC9E,MAAM,WAAW,QAAQ;IACvB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAA;IACV,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAWD,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,GAAG,EAC5C,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,EACZ,MAAM,EAAE,YAAY,GACnB,IAAI,CAwLN"}

package/dist/runtime/health-route.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `GET /api/saacms/v1/health` — liveness/version endpoint.
+ *
+ * Returns a small JSON document the host adapter (or an external probe) can
+ * hit to confirm the runtime is live and to read the deployed `@saacms/core`
+ * version. Per ADR 0021 §6 the response carries `Cache-Control: no-store`
+ * because intermediaries caching a stale "ok" defeats the point of a health
+ * probe.
+ *
+ * `version` is captured once at module init from `package.json`, and
+ * `uptimeMs` is measured from the timestamp the module is first imported —
+ * neither value re-reads any state per request.
+ */
+import type { Env, Hono } from "hono";
+import type { SaacmsConfig } from "../schema/index.ts";
+/**
+ * Register `GET /api/saacms/v1/health` on the supplied Hono app. The `config`
+ * argument is currently unused — kept for parity with the other `mountXRoute`
+ * helpers so a future iteration can surface configured probes (storage,
+ * cache, etc.) without breaking the call sites.
+ */
+export declare function mountHealthRoute<E extends Env>(app: Hono<E>, _config: SaacmsConfig): void;
+//# sourceMappingURL=health-route.d.ts.map

package/dist/runtime/health-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-route.d.ts","sourceRoot":"","sources":["../../src/runtime/health-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAErC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAOtD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,GAAG,EAC5C,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,EACZ,OAAO,EAAE,YAAY,GACpB,IAAI,CAaN"}

package/dist/runtime/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Runtime HTTP handler skeleton.
+ *
+ * Per CONTEXT.md, the runtime handler is the framework-agnostic Hono app the
+ * host adapter mounts. Owns: admin UI, drafts API, publish endpoint, Collection
+ * CRUD via OpenAPI (ADR 0018).
+ *
+ * Live-update channels (SSE / WebSocket) are deliberately NOT in v1 — they're
+ * shipped as opt-in plugins (`@saacms/plugin-realtime`) so the framework can
+ * deploy on the cheapest edge substrate (no sticky connections / Durable
+ * Objects required). Polling + ETag (`If-None-Match`) is the canonical path
+ * for cache coherence and admin-UI refresh; SSE is a turbocharger.
+ */
+import { Hono } from "hono";
+import type { SaacmsConfig } from "../schema/index.ts";
+export * from "./services.ts";
+export * from "./scale-cost.ts";
+/**
+ * Build the saacms Hono app from a resolved config. The returned `Hono` instance
+ * is mountable under any base path the host adapter chooses (defaults to
+ * `/api/saacms` — see `SaacmsConfig.mountPath`).
+ */
+export declare function createSaacmsRuntime(config: SaacmsConfig): Hono;
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAmBtD,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAI/B;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAkE9D"}

package/dist/runtime/index.js

@@ -0,0 +1,17 @@
+import {
+  DEFAULT_THRESHOLDS,
+  collectServices,
+  computeScaleCostSignal,
+  createSaacmsRuntime,
+  getServices
+} from "../index-b59hfany.js";
+import"../index-zgbq60fy.js";
+import"../index-a3pnt8yz.js";
+import"../index-8g8ymd37.js";
+export {
+  getServices,
+  createSaacmsRuntime,
+  computeScaleCostSignal,
+  collectServices,
+  DEFAULT_THRESHOLDS
+};

package/dist/runtime/json-columns.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Schema-driven JSON (de)serialisation at the runtime storage boundary.
+ *
+ * Per ADR 0005 the Effect Schema is the single source of truth; per ADR 0020
+ * the storage adapter is a schema-AGNOSTIC anti-corruption layer that only
+ * knows snake↔camel and never the column types. So the projection of an
+ * object/array domain field to its TEXT column (and back) cannot live in the
+ * adapter — it lives here, at the runtime boundary, where the collection's
+ * Effect Schema is already in hand.
+ *
+ * `to-d1-migration.ts` maps `Schema.Array(X)` / nested `Struct` /
+ * `Schema.Unknown` (and other non-primitive shapes) to a TEXT column with the
+ * note "JSON at the runtime layer". These two functions ARE that layer:
+ *
+ *   - `encodeJsonColumns` — JSON-stringify the complex-typed fields of a record
+ *     immediately BEFORE `rows.insert/update`.
+ *   - `decodeJsonColumns` — JSON-parse them immediately AFTER
+ *     `rows.getById/list`.
+ *
+ * Contract:
+ *   - Which fields are "complex" is derived from the SAME AST the codegen walks
+ *     (post optional/nullable/refinement stripping) — Tuple (Schema.Array),
+ *     TypeLiteral (nested Struct), Unknown/Any/Object keywords. Primitives
+ *     (string/number/boolean/date/literal-union) are never touched.
+ *   - `null` / absent values are left untouched, composing correctly with the
+ *     adapter's NULL→absent read behaviour (ADR 0020) — an absent optional
+ *     complex field never becomes the literal `"null"` string.
+ *   - Symmetric + idempotent for valid data: `decode∘encode = identity`;
+ *     `decode` of an already-decoded (non-string) value is a no-op, so it is
+ *     safe to run on a cache-hit raw record or a freshly-decoded one.
+ *   - Pure: never mutates its input record; returns a shallow copy.
+ */
+import type { AnySchema } from "../schema/index.ts";
+/**
+ * Return a shallow copy of `record` with every complex-typed field
+ * JSON-stringified, ready for `rows.insert/update`. `null`/absent fields are
+ * passed through unchanged so the adapter's NULL handling still applies.
+ * Already-string values are left as-is (idempotent — a re-encode is a no-op),
+ * which keeps it safe if a caller pre-serialised.
+ */
+export declare function encodeJsonColumns<T extends Record<string, unknown>>(schema: AnySchema, record: T): T;
+/**
+ * Return a shallow copy of `record` with every complex-typed field JSON-parsed
+ * back into its domain object/array. Non-string values (already decoded, or
+ * `null`/absent) are left untouched, so this is idempotent and safe to run on
+ * a raw storage row OR an already-decoded one. A value that fails to parse is
+ * left as the original string (defensive — never throw on a read path).
+ */
+export declare function decodeJsonColumns<T extends Record<string, unknown>>(schema: AnySchema, record: T): T;
+//# sourceMappingURL=json-columns.d.ts.map

package/dist/runtime/json-columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-columns.d.ts","sourceRoot":"","sources":["../../src/runtime/json-columns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAmEnD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,CAAC,GACR,CAAC,CAWH;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,CAAC,GACR,CAAC,CAeH"}

package/dist/runtime/list-route.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `GET /api/saacms/v1/:collection` — Collection list endpoint per ADR 0018.
+ *
+ * The route resolves the URL `:collection` slug to a `CollectionDef`, runs the
+ * caller through the Collection's `access.read` predicate (ADR 0006), reads
+ * pagination/sort/filter from the query string, calls
+ * `config.storage.rows.list(slug, opts)`, and returns a HATEOAS-shaped envelope
+ * with `_links.self` + `_links.next` and a `_meta` echo of the request.
+ *
+ * Per ADR 0021 §6 the response carries `Cache-Control: private, max-age=15` and
+ * `Vary: Authorization` so per-user variants don't cross-pollinate.
+ *
+ * Errors are emitted as RFC 9457 Problem Details (ADR 0018) — `404` when the
+ * slug is unknown, `403` when the caller fails the read predicate, `503` when
+ * the host has not wired a `RowStorageAdapter`.
+ */
+import type { Env, Hono } from "hono";
+import type { SaacmsConfig } from "../schema/index.ts";
+export declare function mountListRoute<E extends Env>(app: Hono<E>, config: SaacmsConfig): void;
+//# sourceMappingURL=list-route.d.ts.map

package/dist/runtime/list-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-route.d.ts","sourceRoot":"","sources":["../../src/runtime/list-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAW,GAAG,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAQ9C,OAAO,KAAK,EAA4B,YAAY,EAAE,MAAM,oBAAoB,CAAA;AA8GhF,wBAAgB,cAAc,CAAC,CAAC,SAAS,GAAG,EAC1C,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,EACZ,MAAM,EAAE,YAAY,GACnB,IAAI,CA2MN"}

package/dist/runtime/openapi-route.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `GET /api/saacms/v1/openapi.json` — per-user OpenAPI assembly.
+ *
+ * Composition test for the runtime → codegen → access pipeline per
+ * ADR 0006 + ADR 0018 §2. The route:
+ *
+ *   1. Reads the calling user from `c.get("user")`. A future Better Auth
+ *      middleware is expected to populate that variable before this handler
+ *      runs; until then it is `undefined`/anonymous.
+ *   2. Assembles the full OpenAPI document by calling
+ *      `collectionToOpenApiPaths(coll)` for each registered Collection and
+ *      merging the resulting `paths` + `components.schemas` via
+ *      `mergeOpenApiSpecs`.
+ *   3. Passes the assembled spec through `filterOpenApiForUser` to scope
+ *      routes/fields the caller cannot reach.
+ *
+ * Per ADR 0021 §6 the response carries `Cache-Control: private, max-age=60`
+ * and `Vary: Authorization` so per-user variants don't cross-pollinate.
+ */
+import type { Env, Hono } from "hono";
+import type { SaacmsConfig } from "../schema/index.ts";
+/**
+ * Register `GET /api/saacms/v1/openapi.json` on the supplied Hono app.
+ *
+ * The handler reads `c.get("user")` (set by a future auth middleware) and
+ * passes it through `filterOpenApiForUser`. When no middleware ran, the value
+ * is `undefined` and the filter sees `null` — the anonymous case.
+ */
+export declare function mountOpenApiRoute<E extends Env>(app: Hono<E>, config: SaacmsConfig): void;
+//# sourceMappingURL=openapi-route.d.ts.map

package/dist/runtime/openapi-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-route.d.ts","sourceRoot":"","sources":["../../src/runtime/openapi-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AASrC,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,oBAAoB,CAAA;AA+BrE;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,GAAG,EAC7C,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,EACZ,MAAM,EAAE,YAAY,GACnB,IAAI,CA0DN"}

package/dist/runtime/pattern-route.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `/api/saacms/v1/patterns` — Pattern CRUD (ADR 0025, Operating law Zone 1).
+ *
+ * A Pattern is a runtime-created, Owner-saved reusable arrangement of existing
+ * Block instances with preset content. It is NOT a dev-authored primitive
+ * (there is deliberately no `definePattern`); it is stored *content*, persisted
+ * through the same `RowStorageAdapter` as Collection records — here against a
+ * reserved table slug `"saacms_patterns"`.
+ *
+ * This route is structurally a constrained Collection route. It mirrors the
+ * conventions of `list-route` / `create-route` / `read-route` / `delete-route`
+ * exactly: shared `problemDetails` (RFC 9457) on every 4xx/5xx, `resolveCache`
+ * read-through + tag invalidation (ADR 0021 §6), the
+ * `resolveHooksFor` / `runHooks` event-phase dispatch (ADR 0013), the HATEOAS
+ * envelope, and the weak-ETag / `If-None-Match` / `If-Match` semantics.
+ *
+ * Design choices specific to Patterns:
+ *
+ *  - **Hand-rolled validation, no Effect Schema.** The Collection routes decode
+ *    against a *user-supplied* `collection.schema`; a Pattern's shape is fixed
+ *    by this module (`PatternRecord`), so a tiny inline validator is clearer
+ *    and avoids constructing a Schema for a 2-field contract.
+ *  - **No PUT/PATCH for v1.** Editing a Pattern in the UI is delete-then-create
+ *    (Patterns are recreate-not-edit), which keeps the route surface minimal.
+ *  - **Access (v1, simplest correct rule).** Patterns are admin-surface
+ *    content: writes (POST/DELETE) require a logged-in user (`c.get("user")`);
+ *    reads are open (consistent with the rest of the runtime treating absent
+ *    auth as open). Finer-grained per-Pattern access is a future Escalation.
+ */
+import type { Env, Hono } from "hono";
+import type { SaacmsConfig } from "../schema/index.ts";
+/**
+ * The persisted Pattern shape. `tree` is the serialized Puck block-subtree
+ * JSON — opaque to this route (the editor produces/consumes it).
+ */
+export interface PatternRecord {
+    id: string;
+    /** Human label, required, 1..120 chars. */
+    name: string;
+    /** Serialized Puck block-subtree JSON; opaque here. */
+    tree: unknown;
+    /** User id of the Owner/editor who saved it; `null` if anon-disabled. */
+    createdBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare function mountPatternRoute<E extends Env>(app: Hono<E>, config: SaacmsConfig): void;
+//# sourceMappingURL=pattern-route.d.ts.map

package/dist/runtime/pattern-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern-route.d.ts","sourceRoot":"","sources":["../../src/runtime/pattern-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,KAAK,EAAW,GAAG,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAG9C,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAoBjE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,IAAI,EAAE,OAAO,CAAA;IACb,yEAAyE;IACzE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,GAAG,EAC7C,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,EACZ,MAAM,EAAE,YAAY,GACnB,IAAI,CAmPN"}

package/dist/runtime/problem-details.d.ts

@@ -0,0 +1,32 @@
+/**
+ * RFC 9457 Problem Details helper — shared across runtime route handlers.
+ *
+ * Per ADR 0018 §3, every 4xx/5xx response from the saacms runtime is an
+ * `application/problem+json` document. The lifted helper centralises the
+ * `type` URI namespace + content-type so individual routes only express
+ * `{ type, title, status, detail? }`.
+ *
+ * `type` URIs are rooted at `https://saacms.dev/errors/`; the path segment
+ * after the slash is the error code. New error types are documented in
+ * `docs/errors.md` (TODO) so they're discoverable through HATEOAS hop.
+ */
+import type { Context } from "hono";
+export declare const PROBLEM_TYPE_BASE = "https://saacms.dev/errors";
+export type ProblemStatus = 400 | 401 | 403 | 404 | 405 | 409 | 410 | 412 | 415 | 422 | 500 | 503;
+export interface ProblemDetailsOptions {
+    /** Stable error code; appended to `PROBLEM_TYPE_BASE` to form the `type` URI. */
+    readonly code: string;
+    /** Short human-readable title; per RFC 9457 §3.1 should not change between occurrences. */
+    readonly title: string;
+    /** HTTP status — must match the response status. */
+    readonly status: ProblemStatus;
+    /** Free-text human-readable explanation of THIS occurrence. */
+    readonly detail?: string;
+    /** URI identifying the specific occurrence (e.g. a request id). */
+    readonly instance?: string;
+    /** Free-form extension members; merged into the document at the top level. */
+    readonly extensions?: Readonly<Record<string, unknown>>;
+}
+/** Emit an RFC 9457 Problem Details response on the given Hono context. */
+export declare function problemDetails(c: Context, options: ProblemDetailsOptions): Response;
+//# sourceMappingURL=problem-details.d.ts.map

package/dist/runtime/problem-details.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"problem-details.d.ts","sourceRoot":"","sources":["../../src/runtime/problem-details.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,eAAO,MAAM,iBAAiB,8BAA8B,CAAA;AAE5D,MAAM,MAAM,aAAa,GACrB,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,CAAA;AAEP,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACxD;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAC5B,CAAC,EAAE,OAAO,EACV,OAAO,EAAE,qBAAqB,GAC7B,QAAQ,CAiBV"}

package/dist/runtime/put-route.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `PUT /api/saacms/v1/:collection/:id` — full-replace endpoint per RFC 9110 §9.3.4.
+ *
+ * Unlike PATCH (RFC 7396 shallow merge), PUT replaces the record outright: the
+ * request body is validated as a complete Collection record (Effect
+ * `Schema.decodeUnknownEither`) and the full validated value is handed to the
+ * row-storage adapter — every column tracked by the Schema is overwritten with
+ * what the caller supplied, no merge against the prior row.
+ *
+ * Optimistic concurrency follows RFC 9110 §13 — when `If-Match` is supplied we
+ * compute the same weak ETag the read route emits (`W/"<slug>:<id>:<updatedAt>"`)
+ * and short-circuit to `412` on mismatch (or when the record exposes no
+ * `updatedAt`, since the precondition cannot be satisfied). All 4xx/5xx
+ * responses are RFC 9457 Problem Details via the shared helper, per ADR 0018 §3.
+ */
+import type { Env, Hono } from "hono";
+import type { SaacmsConfig } from "../schema/index.ts";
+export declare function mountPutRoute<E extends Env>(app: Hono<E>, config: SaacmsConfig): void;
+//# sourceMappingURL=put-route.d.ts.map

package/dist/runtime/put-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"put-route.d.ts","sourceRoot":"","sources":["../../src/runtime/put-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAW,GAAG,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE9C,OAAO,KAAK,EAA4B,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAgBhF,wBAAgB,aAAa,CAAC,CAAC,SAAS,GAAG,EACzC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,EACZ,MAAM,EAAE,YAAY,GACnB,IAAI,CA+MN"}

package/dist/runtime/read-route.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `GET /api/saacms/v1/:collection/:id` — single-record read endpoint.
+ *
+ * The route resolves the Collection by slug, loads the row via
+ * `config.storage.rows.getById`, evaluates the Collection's `access.read`
+ * predicate with the loaded record bound (per ADR 0006 §2 — record-level
+ * grain), and returns a HATEOAS-shaped envelope on success.
+ *
+ * Per ADR 0021 §6 the response carries `Cache-Control: private, max-age=30`
+ * and `Vary: Authorization` so per-user variants don't cross-pollinate. When
+ * the row exposes an `updatedAt` ISO timestamp we emit a weak `ETag`
+ * (RFC 9110 §8.8.3) and short-circuit to `304` on a matching `If-None-Match`.
+ *
+ * Lifecycle hooks (ADR 0013) bracket the fetch: command-phase `beforeRead`
+ * runs as a GATE before any cache/storage access (a failed gate is `403`
+ * `hook-rejected`), and event-phase `afterRead` runs best-effort after the
+ * ETag/304 decision (skipped on the 304 path) and MAY transform the outgoing
+ * representation.
+ *
+ * Every 4xx/5xx response is an RFC 9457 `application/problem+json` document
+ * per ADR 0018 §3 via the shared `problemDetails` helper.
+ */
+import type { Env, Hono } from "hono";
+import type { SaacmsConfig } from "../schema/index.ts";
+export declare function mountReadRoute<E extends Env>(app: Hono<E>, config: SaacmsConfig): void;
+//# sourceMappingURL=read-route.d.ts.map

package/dist/runtime/read-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-route.d.ts","sourceRoot":"","sources":["../../src/runtime/read-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAW,GAAG,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAI9C,OAAO,KAAK,EAA4B,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAchF,wBAAgB,cAAc,CAAC,CAAC,SAAS,GAAG,EAC1C,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,EACZ,MAAM,EAAE,YAAY,GACnB,IAAI,CAuON"}

package/dist/runtime/scale-cost.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Scale & Cost signal engine. Per ADR 0025 + ADR 0021 §8 + CONTEXT.md
+ * "Scale & Cost panel": ships the **objective signal**, never prices — a
+ * hardcoded Cloudflare/GitHub pricing table is a rot trap, so the Developer
+ * supplies the price layer downstream. saacms emits only the structural facts
+ * + crossed-threshold markers.
+ *
+ * Two independent cost-crossover axes:
+ *   - **serve**   — dynamic Collection-read volume × traffic → SQL DB cost.
+ *                   Per-collection; mitigated by wiring a cache/KV tier.
+ *   - **publish** — publishes/window × CI minutes × rebuild → Actions cost.
+ *                   The Draft-batches-Publish invariant already keeps CI
+ *                   O(publishes) not O(edits); this axis flags when even the
+ *                   O(publishes) volume crosses the GitHub plan allowance.
+ *
+ * This is a **pure** function in the discipline of `codegen/to-d1-migration.ts`:
+ * deterministic, no I/O, no globals, no `Date.now()`. Same snapshot in → same
+ * signal out. It does NOT collect metrics — collection is a separate plugin
+ * concern. The caller hands in a structural snapshot (and, for publish, the
+ * client's GitHub-plan free-minutes allowance, since we never hardcode it).
+ *
+ * ADR 0021 §8 names the upstream cache metrics this consumes in aggregate:
+ * `saacms.cache.hits{tier,key_kind}`, `saacms.cache.misses{...}`.
+ */
+export interface MetricsSnapshot {
+    /** Observation window in days (e.g. 30). Projections normalise to a 30-day month. */
+    readonly windowDays: number;
+    readonly collections: ReadonlyArray<{
+        readonly slug: string;
+        /** Dynamic (non-cached) Collection reads observed in the window. */
+        readonly dynamicReads: number;
+        readonly cacheHits: number;
+        readonly cacheMisses: number;
+    }>;
+    readonly publish: {
+        /** Publishes observed in the window. */
+        readonly publishes: number;
+        /** Mean CI minutes per publish. */
+        readonly avgCiMinutes: number;
+        /**
+         * The client's GitHub-plan free Actions minutes per month. The caller
+         * supplies this — saacms never hardcodes plan pricing/allowances.
+         */
+        readonly githubFreeMinutesPerMonth: number;
+    };
+}
+export interface ScaleCostThresholds {
+    /** reads/day at/above which serve volume is in the superlinear region. */
+    readonly serveDynamicReadsPerDay: number;
+    /** Cache hit-rate below which a high-volume Collection counts as crossed. */
+    readonly serveMinCacheHitRate: number;
+    /** Projected Actions-minutes/mo ≥ this fraction of the free allowance = crossed. */
+    readonly publishMonthlyMinutesFraction: number;
+}
+export declare const DEFAULT_THRESHOLDS: ScaleCostThresholds;
+export interface AxisSignal {
+    readonly axis: "serve" | "publish";
+    readonly crossed: boolean;
+    /** Human-readable, plain-language facts. NO prices. */
+    readonly metricLines: ReadonlyArray<string>;
+    /** The action (not a price) the Developer should take. */
+    readonly recommendedAction: string;
+    /** Collection slug for serve; omitted for publish. */
+    readonly subject?: string;
+}
+export interface ScaleCostSignal {
+    readonly window: {
+        readonly days: number;
+    };
+    /** One serve entry per over-threshold Collection + one publish entry when crossed. */
+    readonly axes: ReadonlyArray<AxisSignal>;
+    readonly anyCrossed: boolean;
+    /** ONE plain-language sentence for the Owner banner; "" when nothing crossed. */
+    readonly ownerSummary: string;
+}
+/**
+ * Compute the objective Scale & Cost signal from a structural snapshot.
+ *
+ * Pure: deterministic, no I/O, no globals, no clock. The output contains zero
+ * prices/currency — only structural facts + crossed markers + the action the
+ * Developer should take (the Developer attaches the price downstream).
+ */
+export declare function computeScaleCostSignal(snapshot: MetricsSnapshot, thresholds?: Partial<ScaleCostThresholds>): ScaleCostSignal;
+//# sourceMappingURL=scale-cost.d.ts.map

package/dist/runtime/scale-cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scale-cost.d.ts","sourceRoot":"","sources":["../../src/runtime/scale-cost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,MAAM,WAAW,eAAe;IAC9B,qFAAqF;IACrF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC;QAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,oEAAoE;QACpE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;QAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;QAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAC7B,CAAC,CAAA;IACF,QAAQ,CAAC,OAAO,EAAE;QAChB,wCAAwC;QACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;QAC1B,mCAAmC;QACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;QAC7B;;;WAGG;QACH,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAA;KAC3C,CAAA;CACF;AAMD,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAA;IACxC,6EAA6E;IAC7E,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;IACrC,oFAAoF;IACpF,QAAQ,CAAC,6BAA6B,EAAE,MAAM,CAAA;CAC/C;AAED,eAAO,MAAM,kBAAkB,EAAE,mBAIvB,CAAA;AAMV,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC3C,0DAA0D;IAC1D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1C,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAA;IACxC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B;AAgHD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,eAAe,EACzB,UAAU,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GACxC,eAAe,CAyBjB"}