@nifrajs/core 3.3.0 → 4.0.0

package/src/diff.ts

@@ -18,6 +18,7 @@
  * yield `info` - never a silent pass presented as proof.
  */
 
+import { type ProjectEvidenceSnapshot, reflectedRoutesFromEvidence } from "./evidence.ts"
 import {
   type JsonSchema,
   type ReflectedRoute,
@@ -33,8 +34,10 @@ export interface SchemaSnapshot {
 
 export interface RouteSnapshotSchema {
   readonly headers?: SchemaSnapshot
+  readonly cookies?: SchemaSnapshot
   readonly body?: SchemaSnapshot
   readonly query?: SchemaSnapshot
+  readonly params?: SchemaSnapshot
   readonly response?: SchemaSnapshot
   readonly sse?: SchemaSnapshot
   readonly errors?: Readonly<Record<string, SchemaSnapshot>>
@@ -54,7 +57,16 @@ export interface RouteChange {
   readonly method: string
   readonly path: string
   /** Which part of the contract changed; "route" for add/remove of the whole route. */
-  readonly section: "route" | "headers" | "body" | "query" | "response" | "sse" | "errors"
+  readonly section:
+    | "route"
+    | "headers"
+    | "cookies"
+    | "body"
+    | "query"
+    | "params"
+    | "response"
+    | "sse"
+    | "errors"
   /** The top-level field (or error status) the change is about, when field-granular. */
   readonly field?: string
   readonly message: string
@@ -87,9 +99,19 @@ const schemaSnapshot = (
  * `JSON.stringify` unchanged.
  */
 export function snapshotRoutes(source: unknown): readonly RouteSnapshot[] {
+  // Preserve the historical registration order of this low-level helper. The canonical evidence
+  // seam intentionally sorts routes for persistence, while callers using snapshotRoutes directly
+  // may use the order to compare a live reflection with an older baseline.
   return reflectRoutes(source).map((route) => snapshotRoute(route))
 }
 
+/** Snapshot routes from an existing canonical project-evidence pass. */
+export function snapshotRoutesFromEvidence(
+  evidence: ProjectEvidenceSnapshot,
+): readonly RouteSnapshot[] {
+  return reflectedRoutesFromEvidence(evidence).map((route) => snapshotRoute(route))
+}
+
 const snapshotRoute = (route: ReflectedRoute): RouteSnapshot => {
   const schema = route.schema
   if (schema === undefined) return { method: route.method, path: route.path }
@@ -100,13 +122,17 @@ const snapshotRoute = (route: ReflectedRoute): RouteSnapshot => {
   }
   const body = schemaSnapshot(schema.body)
   const headers = schemaSnapshot(schema.headers)
+  const cookies = schemaSnapshot(schema.cookies)
   const query = schemaSnapshot(schema.query)
+  const params = schemaSnapshot(schema.params)
   const response = schemaSnapshot(schema.response)
   const sse = schemaSnapshot(schema.sse)
   const snapped: RouteSnapshotSchema = {
     ...(headers !== undefined ? { headers } : {}),
+    ...(cookies !== undefined ? { cookies } : {}),
     ...(body !== undefined ? { body } : {}),
     ...(query !== undefined ? { query } : {}),
+    ...(params !== undefined ? { params } : {}),
     ...(response !== undefined ? { response } : {}),
     ...(sse !== undefined ? { sse } : {}),
     ...(Object.keys(errors).length > 0 ? { errors } : {}),
@@ -197,19 +223,40 @@ const fieldMap = (
   return new Map(snapshot.fields.map((field) => [field.name, field]))
 }
 
+/**
+ * An object schema without the parts the field diff already covers: its `properties`, and the
+ * `required` names of declared fields. What is left (`additionalProperties`, the `$defs` a field's
+ * `$ref` points into, a required name no field declares) changes the contract as surely as a field.
+ */
+const envelopeOf = (schema: JsonSchema): JsonSchema => {
+  if (typeof schema !== "object") return schema
+  const { properties, required, ...rest } = schema
+  const declared = typeof properties === "object" && properties !== null ? properties : {}
+  const undeclared = Array.isArray(required)
+    ? required.filter((name) => typeof name !== "string" || !Object.hasOwn(declared, name))
+    : required
+  return undeclared === undefined || (Array.isArray(undeclared) && undeclared.length === 0)
+    ? rest
+    : { ...rest, required: undeclared }
+}
+
 const diffFields = (ctx: SectionContext, before: SchemaSnapshot, after: SchemaSnapshot): void => {
+  const beforeSchema = before.jsonSchema as JsonSchema
+  const afterSchema = after.jsonSchema as JsonSchema
   const beforeFields = fieldMap(before)
   const afterFields = fieldMap(after)
   if (beforeFields === undefined || afterFields === undefined) {
     // Non-object schemas: compare the whole JSON Schema in one step.
-    const severity = compareJsonSchema(
-      ctx.direction,
-      before.jsonSchema as JsonSchema,
-      after.jsonSchema as JsonSchema,
-    )
+    const severity = compareJsonSchema(ctx.direction, beforeSchema, afterSchema)
     if (severity !== undefined) push(ctx, severity, `${ctx.section} schema changed`)
     return
   }
+  const envelope = compareJsonSchema(
+    ctx.direction,
+    envelopeOf(beforeSchema),
+    envelopeOf(afterSchema),
+  )
+  if (envelope !== undefined) push(ctx, envelope, `${ctx.section} schema changed`)
   for (const [name, beforeField] of beforeFields) {
     const afterField = afterFields.get(name)
     if (afterField === undefined) {
@@ -356,7 +403,7 @@ export function diffRouteSnapshots(
     const path = beforeRoute.path
     const beforeSchema = beforeRoute.schema ?? {}
     const afterSchema = afterRoute.schema ?? {}
-    for (const section of ["headers", "body", "query"] as const) {
+    for (const section of ["headers", "cookies", "body", "query", "params"] as const) {
       diffSchemaSection(
         { method, path, section, direction: "request", changes },
         beforeSchema[section],

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