@nifrajs/core 3.5.0 → 4.0.2

package/src/durable-adapters.ts

@@ -222,7 +222,8 @@ export class MemoryDurableRecordBackend implements DurableRecordBackend {
         if (!key.startsWith(prefix) || !input.states.includes(value.state ?? "")) return false
         return input.updatedBefore === undefined || (value.updatedAt ?? 0) <= input.updatedBefore
       })
-      .sort(([a], [b]) => a.localeCompare(b))
+      // Code-unit order, the order the cursor comparison below uses (and SQLite's BINARY collation).
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
       .filter(([key]) => input.cursor === undefined || key > prefix + input.cursor)
     const page = records.slice(0, input.limit)
     return Object.freeze({
@@ -382,6 +383,14 @@ export async function runDurableExecutionAdapterConformance(
     version: 1,
   }
   requireConformance(await adapter.sagas.create(saga), "saga create rejected")
+  requireConformance(
+    !(await adapter.sagas.compareAndSet({
+      sagaId,
+      version: 1,
+      record: { ...saga, sagaId: `${sagaId}-other`, state: "completed", updatedAt: 2, version: 2 },
+    })),
+    "saga CAS accepted a record for another saga",
+  )
   requireConformance(
     await adapter.sagas.compareAndSet({
       sagaId,
@@ -914,11 +923,19 @@ export class DurableObjectRecordBackend implements DurableRecordBackend {
       }
       if (selected.length > input.limit) break
     }
-    const hasMore = selected.length > input.limit || listed.size > input.limit
     const page = selected.slice(0, input.limit)
+    // A full page resumes after its own last record: the matching record that overflowed it was
+    // visited but not returned, so the cursor must not pass it. Otherwise every listed key was
+    // returned or filtered out, and the next page starts after the last one visited.
+    const cursor =
+      selected.length > input.limit
+        ? page.at(-1)?.id
+        : listed.size > input.limit
+          ? lastVisited
+          : undefined
     return Object.freeze({
       records: Object.freeze(page.map(({ record }) => clone(record))),
-      ...(hasMore && lastVisited !== undefined ? { cursor: lastVisited } : {}),
+      ...(cursor === undefined ? {} : { cursor }),
     })
   }
   async acquireLease(

package/src/durable-effect.ts

@@ -57,6 +57,7 @@ export function createDurableEffectJournal(
     if (record === undefined) throw new DurableEffectTransitionError(effectId, "missing")
     if (
       record.effectId !== effectId ||
+      typeof record.capability !== "string" ||
       !validCapabilityId(record.capability) ||
       !["admission", "executing", "committed", "failed", "unknown"].includes(record.state) ||
       !Number.isSafeInteger(record.version) ||
@@ -69,7 +70,10 @@ export function createDurableEffectJournal(
     if (record.createdAt > record.updatedAt)
       throw new TypeError(`durable effect ${effectId}: updatedAt precedes createdAt`)
     if (record.target !== undefined) assertToken(record.target, "stored durable effect target", 128)
-    if (record.digest !== undefined && !/^[0-9a-f]{64}$/u.test(record.digest))
+    if (
+      record.digest !== undefined &&
+      (typeof record.digest !== "string" || !/^[0-9a-f]{64}$/u.test(record.digest))
+    )
       throw new TypeError(`durable effect ${effectId}: store returned an invalid digest`)
     if (record.tenantId !== undefined)
       assertToken(record.tenantId, "stored durable effect tenantId")
@@ -77,7 +81,10 @@ export function createDurableEffectJournal(
       assertToken(record.principalId, "stored durable effect principalId")
     if ((record.tenantId === undefined) !== (record.principalId === undefined))
       throw new TypeError(`durable effect ${effectId}: store returned a partial identity`)
-    if (record.errorCode !== undefined && !ERROR_CODE.test(record.errorCode))
+    if (
+      record.errorCode !== undefined &&
+      (typeof record.errorCode !== "string" || !ERROR_CODE.test(record.errorCode))
+    )
       throw new TypeError(`durable effect ${effectId}: store returned an invalid error code`)
     return record
   }
@@ -145,7 +152,7 @@ export function createDurableEffectJournal(
       await transition(effectId, "executing", "committed")
     },
     async failed(effectId, input) {
-      if (!ERROR_CODE.test(input.errorCode))
+      if (typeof input.errorCode !== "string" || !ERROR_CODE.test(input.errorCode))
         throw new TypeError("durable effect errorCode is invalid")
       const record = await current(effectId)
       const to = input.began ? "unknown" : "failed"

package/src/edge-kit.ts

@@ -11,6 +11,7 @@
  *   - {@link toResponse}       render a {@link ResponseResult} (e.g. a 413 / 415 rejection) to a `Response`
  *   - {@link plainError}       the structured rejection envelope the lane returns
  *   - {@link queryObjectOf} / {@link searchOf}   query parse without a full WHATWG URL construction
+ *   - {@link answerNotFound}   run a not-found handler under the same rules (404 only, no 2xx, fail closed)
  *
  * Everything here carries only structure - bytes, guards, and envelopes - never routing, lifecycle,
  * or app state. It is the interface, not the framework.
@@ -18,6 +19,12 @@
 
 export { readBodyFramed } from "./server/body-lane.ts"
 export { plainError } from "./server/http.ts"
+export {
+  answerNotFound,
+  type NotFoundHandler,
+  type NotFoundInput,
+  notFoundInput,
+} from "./server/not-found-answer.ts"
 export type { ProtoPoisoning } from "./server/proto-guard.ts"
 export { type QueryValue, queryObjectOf, searchOf } from "./server/query.ts"
 export { toResponse } from "./server/respond.ts"

package/src/effect-lifecycle.ts

@@ -93,7 +93,11 @@ export function emitEffectLifecycle(
   if (input.attempt !== undefined && (!Number.isSafeInteger(input.attempt) || input.attempt < 1)) {
     return
   }
-  if (input.errorCode !== undefined && !ERROR_CODE.test(input.errorCode)) return
+  if (
+    input.errorCode !== undefined &&
+    (typeof input.errorCode !== "string" || !ERROR_CODE.test(input.errorCode))
+  )
+    return
   const event: EffectLifecycleEvent = Object.freeze({
     effectId: input.effectId,
     capability: input.capability,

package/src/effect-scope.ts

@@ -108,7 +108,8 @@ function codeFor(
     typeof configured === "function"
       ? configured(error, began)
       : (configured ?? (began ? "execution_failed" : "admission_failed"))
-  if (!ERROR_CODE.test(code)) throw new TypeError("effect errorCode is invalid")
+  if (typeof code !== "string" || !ERROR_CODE.test(code))
+    throw new TypeError("effect errorCode is invalid")
   return code
 }
 

package/src/errors.ts

@@ -27,7 +27,10 @@ export type RouteConfigErrorCode =
   | "INVALID_ASSURANCE"
   | "INVALID_IDEMPOTENCY"
   | "INVALID_WS_SEND_VALIDATION"
+  | "INVALID_WIRE"
+  | "INVALID_VALIDATION_ORDER"
   | "INVALID_BODY_LIMIT"
+  | "PLUGIN_RECONFIGURED"
 
 /**
  * Thrown at route registration when a route is misconfigured. This is the

package/src/evidence.ts

@@ -14,11 +14,14 @@ import type {
   CapabilityFinding,
 } from "./capabilities.ts"
 import type { ResponseClassification } from "./classification.ts"
+import { codeUnitOrder } from "./internal/code-unit-order.ts"
 import { evidenceProvenance } from "./internal/route-assurance.ts"
 import {
   type JsonSchema,
+  type ReflectedMount,
   type ReflectedRoute,
   type ReflectedSchemaField,
+  reflectMounts,
   reflectRoutes,
   type SchemaReflection,
 } from "./reflection.ts"
@@ -26,12 +29,15 @@ import {
 export interface ProjectEvidenceSchemaPart {
   readonly jsonSchema?: JsonSchema
   readonly fields?: readonly ReflectedSchemaField[]
+  /** The media types a body schema reads through a parser of its own. */
+  readonly mediaTypes?: readonly string[]
 }
 
 export interface ProjectEvidenceSchema {
   readonly bodyLimit?: number | "unlimited"
   readonly bodyLimitReason?: string
   readonly headers?: ProjectEvidenceSchemaPart
+  readonly cookies?: ProjectEvidenceSchemaPart
   readonly body?: ProjectEvidenceSchemaPart
   readonly query?: ProjectEvidenceSchemaPart
   readonly params?: ProjectEvidenceSchemaPart
@@ -50,6 +56,7 @@ export interface ProjectEvidenceRoute {
   readonly method: string
   readonly path: string
   readonly schema?: ProjectEvidenceSchema
+  readonly responseContract?: "warn" | "enforce"
   readonly assurance?: readonly AssuranceEvidence[]
   readonly capabilities?: readonly string[]
   readonly family?: boolean
@@ -93,6 +100,8 @@ export interface ProjectEvidenceCapabilities {
 export interface ProjectEvidenceSnapshot {
   readonly version: 1
   readonly routes: readonly ProjectEvidenceRoute[]
+  /** Mounted children whose routes are not in `routes`, present when there is at least one. */
+  readonly mounts?: readonly ReflectedMount[]
   readonly assurance?: ProjectEvidenceAssurance
   readonly capabilities?: ProjectEvidenceCapabilities
 }
@@ -108,6 +117,15 @@ export interface ProjectEvidenceOptions {
   readonly routes?: readonly ReflectedRoute[]
   /** Optional static source locations keyed by `${METHOD}\n${path}`. */
   readonly sourceLocations?: ReadonlyMap<string, readonly ProjectEvidenceSourceLocation[]>
+  /** An existing mount reflection, like `routes`. Default: `reflectMounts(source)`. */
+  readonly mounts?: readonly ReflectedMount[]
+}
+
+/** One token-only evidence snapshot in a composed application surface. */
+export interface ProjectEvidenceCompositionPart {
+  readonly evidence: ProjectEvidenceSnapshot
+  /** Public pathname prefix to add when the child receives a stripped mount request. */
+  readonly pathPrefix?: string
 }
 
 const recordOf = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
@@ -120,6 +138,9 @@ function schemaPart(value: SchemaReflection | undefined): ProjectEvidenceSchemaP
   return Object.freeze({
     ...(value.jsonSchema !== undefined ? { jsonSchema: value.jsonSchema } : {}),
     ...(value.fields !== undefined ? { fields: Object.freeze([...value.fields]) } : {}),
+    ...(value.mediaTypes !== undefined
+      ? { mediaTypes: Object.freeze([...value.mediaTypes].sort()) }
+      : {}),
   })
 }
 
@@ -127,6 +148,7 @@ function schemaOf(route: ReflectedRoute): ProjectEvidenceSchema | undefined {
   const source = route.schema
   if (source === undefined) return undefined
   const headers = schemaPart(source.headers)
+  const cookies = schemaPart(source.cookies)
   const body = schemaPart(source.body)
   const query = schemaPart(source.query)
   const params = schemaPart(source.params)
@@ -141,6 +163,7 @@ function schemaOf(route: ReflectedRoute): ProjectEvidenceSchema | undefined {
     ...(source.bodyLimit !== undefined ? { bodyLimit: source.bodyLimit } : {}),
     ...(source.bodyLimitReason !== undefined ? { bodyLimitReason: source.bodyLimitReason } : {}),
     ...(headers !== undefined ? { headers } : {}),
+    ...(cookies !== undefined ? { cookies } : {}),
     ...(body !== undefined ? { body } : {}),
     ...(query !== undefined ? { query } : {}),
     ...(params !== undefined ? { params } : {}),
@@ -163,7 +186,7 @@ function assuranceEvidenceOf(values: readonly AssuranceEvidence[]): readonly Ass
           provenance: evidenceProvenance(item),
         }),
       )
-      .sort((a, b) => a.id.localeCompare(b.id) || a.source.localeCompare(b.source)),
+      .sort((a, b) => codeUnitOrder(a.id, b.id) || codeUnitOrder(a.source, b.source)),
   )
 }
 
@@ -175,9 +198,9 @@ function capabilityEvidenceOf(
       .map((item) => Object.freeze({ id: item.id, kind: item.kind, source: item.source }))
       .sort(
         (a, b) =>
-          a.id.localeCompare(b.id) ||
-          a.kind.localeCompare(b.kind) ||
-          a.source.localeCompare(b.source),
+          codeUnitOrder(a.id, b.id) ||
+          codeUnitOrder(a.kind, b.kind) ||
+          codeUnitOrder(a.source, b.source),
       ),
   )
 }
@@ -186,7 +209,7 @@ const sortByRoute = <T extends { readonly method: string; readonly path: string
   values: readonly T[],
 ): readonly T[] =>
   Object.freeze(
-    [...values].sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method)),
+    [...values].sort((a, b) => codeUnitOrder(a.path, b.path) || codeUnitOrder(a.method, b.method)),
   )
 
 function evidenceRouteOf(
@@ -198,6 +221,7 @@ function evidenceRouteOf(
     method: route.method.toUpperCase(),
     path: route.path,
     ...(schema !== undefined ? { schema } : {}),
+    ...(route.responseContract === undefined ? {} : { responseContract: route.responseContract }),
     ...(route.assurance !== undefined ? { assurance: assuranceEvidenceOf(route.assurance) } : {}),
     ...(route.capabilities !== undefined
       ? { capabilities: Object.freeze([...route.capabilities].sort()) }
@@ -230,9 +254,9 @@ function assuranceOf(report: AssuranceReport | undefined): ProjectEvidenceAssura
     findings: Object.freeze(
       [...report.findings].sort(
         (a, b) =>
-          a.path.localeCompare(b.path) ||
-          a.method.localeCompare(b.method) ||
-          a.code.localeCompare(b.code),
+          codeUnitOrder(a.path, b.path) ||
+          codeUnitOrder(a.method, b.method) ||
+          codeUnitOrder(a.code, b.code),
       ),
     ),
   })
@@ -260,20 +284,203 @@ function capabilitiesOf(
     findings: Object.freeze(
       [...report.findings].sort(
         (a, b) =>
-          a.path.localeCompare(b.path) ||
-          a.method.localeCompare(b.method) ||
-          a.code.localeCompare(b.code),
+          codeUnitOrder(a.path, b.path) ||
+          codeUnitOrder(a.method, b.method) ||
+          codeUnitOrder(a.code, b.code),
       ),
     ),
   })
 }
 
+function trimTrailingSlashes(path: string): string {
+  // Index-scan instead of `/\/+$/`: path prefixes can be library input, and the
+  // unanchored-start trailing-run replacement can backtrack quadratically.
+  let end = path.length
+  while (end > 0 && path.charCodeAt(end - 1) === 47 /* '/' */) end--
+  return path.slice(0, end)
+}
+
+const composedPath = (prefix: string, path: string): string => {
+  if (path === "*") return path
+  if (!path.startsWith("/"))
+    throw new TypeError(`project evidence: route path must start with "/": ${path}`)
+  if (prefix === "") return path
+  if (!prefix.startsWith("/")) {
+    throw new TypeError(`project evidence: path prefix must start with "/": ${prefix}`)
+  }
+  const normalized = prefix === "/" ? "" : trimTrailingSlashes(prefix)
+  return normalized === "" ? path : path === "/" ? normalized : `${normalized}${path}`
+}
+
+function remapEvidenceSnapshot(
+  evidence: ProjectEvidenceSnapshot,
+  pathPrefix: string,
+): ProjectEvidenceSnapshot {
+  if (evidence.version !== 1) throw new Error("project evidence: unsupported snapshot version")
+  const route = (
+    method: string,
+    path: string,
+  ): { readonly method: string; readonly path: string } => ({
+    method: method.toUpperCase(),
+    path: composedPath(pathPrefix, path),
+  })
+  const routes = evidence.routes.map((item) => {
+    const key = route(item.method, item.path)
+    return Object.freeze({ ...item, ...key })
+  })
+  const mounts = evidence.mounts?.map((item) =>
+    Object.freeze({ ...item, path: composedPath(pathPrefix, item.path) }),
+  )
+  const assurance =
+    evidence.assurance === undefined
+      ? undefined
+      : Object.freeze({
+          ok: evidence.assurance.ok,
+          routes: Object.freeze(
+            evidence.assurance.routes.map((item) =>
+              Object.freeze({ ...item, ...route(item.method, item.path) }),
+            ),
+          ),
+          findings: Object.freeze(
+            evidence.assurance.findings.map((item) =>
+              Object.freeze({ ...item, ...route(item.method, item.path) }),
+            ),
+          ),
+        })
+  const capabilities =
+    evidence.capabilities === undefined
+      ? undefined
+      : Object.freeze({
+          ok: evidence.capabilities.ok,
+          routes: Object.freeze(
+            evidence.capabilities.routes.map((item) =>
+              Object.freeze({ ...item, ...route(item.method, item.path) }),
+            ),
+          ),
+          findings: Object.freeze(
+            evidence.capabilities.findings.map((item) =>
+              Object.freeze({ ...item, ...route(item.method, item.path) }),
+            ),
+          ),
+        })
+  return Object.freeze({
+    version: 1,
+    routes: Object.freeze(routes),
+    ...(mounts === undefined ? {} : { mounts: Object.freeze(mounts) }),
+    ...(assurance === undefined ? {} : { assurance }),
+    ...(capabilities === undefined ? {} : { capabilities }),
+  })
+}
+
+function routeKeyForEvidence(method: string, path: string): string {
+  return `${method.toUpperCase()}\n${path}`
+}
+
+function validateComposedReportRoutes(
+  report: ProjectEvidenceAssurance | ProjectEvidenceCapabilities,
+  routeKeys: ReadonlySet<string>,
+  kind: "assurance" | "capabilities",
+): void {
+  for (const route of report.routes) {
+    if (!routeKeys.has(routeKeyForEvidence(route.method, route.path))) {
+      throw new Error(
+        `project evidence: ${kind} route ${route.method} ${route.path} is not present in the composed route set`,
+      )
+    }
+  }
+}
+
+/**
+ * Compose page and mounted-app evidence into one deterministic snapshot.
+ *
+ * This is an offline operation. It carries route contracts, assurance/capability tokens, and source
+ * locations only; it never invokes handlers or copies request/business data. A duplicate public
+ * method+path or a report that no longer describes a composed route is rejected rather than silently
+ * dropping one side of the trust boundary.
+ */
+export function composeProjectEvidence(
+  parts: readonly ProjectEvidenceCompositionPart[],
+): ProjectEvidenceSnapshot {
+  const routes: ProjectEvidenceRoute[] = []
+  const routeKeys = new Set<string>()
+  const mounts: ReflectedMount[] = []
+  const assuranceReports: ProjectEvidenceAssurance[] = []
+  const capabilityReports: ProjectEvidenceCapabilities[] = []
+
+  for (const part of parts) {
+    const prefix = part.pathPrefix ?? ""
+    const mapped = remapEvidenceSnapshot(part.evidence, prefix)
+    for (const route of mapped.routes) {
+      const key = routeKeyForEvidence(route.method, route.path)
+      if (routeKeys.has(key)) {
+        throw new Error(`project evidence: duplicate composed route ${route.method} ${route.path}`)
+      }
+      routeKeys.add(key)
+      routes.push(route)
+    }
+    mounts.push(...(mapped.mounts ?? []))
+    if (mapped.assurance !== undefined) assuranceReports.push(mapped.assurance)
+    if (mapped.capabilities !== undefined) capabilityReports.push(mapped.capabilities)
+  }
+
+  const assurance =
+    assuranceReports.length === 0
+      ? undefined
+      : Object.freeze({
+          ok: assuranceReports.every((report) => report.ok),
+          routes: sortByRoute(assuranceReports.flatMap((report) => report.routes)),
+          findings: Object.freeze(
+            assuranceReports
+              .flatMap((report) => report.findings)
+              .sort(
+                (a, b) =>
+                  codeUnitOrder(a.path, b.path) ||
+                  codeUnitOrder(a.method, b.method) ||
+                  codeUnitOrder(a.code, b.code),
+              ),
+          ),
+        })
+  const capabilities =
+    capabilityReports.length === 0
+      ? undefined
+      : Object.freeze({
+          ok: capabilityReports.every((report) => report.ok),
+          routes: sortByRoute(capabilityReports.flatMap((report) => report.routes)),
+          findings: Object.freeze(
+            capabilityReports
+              .flatMap((report) => report.findings)
+              .sort(
+                (a, b) =>
+                  codeUnitOrder(a.path, b.path) ||
+                  codeUnitOrder(a.method, b.method) ||
+                  codeUnitOrder(a.code, b.code),
+              ),
+          ),
+        })
+  if (assurance !== undefined) validateComposedReportRoutes(assurance, routeKeys, "assurance")
+  if (capabilities !== undefined)
+    validateComposedReportRoutes(capabilities, routeKeys, "capabilities")
+
+  return Object.freeze({
+    version: 1,
+    routes: sortByRoute(routes),
+    ...mountsPart(mounts),
+    ...(assurance === undefined ? {} : { assurance }),
+    ...(capabilities === undefined ? {} : { capabilities }),
+  })
+}
+
 function schemaPartToReflection(
   value: ProjectEvidenceSchemaPart | undefined,
 ): SchemaReflection | undefined {
   return value === undefined
     ? undefined
-    : { standard: undefined, jsonSchema: value.jsonSchema, fields: value.fields }
+    : {
+        standard: undefined,
+        jsonSchema: value.jsonSchema,
+        fields: value.fields,
+        ...(value.mediaTypes !== undefined ? { mediaTypes: value.mediaTypes } : {}),
+      }
 }
 
 function schemaFromEvidence(schema: ProjectEvidenceSchema | undefined): ReflectedRoute["schema"] {
@@ -285,6 +492,7 @@ function schemaFromEvidence(schema: ProjectEvidenceSchema | undefined): Reflecte
     ]),
   )
   const headers = schemaPartToReflection(schema.headers)
+  const cookies = schemaPartToReflection(schema.cookies)
   const body = schemaPartToReflection(schema.body)
   const query = schemaPartToReflection(schema.query)
   const params = schemaPartToReflection(schema.params)
@@ -294,6 +502,7 @@ function schemaFromEvidence(schema: ProjectEvidenceSchema | undefined): Reflecte
     ...(schema.bodyLimit !== undefined ? { bodyLimit: schema.bodyLimit } : {}),
     ...(schema.bodyLimitReason !== undefined ? { bodyLimitReason: schema.bodyLimitReason } : {}),
     ...(headers !== undefined ? { headers } : {}),
+    ...(cookies !== undefined ? { cookies } : {}),
     ...(body !== undefined ? { body } : {}),
     ...(query !== undefined ? { query } : {}),
     ...(params !== undefined ? { params } : {}),
@@ -311,12 +520,14 @@ function schemaFromEvidence(schema: ProjectEvidenceSchema | undefined): Reflecte
 export function reflectedRoutesFromEvidence(
   evidence: ProjectEvidenceSnapshot,
 ): readonly ReflectedRoute[] {
+  if (evidence.version !== 1) throw new Error("project evidence: unsupported snapshot version")
   return evidence.routes.map((route) => {
     const schema = schemaFromEvidence(route.schema)
     return {
       method: route.method,
       path: route.path,
       ...(schema !== undefined ? { schema } : {}),
+      ...(route.responseContract === undefined ? {} : { responseContract: route.responseContract }),
       ...(route.assurance !== undefined ? { assurance: route.assurance } : {}),
       ...(route.capabilities !== undefined ? { capabilities: route.capabilities } : {}),
       ...(route.family === true ? { family: true } : {}),
@@ -345,11 +556,25 @@ export function snapshotProjectEvidence(
   return Object.freeze({
     version: 1,
     routes,
+    ...mountsPart(options.mounts ?? reflectMounts(source)),
     ...(assurance !== undefined ? { assurance } : {}),
     ...(capabilities !== undefined ? { capabilities } : {}),
   })
 }
 
+/** The snapshot's `mounts` field, sorted, and absent when empty so a mount-free app's snapshot (and its
+ * manifest hash) is unchanged. */
+const mountsPart = (
+  mounts: readonly ReflectedMount[],
+): { readonly mounts?: readonly ReflectedMount[] } =>
+  mounts.length === 0
+    ? {}
+    : {
+        mounts: Object.freeze(
+          [...mounts].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+        ),
+      }
+
 function canonicalValue(value: unknown): string {
   if (value === null || typeof value === "string" || typeof value === "boolean") {
     return JSON.stringify(value)