@selvajs/server 1.0.0-beta.8 → 1.0.0

package/dist/compute/safe-url.js

@@ -2,31 +2,29 @@ import { lookup } from 'node:dns/promises';
 import { isIP } from 'node:net';
 import { NoopLogger } from '@selvajs/platform';
 /**
- * SSRF guard for `loadRemoteDefinition`. Without it an authenticated user could
- * submit `http://169.254.169.254/...` (cloud metadata) or any intranet endpoint
- * and the server would fetch it on their behalf.
+ * SSRF guard for the remote-definition fetch. Without it an authenticated user
+ * could submit `http://169.254.169.254/...` (cloud metadata) or any intranet
+ * endpoint and the server would fetch it on their behalf.
  *
  * Two layers:
  *
- *   1. `isSafeRemoteDefinitionUrl` — synchronous literal pre-filter. Rejects
- *      protocol, hostname literals, and every IP *encoding* that maps to a
- *      blocked address (dotted-decimal, integer, octal, hex, short-form,
- *      IPv4-mapped IPv6). Fast and DNS-free; safe to call anywhere.
+ *   1. `isSafeRemoteDefinitionUrl` — synchronous, DNS-free literal filter.
+ *      Rejects the protocol, hostname literals, and every IP *encoding* that
+ *      maps to a blocked address: dotted-decimal, integer, octal, hex,
+ *      short-form, IPv4-mapped IPv6.
+ *   2. `assertSafeRemoteDefinitionUrl` — resolves the hostname and re-checks the
+ *      *resolved* IP, catching a public name that points at a private one.
  *
- *   2. `assertSafeRemoteDefinitionUrl` — resolves the hostname via DNS and
- *      re-checks the *resolved* IP. This is the real defense: it catches a
- *      public name that resolves to a private IP, which the literal filter
- *      can't see. Still not bulletproof against rebinding (the IP can change
- *      between this lookup and fetch's own); for that the caller would have to
- *      connect to the resolved IP directly. Connecting by IP is a larger change
- *      — this closes the practical bypasses (literal encodings + a DNS record
- *      that points inward) which is what an attacker actually reaches for.
+ * Neither is bulletproof against DNS rebinding — the IP can change between our
+ * lookup and fetch's own. Closing that needs the caller to connect to the
+ * resolved IP directly, a much larger change; these two layers close the
+ * bypasses an attacker actually reaches for (literal encodings, and a public
+ * name whose record points inward).
  */
 /**
  * True when `ip` (a normalized IPv4 or IPv6 literal from `isIP`/`dns.lookup`)
  * is loopback, private, link-local, or otherwise must-not-fetch. IPv4-mapped
- * IPv6 (`::ffff:a.b.c.d`) is unwrapped to its embedded IPv4 first so the v4
- * rules apply.
+ * IPv6 (`::ffff:a.b.c.d`) is unwrapped first so the v4 rules apply.
  */
 function isBlockedIp(ip) {
     let addr = ip.toLowerCase();
@@ -76,9 +74,10 @@ function isBlockedIp(ip) {
 /**
  * Parse a bare-IPv4 hostname in any encoding browsers/glibc accept — integer
  * (`2130706433`), octal (`0177.0.0.1`), hex (`0x7f000001`), and short forms
- * (`127.1`) — into a canonical dotted-decimal string. Returns null when the
- * host is not a numeric IPv4 literal (i.e. it's a real name or already-valid
- * dotted-quad, which callers handle separately).
+ * (`127.1`) — into canonical dotted-decimal. An already-valid dotted-quad comes
+ * back unchanged. Returns null only when the host is not a numeric IPv4 literal
+ * at all, i.e. it's a real name — which is what callers use to decide whether
+ * DNS resolution is needed.
  */
 function canonicalizeNumericIpv4(host) {
     // Already a clean dotted-quad — let isIP handle it directly.
@@ -133,10 +132,10 @@ function canonicalizeNumericIpv4(host) {
     return [(value >>> 24) & 0xff, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff].join('.');
 }
 /**
- * Synchronous literal pre-filter. Rejects bad schemes, loopback hostnames, and
- * any IP literal (in any encoding) that resolves to a blocked address. Does NOT
+ * Synchronous literal pre-filter: rejects bad schemes, loopback hostnames, and
+ * any IP literal (in any encoding) that maps to a blocked address. Does NOT
  * perform DNS — a public *name* that points at a private IP passes here and is
- * caught by `assertSafeRemoteDefinitionUrl`.
+ * caught only by `assertSafeRemoteDefinitionUrl`.
  */
 export function isSafeRemoteDefinitionUrl(raw) {
     let parsed;
@@ -170,13 +169,12 @@ export function isSafeRemoteDefinitionUrl(raw) {
 /**
  * Full SSRF check: literal pre-filter, then resolve every A/AAAA record and
  * reject if *any* resolved IP is blocked. Returns the original URL on success
- * so callers can `await assertSafeRemoteDefinitionUrl(url)` inline. Throws on
- * any rejection.
+ * so callers can `await assertSafeRemoteDefinitionUrl(url)` inline.
+ *
+ * Every rejection throws the same generic message so the caller gets no oracle;
+ * which host was blocked and by which layer is logged server-side instead.
  */
 export async function assertSafeRemoteDefinitionUrl(raw, logger = new NoopLogger()) {
-    // Security-relevant event: the thrown message is deliberately generic (no
-    // oracle for the caller), so log the specifics server-side instead — which
-    // host was blocked and by which layer.
     if (!isSafeRemoteDefinitionUrl(raw)) {
         logger.warn('Blocked remote definition URL', {
             component: 'Compute/ssrf',

package/dist/compute/safe-url.js.map

@@ -1 +1 @@
-{"version":3,"file":"safe-url.js","sourceRoot":"","sources":["../../src/compute/safe-url.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"safe-url.js","sourceRoot":"","sources":["../../src/compute/safe-url.ts"],"names":[],"mappings":"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"}

package/dist/definitions/definition-service.d.ts

@@ -1,11 +1,8 @@
 import type { IDataProvider, IStorageProvider, RequestContext, DefinitionRecord, DefinitionFileExt, DefinitionVersion, UpdateMetadataInput, UISchema } from '@selvajs/platform';
 /**
- * Input passed to `DefinitionService.create`. Carries everything the service
- * needs to assemble a `DefinitionRecord` plus orchestrate the v1 upload.
- *
- * Distinct from `CreateDefinitionInputSchema` exported by
- * `@selvajs/platform/definitions`, which validates the user-facing
- * HTTP body (no guid/ownerId — those are derived server-side).
+ * Not the HTTP body — that's `CreateDefinitionInputSchema` in
+ * `@selvajs/platform/definitions`, which has no guid/ownerId because those are
+ * derived server-side.
  */
 export interface CreateDefinitionRecord {
     guid: string;
@@ -21,33 +18,13 @@ export interface CreateDefinitionRecord {
     computeServerId?: string;
 }
 /**
- * Orchestrates writes that span IDataProvider + IStorageProvider for the
- * spec §6 versioning model. Lives in @selvajs/selva (not @selvajs/platform)
- * because it is application orchestration, not platform contract.
- *
- * Ordering rules:
- *
- *   create — metadata-first, then v1:
- *     1. Write record with status='pending', both pointers null
- *     2. Upload v1 blob to versions/v1.{ext}
- *     3. Insert DefinitionVersion row v1
- *     4. `attachInitialVersion` — atomically set live + draft pointers and
- *        flip status to 'draft' in a single store operation.
- *   Step 4 is one round-trip so a mid-flight failure can't leave a partial
- *   state (status='draft' with null pointers, or status='pending' with
- *   pointers set). If step 2 fails the record stays 'pending' with no
- *   blob and is filtered out of list endpoints by default.
- *
- *   uploadVersion — append-only:
- *     1. Reserve next versionNumber from the record's monotonic counter
- *     2. Upload blob to versions/v{N}.{ext}
- *     3. Insert DefinitionVersion row
- *     4. Advance draft pointer (live unchanged)
- *
- *   publish — pointer flip only, no blob writes.
+ * Orchestrates writes spanning IDataProvider + IStorageProvider. Application
+ * orchestration, not platform contract — hence not in @selvajs/platform.
  *
- *   deleteVersion — store enforces "not referenced by live/draft"; on
- *   success, delete the underlying blob.
+ * Methods that write both metadata and blobs order the two so a mid-flight
+ * failure leaves a state the API can still serve; those reasons sit inline at
+ * each write. `publish` and `updateMeta` flip pointers/metadata only and touch
+ * storage not at all.
  */
 export declare class DefinitionService {
     private data;
@@ -58,15 +35,13 @@ export declare class DefinitionService {
         version: DefinitionVersion;
     }>;
     /**
-     * Upload a new version of an existing definition. Writes the blob, inserts
-     * the version row, and advances the draft pointer. `live` is unchanged —
-     * use `publish` to promote.
+     * Advances the draft pointer only — `live` is unchanged. Use `publish` to
+     * promote.
      */
     uploadVersion(ctx: RequestContext, guid: string, file: Uint8Array, ext: DefinitionFileExt, originalName: string, schema: UISchema, changeNote?: string): Promise<DefinitionVersion>;
     /**
-     * Advance the live channel. If `versionId` is omitted, promotes the
-     * current draft. Pass an arbitrary version id to roll forward/back —
-     * spec §6 makes rollback a first-class operation.
+     * Moves the live channel to `versionId`, or to the current draft if omitted.
+     * Any version id is accepted, so this rolls backward as well as forward.
      */
     publish(ctx: RequestContext, guid: string, versionId?: string): Promise<DefinitionVersion>;
     deleteVersion(ctx: RequestContext, guid: string, versionId: string): Promise<void>;

package/dist/definitions/definition-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definition-service.d.ts","sourceRoot":"","sources":["../../src/definitions/definition-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,QAAQ,EACR,MAAM,mBAAmB,CAAC;AAG3B;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,iBAAiB;IAE5B,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,OAAO;gBADP,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB;IAG5B,MAAM,CACX,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,sBAAsB,EAC7B,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,QAAQ,GACd,OAAO,CAAC;QAAE,MAAM,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,iBAAiB,CAAA;KAAE,CAAC;IA8DpE;;;;OAIG;IACG,aAAa,CAClB,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,iBAAiB,EACtB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,QAAQ,EAChB,UAAU,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,CAAC;IAmC7B;;;;OAIG;IACG,OAAO,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAoB1F,aAAa,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUlF,UAAU,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxF,cAAc,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAQzF,MAAM,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAc9D"}
+{"version":3,"file":"definition-service.d.ts","sourceRoot":"","sources":["../../src/definitions/definition-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,QAAQ,EACR,MAAM,mBAAmB,CAAC;AAG3B;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,qBAAa,iBAAiB;IAE5B,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,OAAO;gBADP,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB;IAG5B,MAAM,CACX,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,sBAAsB,EAC7B,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,QAAQ,GACd,OAAO,CAAC;QAAE,MAAM,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,iBAAiB,CAAA;KAAE,CAAC;IA4DpE;;;OAGG;IACG,aAAa,CAClB,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,iBAAiB,EACtB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,QAAQ,EAChB,UAAU,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,CAAC;IAkC7B;;;OAGG;IACG,OAAO,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAoB1F,aAAa,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUlF,UAAU,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxF,cAAc,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAQzF,MAAM,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAW9D"}

package/dist/definitions/definition-service.js

@@ -1,33 +1,13 @@
 import { randomUUID } from 'node:crypto';
 import { ProviderError, definitionPaths } from '@selvajs/platform';
 /**
- * Orchestrates writes that span IDataProvider + IStorageProvider for the
- * spec §6 versioning model. Lives in @selvajs/selva (not @selvajs/platform)
- * because it is application orchestration, not platform contract.
+ * Orchestrates writes spanning IDataProvider + IStorageProvider. Application
+ * orchestration, not platform contract — hence not in @selvajs/platform.
  *
- * Ordering rules:
- *
- *   create — metadata-first, then v1:
- *     1. Write record with status='pending', both pointers null
- *     2. Upload v1 blob to versions/v1.{ext}
- *     3. Insert DefinitionVersion row v1
- *     4. `attachInitialVersion` — atomically set live + draft pointers and
- *        flip status to 'draft' in a single store operation.
- *   Step 4 is one round-trip so a mid-flight failure can't leave a partial
- *   state (status='draft' with null pointers, or status='pending' with
- *   pointers set). If step 2 fails the record stays 'pending' with no
- *   blob and is filtered out of list endpoints by default.
- *
- *   uploadVersion — append-only:
- *     1. Reserve next versionNumber from the record's monotonic counter
- *     2. Upload blob to versions/v{N}.{ext}
- *     3. Insert DefinitionVersion row
- *     4. Advance draft pointer (live unchanged)
- *
- *   publish — pointer flip only, no blob writes.
- *
- *   deleteVersion — store enforces "not referenced by live/draft"; on
- *   success, delete the underlying blob.
+ * Methods that write both metadata and blobs order the two so a mid-flight
+ * failure leaves a state the API can still serve; those reasons sit inline at
+ * each write. `publish` and `updateMeta` flip pointers/metadata only and touch
+ * storage not at all.
  */
 export class DefinitionService {
     data;
@@ -61,14 +41,13 @@ export class DefinitionService {
             updatedAt: now,
             deletedAt: null
         };
-        // 1. Metadata first — if this fails there's nothing to clean up.
+        // Metadata first — if this fails there's nothing to clean up.
         await this.data.definitions.create(ctx, record);
-        // 2. v1 blob — if this fails the record stays 'pending' and is hidden
-        //    from default list queries.
+        // If the blob write fails, the record stays 'pending' and is hidden from
+        // default list queries.
         const versionId = randomUUID();
         const fileKey = definitionPaths.version(input.guid, 1, input.fileExt);
         await this.storage.put(fileKey, file, 'application/octet-stream');
-        // 3. Version row.
         const version = {
             id: versionId,
             definitionId: input.guid,
@@ -82,10 +61,9 @@ export class DefinitionService {
             schemaExtractedAt: now
         };
         await this.data.definitions.createVersion(ctx, version);
-        // 4. Atomically point both channels at v1 and flip status='draft' in a
-        //    single store operation. Replaces three separate writes
-        //    (setLiveVersion + setDraftVersion + update) — see the class
-        //    header for why ordering matters here.
+        // Points both channels at v1 and flips status='draft' in ONE store
+        // operation. Doing it as three writes leaves a partial state on failure:
+        // status='draft' with null pointers, or 'pending' with pointers set.
         await this.data.definitions.attachInitialVersion(ctx, input.guid, versionId);
         return {
             record: { ...record, status: 'draft', liveVersionId: versionId, draftVersionId: versionId },
@@ -93,18 +71,16 @@ export class DefinitionService {
         };
     }
     /**
-     * Upload a new version of an existing definition. Writes the blob, inserts
-     * the version row, and advances the draft pointer. `live` is unchanged —
-     * use `publish` to promote.
+     * Advances the draft pointer only — `live` is unchanged. Use `publish` to
+     * promote.
      */
     async uploadVersion(ctx, guid, file, ext, originalName, schema, changeNote) {
         const existing = await this.data.definitions.get(ctx, guid);
         if (!existing)
             throw new ProviderError(`Definition not found: ${guid}`, 404);
-        // Reserve the next version number from the record's monotonic counter — NOT
-        // max(existing)+1, which reused a number after delete-latest and collided
-        // the `fileKey` (stale blob served for new content). The counter only ever
-        // advances, so a delete-then-reupload gets a fresh number and fresh key.
+        // Monotonic counter, NOT max(existing)+1 — the latter reuses a number after
+        // delete-latest and collides the `fileKey`, serving a stale blob for new
+        // content.
         const next = await this.data.definitions.reserveNextVersionNumber(ctx, guid);
         const versionId = randomUUID();
         const fileKey = definitionPaths.version(guid, next, ext);
@@ -129,9 +105,8 @@ export class DefinitionService {
         return version;
     }
     /**
-     * Advance the live channel. If `versionId` is omitted, promotes the
-     * current draft. Pass an arbitrary version id to roll forward/back —
-     * spec §6 makes rollback a first-class operation.
+     * Moves the live channel to `versionId`, or to the current draft if omitted.
+     * Any version id is accepted, so this rolls backward as well as forward.
      */
     async publish(ctx, guid, versionId) {
         const existing = await this.data.definitions.get(ctx, guid);
@@ -171,16 +146,13 @@ export class DefinitionService {
         return url;
     }
     async delete(ctx, guid) {
-        // CONTRACT (spec §9): metadata is soft-deleted (preserved for audit,
-        // restorable by clearing `deleted_at`); blobs are HARD-deleted. The
-        // record is the audit trail; the blobs are storage cost.
+        // Metadata is soft-deleted (audit trail, restorable by clearing
+        // `deleted_at`); blobs are HARD-deleted.
         //
-        // Order matters. Metadata first so the API immediately hides the
-        // record (RLS / `deleted_at IS NULL` filter). If the blob wipe then
-        // fails, the orphan storage is unreachable through the API — a
-        // retention sweep can clean it up later. The reverse order leaves a
-        // window where the record is still alive but its blobs are gone — a
-        // 404 source for any in-flight reader.
+        // Metadata first, so the API hides the record immediately. A failed blob
+        // wipe then leaves orphan storage that no reader can reach, for a
+        // retention sweep to collect. The reverse order leaves the record alive
+        // with its blobs gone — a 404 for any in-flight reader.
         await this.data.definitions.delete(ctx, guid);
         await this.storage.deletePrefix(definitionPaths.prefix(guid));
     }

package/dist/definitions/definition-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"definition-service.js","sourceRoot":"","sources":["../../src/definitions/definition-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"definition-service.js","sourceRoot":"","sources":["../../src/definitions/definition-service.ts"],"names":[],"mappings":"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"}

package/dist/definitions/index.d.ts

@@ -1,5 +1,5 @@
 export { DefinitionService, type CreateDefinitionRecord } from './definition-service.js';
 export { fetchSchemaFromCompute, postSchemaFormData, assertSupportedSchemaVersion, readSchemaResults, SchemaExtractionError } from './schema-extraction.js';
 export type { SchemaExtractionResult } from './schema-extraction.js';
-export { createDefinitionLoader, DefinitionLoadError, type DefinitionChannel, type DefinitionLoader, type DefinitionLoaderDeps, type DefinitionLoadErrorKind, type LoadedDefinition } from './load-for-render.js';
+export { createDefinitionLoader, DefinitionLoadError, type DefinitionChannel, type DefinitionLoader, type DefinitionLoaderDeps, type DefinitionLoadErrorKind, type DefinitionLoadOptions, type LoadedDefinition } from './load-for-render.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/definitions/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEzF,OAAO,EACN,sBAAsB,EACtB,kBAAkB,EAClB,4BAA4B,EAC5B,iBAAiB,EACjB,qBAAqB,EACrB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAErE,OAAO,EACN,sBAAsB,EACtB,mBAAmB,EACnB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/definitions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEzF,OAAO,EACN,sBAAsB,EACtB,kBAAkB,EAClB,4BAA4B,EAC5B,iBAAiB,EACjB,qBAAqB,EACrB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAErE,OAAO,EACN,sBAAsB,EACtB,mBAAmB,EACnB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,MAAM,sBAAsB,CAAC"}

package/dist/definitions/index.js

@@ -1,7 +1,3 @@
-// Definitions server slice — the write orchestration (DefinitionService), the
-// compute-schema extraction/validation gate, and the render loader. All
-// composition-root wiring (stores, warm-client cache, server resolution) is
-// injected; access gating stays with the calling app.
 export { DefinitionService } from './definition-service.js';
 export { fetchSchemaFromCompute, postSchemaFormData, assertSupportedSchemaVersion, readSchemaResults, SchemaExtractionError } from './schema-extraction.js';
 export { createDefinitionLoader, DefinitionLoadError } from './load-for-render.js';

package/dist/definitions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/definitions/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,wEAAwE;AACxE,4EAA4E;AAC5E,sDAAsD;AAEtD,OAAO,EAAE,iBAAiB,EAA+B,MAAM,yBAAyB,CAAC;AAEzF,OAAO,EACN,sBAAsB,EACtB,kBAAkB,EAClB,4BAA4B,EAC5B,iBAAiB,EACjB,qBAAqB,EACrB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACN,sBAAsB,EACtB,mBAAmB,EAMnB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/definitions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAA+B,MAAM,yBAAyB,CAAC;AAEzF,OAAO,EACN,sBAAsB,EACtB,kBAAkB,EAClB,4BAA4B,EAC5B,iBAAiB,EACjB,qBAAqB,EACrB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACN,sBAAsB,EACtB,mBAAmB,EAOnB,MAAM,sBAAsB,CAAC"}

package/dist/definitions/load-for-render.d.ts

@@ -26,11 +26,11 @@ export interface DefinitionLoaderDeps {
     storage: Pick<IStorageProvider, 'get'>;
     definitions: Pick<IDefinitionStore, 'getVersion' | 'setVersionSchema'>;
     projects: Pick<IProjectStore, 'getProject'>;
-    /** §3 resolution order: definition pin → org default override → global default. */
+    /** Resolution order: definition pin → org default override → global default. */
     resolveServer: (ctx: RequestContext, orgId: string | null, opts: {
         definitionPin: string | null;
     }) => Promise<ComputeServerConfig>;
-    /** Shared warm-client cache (ADR 0004: keyed by server id, definition-guid affinity header). */
+    /** Shared warm-client cache, keyed by server id with a definition-guid affinity header. */
     getClient: (server: ComputeServerConfig, opts: {
         definitionGuid: string;
     }) => Promise<{
@@ -39,32 +39,35 @@ export interface DefinitionLoaderDeps {
     /** Schema extraction; defaults to `fetchSchemaFromCompute`. Injectable for tests. */
     fetchSchema?: (bytes: Uint8Array, server: ComputeServerConfig) => Promise<UISchema>;
     /**
-     * Verbose IO diagnostics — when set, an unhealthy IO result (empty inputs /
-     * parse / load errors) also dumps the raw /io wire shape so
-     * casing/serialization mismatches are visible.
+     * When set, an unhealthy IO result also dumps the raw /io wire shape, making
+     * casing/serialization mismatches visible.
      */
     computeDebug?: boolean;
-    /**
-     * Legacy diagnostic sink, kept for callers that already pass one. When set it
-     * receives the rendered strings and `logger` is not used for these warnings.
-     */
+    /** Legacy diagnostic sink. When set it takes the warnings below instead of `logger`. */
     onWarn?: (message: string, detail?: string) => void;
     /**
-     * Structured logger for the diagnostics below. Defaults to `NoopLogger`, so a
-     * consumer that wires nothing gets silence rather than unsolicited stdout.
+     * Defaults to `NoopLogger`, so a consumer that wires nothing gets silence
+     * rather than unsolicited stdout.
      */
     logger?: ILogger;
 }
-export type DefinitionLoader = (ctx: RequestContext, record: DefinitionRecord, channel: DefinitionChannel, explicitVersionId?: string | null) => Promise<LoadedDefinition>;
+export interface DefinitionLoadOptions {
+    /**
+     * For callers that read only schema STRUCTURE (input ids, `source.key`,
+     * widget types — anything persisted at upload). A fresh cached schema then
+     * returns without touching compute, whose multi-second connect otherwise
+     * dominates a page resolving several definitions.
+     *
+     * Leave unset (the default) for anything that RENDERS a form — without
+     * compute defaults the form shows the wrong initial values.
+     */
+    skipComputeDefaults?: boolean;
+}
+export type DefinitionLoader = (ctx: RequestContext, record: DefinitionRecord, channel: DefinitionChannel, explicitVersionId?: string | null, options?: DefinitionLoadOptions) => Promise<LoadedDefinition>;
 /**
- * Build a definition loader over the injected stores/compute wiring.
- *
- * The returned function loads a definition's version blob + schema (with
- * merged compute defaults). By default it resolves the `channel` pointer
- * (live/draft); pass `explicitVersionId` to render an arbitrary historical
- * version instead — the caller must gate that behind edit permission
- * (editor-only, like the draft channel). Throws `DefinitionLoadError` for
- * classified failures so the caller can translate to HTTP status codes.
+ * The returned loader resolves the `channel` pointer (live/draft) by default.
+ * `explicitVersionId` renders an arbitrary historical version instead — the
+ * caller MUST gate that behind edit permission, as with the draft channel.
  */
 export declare function createDefinitionLoader(deps: DefinitionLoaderDeps): DefinitionLoader;
 //# sourceMappingURL=load-for-render.d.ts.map

package/dist/definitions/load-for-render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-for-render.d.ts","sourceRoot":"","sources":["../../src/definitions/load-for-render.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAqB,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EACX,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAG7D,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,gBAAgB,EAAE,UAAU,CAAC;IAC7B,aAAa,EAAE,mBAAmB,CAAC;IACnC,MAAM,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,gBAAgB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEvF,qBAAa,mBAAoB,SAAQ,KAAK;aAE5B,IAAI,EAAE,uBAAuB;aAE7B,KAAK,CAAC,EAAE,OAAO;gBAFf,IAAI,EAAE,uBAAuB,EAC7C,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,OAAO,YAAA;CAKhC;AAED,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACvC,WAAW,EAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,GAAG,kBAAkB,CAAC,CAAC;IACvE,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;IAC5C,mFAAmF;IACnF,aAAa,EAAE,CACd,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,IAAI,EAAE;QAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAClC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClC,gGAAgG;IAChG,SAAS,EAAE,CACV,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,KAC5B,OAAO,CAAC;QAAE,MAAM,EAAE,iBAAiB,CAAA;KAAE,CAAC,CAAC;IAC5C,qFAAqF;IACrF,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,mBAAmB,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpF;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,GAAG,CAC9B,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,iBAAiB,EAC1B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,KAC7B,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE/B;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,gBAAgB,CAgKnF"}
+{"version":3,"file":"load-for-render.d.ts","sourceRoot":"","sources":["../../src/definitions/load-for-render.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAqB,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EACX,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAG7D,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,gBAAgB,EAAE,UAAU,CAAC;IAC7B,aAAa,EAAE,mBAAmB,CAAC;IACnC,MAAM,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,gBAAgB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEvF,qBAAa,mBAAoB,SAAQ,KAAK;aAE5B,IAAI,EAAE,uBAAuB;aAE7B,KAAK,CAAC,EAAE,OAAO;gBAFf,IAAI,EAAE,uBAAuB,EAC7C,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,OAAO,YAAA;CAKhC;AAED,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACvC,WAAW,EAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,GAAG,kBAAkB,CAAC,CAAC;IACvE,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;IAC5C,gFAAgF;IAChF,aAAa,EAAE,CACd,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,IAAI,EAAE;QAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAClC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClC,2FAA2F;IAC3F,SAAS,EAAE,CACV,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,KAC5B,OAAO,CAAC;QAAE,MAAM,EAAE,iBAAiB,CAAA;KAAE,CAAC,CAAC;IAC5C,qFAAqF;IACrF,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,mBAAmB,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpF;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,wFAAwF;IACxF,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACrC;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,MAAM,gBAAgB,GAAG,CAC9B,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,iBAAiB,EAC1B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,EACjC,OAAO,CAAC,EAAE,qBAAqB,KAC3B,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE/B;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,gBAAgB,CAsKnF"}