@jskit-ai/json-rest-api-core 0.1.129 → 0.1.131

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@jskit-ai/json-rest-api-core",
-  "version": "0.1.129",
+  "version": "0.1.131",
   "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
   "scripts": {
     "test": "node --test"
   },
@@ -9,10 +12,9 @@
     "./server/jsonRestApiHost": "./src/server/jsonRestApiHost.js"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.1.185",
-    "@jskit-ai/resource-crud-core": "0.1.127",
-    "hooked-api": "1.x.x",
-    "json-rest-api": "^1.0.29"
+    "@jskit-ai/database-runtime": "0.1.187",
+    "@jskit-ai/resource-crud-core": "0.1.129",
+    "json-rest-api": "2.0.0"
   },
   "description": "Shared internal json-rest-api host runtime with autofilter, query-projection, and row-policy support.",
   "jskit": {
@@ -50,6 +52,6 @@
     }
   },
   "peerDependencies": {
-    "@jskit-ai/kernel": "0.1.185"
+    "@jskit-ai/kernel": "0.1.187"
   }
 }

package/src/server/jsonRestApiHost.js

@@ -1,6 +1,6 @@
-import { Api } from "hooked-api";
 import {
   AutoFilterPlugin,
+  JsonRestApi,
   QueryProjectionsPlugin,
   REST_API_FIELDSET_ERROR_CODE,
   RestApiKnexPlugin,
@@ -51,9 +51,9 @@ const JSON_REST_RESERVED_QUERY_KEYS = Object.freeze(new Set([
   "sort",
   "fields"
 ]));
-const JSON_REST_CALENDAR_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/u;
-const JSON_REST_DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/u;
-const JSON_REST_DATABASE_UTC_DATE_TIME_PATTERN = /^(\d{4}-\d{2}-\d{2}) ((?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?)$/u;
+const JSON_REST_DEFAULT_LOGGER = Object.freeze({
+  error: (...args) => console.error(...args)
+});
 
 function isPlainJsonRestObject(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -106,132 +106,6 @@ function cloneJsonRestResourceValue(value, { writeSerializers = {} } = {}) {
   return next;
 }
 
-function resolveCanonicalCalendarDate(value) {
-  if (value instanceof Date) {
-    return Number.isNaN(value.getTime())
-      ? ""
-      : value.toISOString().slice(0, 10);
-  }
-
-  const normalized = typeof value === "string" ? value.trim() : "";
-  const candidate = normalized.match(/^(\d{4}-\d{2}-\d{2})(?:$|T)/u)?.[1] || "";
-  if (!JSON_REST_CALENDAR_DATE_PATTERN.test(candidate)) {
-    return "";
-  }
-
-  const parsed = new Date(`${candidate}T00:00:00.000Z`);
-  if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== candidate) {
-    return "";
-  }
-
-  return candidate;
-}
-
-function serializeJsonRestCalendarDate(value) {
-  if (value == null) {
-    return value;
-  }
-
-  const canonical = resolveCanonicalCalendarDate(value);
-  if (!canonical) {
-    throw new TypeError("json-rest-api calendar date must be a valid YYYY-MM-DD value.");
-  }
-  return canonical;
-}
-
-function resolveCanonicalDateTime(value) {
-  if (value instanceof Date) {
-    return Number.isNaN(value.getTime()) ? "" : value.toISOString();
-  }
-
-  const normalized = typeof value === "string" ? value.trim() : "";
-  if (JSON_REST_DATE_TIME_PATTERN.test(normalized)) {
-    return normalized;
-  }
-
-  const databaseMatch = JSON_REST_DATABASE_UTC_DATE_TIME_PATTERN.exec(normalized);
-  return databaseMatch ? `${databaseMatch[1]}T${databaseMatch[2]}Z` : "";
-}
-
-function applyJsonRestCalendarDateWriteSerializers(scopeOptions = {}) {
-  const schema = normalizeJsonRestObject(scopeOptions.schema);
-  for (const fieldDefinition of Object.values(schema)) {
-    if (normalizeJsonRestText(fieldDefinition?.type).toLowerCase() !== "date") {
-      continue;
-    }
-    if (fieldDefinition?.virtual === true || fieldDefinition?.storage?.virtual === true) {
-      continue;
-    }
-
-    const storage = normalizeJsonRestObject(fieldDefinition.storage);
-    if (typeof storage.serialize === "function") {
-      continue;
-    }
-    fieldDefinition.storage = {
-      ...storage,
-      serialize: serializeJsonRestCalendarDate
-    };
-  }
-}
-
-function normalizeJsonRestTemporalEntry(entry = null, scopes = {}) {
-  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-    return entry;
-  }
-
-  const schema = normalizeJsonRestObject(
-    scopes?.[normalizeJsonRestText(entry.type)]?.vars?.schemaInfo?.schemaStructure
-  );
-  const attributes = normalizeJsonRestObject(entry.attributes);
-  for (const [fieldName, definition] of Object.entries(schema)) {
-    if (!Object.hasOwn(attributes, fieldName) || attributes[fieldName] == null) {
-      continue;
-    }
-
-    const fieldType = normalizeJsonRestText(definition?.type).toLowerCase();
-    const canonical = fieldType === "date"
-      ? resolveCanonicalCalendarDate(attributes[fieldName])
-      : fieldType === "datetime"
-        ? resolveCanonicalDateTime(attributes[fieldName])
-        : "";
-    if (canonical) {
-      attributes[fieldName] = canonical;
-    }
-  }
-
-  return entry;
-}
-
-function normalizeJsonRestTemporalDocument(document = null, scopes = {}) {
-  if (!document || typeof document !== "object" || Array.isArray(document)) {
-    return document;
-  }
-
-  const data = Array.isArray(document.data) ? document.data : [document.data];
-  for (const entry of data) {
-    normalizeJsonRestTemporalEntry(entry, scopes);
-  }
-  for (const entry of Array.isArray(document.included) ? document.included : []) {
-    normalizeJsonRestTemporalEntry(entry, scopes);
-  }
-  return document;
-}
-
-const JsonRestTemporalPlugin = Object.freeze({
-  name: "jskit-temporal",
-  dependencies: ["rest-api"],
-  install({ addHook, scopes }) {
-    addHook("finish", "normalizeCalendarDateDocuments", {}, ({ context }) => {
-      if (context?.record) {
-        normalizeJsonRestTemporalDocument(context.record, scopes);
-      }
-      if (context?.responseRecord) {
-        normalizeJsonRestTemporalDocument(context.responseRecord, scopes);
-      }
-    });
-  }
-});
-
 async function addResourceIfMissing(api, scopeName, resourceConfig) {
   if (api?.resources?.[scopeName]) {
     return api.resources[scopeName];
@@ -572,94 +446,11 @@ function buildJsonRestQueryParams(resourceType = "", query = {}, { include = und
   return queryParams;
 }
 
-function extractJsonRestCollectionRows(payload = null) {
-  if (Array.isArray(payload)) {
-    return payload;
+function extractJsonRestCollectionRows(payload) {
+  if (!isPlainJsonRestObject(payload) || !Array.isArray(payload.data)) {
+    throw new TypeError("json-rest-api collection response must contain a data array.");
   }
-
-  const source = normalizeJsonRestObject(payload);
-  return Array.isArray(source.data) ? source.data : [];
-}
-
-function extractJsonApiInputRelationships(attributes = {}, resource = null, relationships = null) {
-  const normalizedAttributes = {
-    ...normalizeJsonRestObject(attributes)
-  };
-  const normalizedRelationships = {
-    ...normalizeJsonRestObject(relationships)
-  };
-  const resourceSchema = normalizeJsonRestObject(resource?.schema);
-
-  for (const [fieldName, fieldDefinition] of Object.entries(resourceSchema)) {
-    if (!Object.hasOwn(normalizedAttributes, fieldName)) {
-      continue;
-    }
-
-    const normalizedFieldDefinition = normalizeJsonRestObject(fieldDefinition);
-    const relationshipType = normalizeJsonRestText(normalizedFieldDefinition.belongsTo);
-    if (!relationshipType) {
-      continue;
-    }
-
-    const relationshipName = normalizeJsonRestText(normalizedFieldDefinition.as, {
-      fallback: fieldName
-    });
-    if (!relationshipName) {
-      continue;
-    }
-
-    const relationshipValue = normalizedAttributes[fieldName];
-    delete normalizedAttributes[fieldName];
-
-    if (relationshipValue === undefined) {
-      continue;
-    }
-
-    if (!Object.hasOwn(normalizedRelationships, relationshipName)) {
-      normalizedRelationships[relationshipName] = createJsonApiRelationship(
-        relationshipType,
-        relationshipValue
-      );
-    }
-  }
-
-  return {
-    attributes: normalizedAttributes,
-    relationships: normalizedRelationships
-  };
-}
-
-function createJsonApiInputRecord(
-  resourceType = "",
-  attributes = {},
-  { id = null, relationships = null, resource = null } = {}
-) {
-  const normalizedInput = extractJsonApiInputRelationships(attributes, resource, relationships);
-  return {
-    data: {
-      type: normalizeJsonRestText(resourceType),
-      ...(id == null ? {} : { id: String(id) }),
-      attributes: normalizedInput.attributes,
-      ...(Object.keys(normalizedInput.relationships).length < 1
-        ? {}
-        : { relationships: normalizedInput.relationships })
-    }
-  };
-}
-
-function createJsonApiRelationship(resourceType = "", id = null) {
-  if (id == null) {
-    return {
-      data: null
-    };
-  }
-
-  return {
-    data: {
-      type: normalizeJsonRestText(resourceType),
-      id: String(id)
-    }
-  };
+  return payload.data;
 }
 
 function createJsonRestResourceScopeOptions(
@@ -675,7 +466,6 @@ function createJsonRestResourceScopeOptions(
   const scopeOptions = cloneJsonRestResourceValue(resource, {
     writeSerializers: normalizeJsonRestObject(writeSerializers)
   });
-  applyJsonRestCalendarDateWriteSerializers(scopeOptions);
   if (isPlainJsonRestObject(searchSchema)) {
     scopeOptions.searchSchema = {
       ...normalizeJsonRestObject(scopeOptions.searchSchema),
@@ -767,7 +557,8 @@ async function returnNullWhenJsonRestResourceMissing(run) {
   try {
     return await run();
   } catch (error) {
-    if (isJsonRestResourceMissingError(error)) {
+    if (isJsonRestResourceMissingError(error) &&
+      (!error.transactionOutcome || ["none", "rolledBack"].includes(error.transactionOutcome))) {
       return null;
     }
 
@@ -791,32 +582,30 @@ async function returnBadRequestWhenJsonRestFieldsetInvalid(run) {
       throw error;
     }
 
-    throw new AppError(400, error.message, {
+    const mapped = new AppError(400, error.message, {
       code: "JSON_API_FIELDSET_INVALID"
     });
+    Object.defineProperty(mapped, "cause", { value: error, configurable: true });
+    if (error.transactionOutcome) {
+      mapped.transactionOutcome = error.transactionOutcome;
+    }
+    throw mapped;
   }
 }
 
-async function createJsonRestApiHost({ knex }) {
+async function createJsonRestApiHost({ knex, logger = JSON_REST_DEFAULT_LOGGER }) {
   if (typeof knex !== "function") {
     throw new TypeError("createJsonRestApiHost requires knex.");
   }
 
-  const api = new Api({
+  const api = new JsonRestApi({
     name: "jskit-internal-json-rest-api",
-    logging: {
-      level: "error"
-    }
+    logger
   });
 
   await api.use(RestApiPlugin, {
-    simplifiedApi: true,
-    simplifiedTransport: false,
-    returnRecordApi: {
-      post: "full",
-      put: "full",
-      patch: "full"
-    },
+    format: "plain",
+    returning: "full",
     normalizeId: normalizeRecordId
   });
 
@@ -830,7 +619,6 @@ async function createJsonRestApiHost({ knex }) {
     },
     presets: JSON_REST_AUTOFILTER_PRESETS
   });
-  await api.use(JsonRestTemporalPlugin);
 
   return api;
 }
@@ -839,8 +627,6 @@ export {
   JSON_REST_AUTOFILTER_PRESETS,
   addResourceIfMissing,
   buildJsonRestQueryParams,
-  createJsonApiInputRecord,
-  createJsonApiRelationship,
   createJsonRestResourceScopeOptions,
   createJsonRestContext,
   extractJsonRestCollectionRows,

package/test/entrypoints.boundary.test.js

@@ -2,14 +2,13 @@ import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import test from "node:test";
+import knexLib from "knex";
 import { normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
-import { RestApiFieldsetError } from "json-rest-api";
+import { JsonRestApi, RestApiFieldsetError, RestApiWriteError } from "json-rest-api";
 
 import {
   addResourceIfMissing,
   buildJsonRestQueryParams,
-  createJsonApiInputRecord,
-  createJsonApiRelationship,
   createJsonRestResourceScopeOptions,
   createJsonRestContext,
   createJsonRestApiHost,
@@ -27,19 +26,18 @@ test("package exports include explicit server jsonRestApiHost entrypoint only",
   const exportsMap = packageJson && typeof packageJson === "object" ? packageJson.exports : {};
   assert.equal(exportsMap["./server/jsonRestApiHost"], "./src/server/jsonRestApiHost.js");
   assert.equal(exportsMap["./server"], undefined);
-  assert.equal(packageJson.dependencies?.["json-rest-api"], "^1.0.29");
 });
 
 test("server jsonRestApiHost entrypoint exposes only the focused host API", async () => {
   const hostModule = await import("../src/server/jsonRestApiHost.js");
   assert.equal(Object.hasOwn(hostModule, "simplifyJsonApiDocument"), false);
+  assert.equal(Object.hasOwn(hostModule, "createJsonApiInputRecord"), false);
+  assert.equal(Object.hasOwn(hostModule, "createJsonApiRelationship"), false);
 });
 
 test("server entrypoint exports shared host helpers", () => {
   assert.equal(typeof addResourceIfMissing, "function");
   assert.equal(typeof buildJsonRestQueryParams, "function");
-  assert.equal(typeof createJsonApiInputRecord, "function");
-  assert.equal(typeof createJsonApiRelationship, "function");
   assert.equal(typeof createJsonRestResourceScopeOptions, "function");
   assert.equal(typeof createJsonRestContext, "function");
   assert.equal(typeof createJsonRestApiHost, "function");
@@ -95,7 +93,6 @@ test("createJsonRestContext returns an empty mutable object when source context
 test("extractJsonRestCollectionRows understands the internal collection-document contract", () => {
   const rows = [{ id: "1" }, { id: "2" }];
 
-  assert.deepEqual(extractJsonRestCollectionRows(rows), rows);
   assert.deepEqual(
     extractJsonRestCollectionRows({
       data: rows,
@@ -105,8 +102,10 @@ test("extractJsonRestCollectionRows understands the internal collection-document
     }),
     rows
   );
-  assert.deepEqual(extractJsonRestCollectionRows({ data: null }), []);
-  assert.deepEqual(extractJsonRestCollectionRows(null), []);
+  assert.deepEqual(extractJsonRestCollectionRows({ data: [] }), []);
+  for (const malformed of [rows, { data: null }, {}, null, undefined]) {
+    assert.throws(() => extractJsonRestCollectionRows(malformed), /collection response must contain a data array/);
+  }
 });
 
 test("createJsonRestApiHost installs normalizeRecordId as the default resource id normalizer", async () => {
@@ -136,7 +135,7 @@ test("createJsonRestApiHost installs normalizeRecordId as the default resource i
   assert.equal(api.vars.normalizeId(7.5), null);
 });
 
-test("createJsonRestApiHost configures the internal json-rest logger at error level", async () => {
+test("createJsonRestApiHost uses the v2 runtime, error-only default logging and an injected logger", async (t) => {
   const fakeKnex = Object.assign(() => {}, {
     client: {
       config: {
@@ -153,11 +152,25 @@ test("createJsonRestApiHost configures the internal json-rest logger at error le
     transaction() {}
   });
 
+  const messages = [];
   const api = await createJsonRestApiHost({
-    knex: fakeKnex
+    knex: fakeKnex,
+    logger: { error: (...args) => messages.push(args) }
   });
 
-  assert.equal(api.options.logging.level, "error");
+  assert.ok(api instanceof JsonRestApi);
+  assert.equal(api.vars.format, "plain");
+  assert.equal(api.vars.returning, "full");
+  assert.equal(api.options.logging, undefined);
+  api.log.error("failure", { code: "example" });
+  assert.deepEqual(messages, [["failure", { code: "example" }]]);
+
+  const errorSink = t.mock.method(console, "error", () => {});
+  const defaultApi = await createJsonRestApiHost({ knex: fakeKnex });
+  defaultApi.log.info("quiet");
+  defaultApi.log.error("default failure");
+  assert.equal(errorSink.mock.callCount(), 1);
+  assert.deepEqual(errorSink.mock.calls[0].arguments, ["default failure"]);
 });
 
 test("createJsonRestApiHost installs row policies before resources are added", async () => {
@@ -200,7 +213,7 @@ test("createJsonRestApiHost installs row policies before resources are added", a
   assert.equal(scopeOptions.rowPolicy, rowPolicy);
 });
 
-test("shared query/document helpers build json-rest-api request shapes", () => {
+test("shared query helper builds json-rest-api request shapes", () => {
   assert.deepEqual(
     buildJsonRestQueryParams("contacts", {
       q: "Merc",
@@ -232,70 +245,6 @@ test("shared query/document helpers build json-rest-api request shapes", () => {
     }
   );
 
-  assert.deepEqual(
-    createJsonApiInputRecord("contacts", {
-      name: "Merc"
-    }, {
-      id: 7,
-      relationships: {
-        workspace: createJsonApiRelationship("workspaces", 9)
-      }
-    }),
-    {
-      data: {
-        type: "contacts",
-        id: "7",
-        attributes: {
-          name: "Merc"
-        },
-        relationships: {
-          workspace: {
-            data: {
-              type: "workspaces",
-              id: "9"
-            }
-          }
-        }
-      }
-    }
-  );
-
-  assert.deepEqual(
-    createJsonApiInputRecord("products", {
-      serviceId: "9",
-      name: "Style Groom"
-    }, {
-      resource: {
-        schema: {
-          serviceId: {
-            type: "id",
-            belongsTo: "services",
-            as: "service"
-          },
-          name: {
-            type: "string"
-          }
-        }
-      }
-    }),
-    {
-      data: {
-        type: "products",
-        attributes: {
-          name: "Style Groom"
-        },
-        relationships: {
-          service: {
-            data: {
-              type: "services",
-              id: "9"
-            }
-          }
-        }
-      }
-    }
-  );
-
 });
 
 test("buildJsonRestQueryParams preserves structured filter values", () => {
@@ -424,16 +373,7 @@ test("createJsonRestResourceScopeOptions clones canonical resource metadata and
   assert.equal(result.schema.createdAt.storage.serialize, serializer);
   assert.equal(result.schema.createdAt.storage.serialize(null), null);
   assert.equal(result.schema.createdAt.storage.writeSerializer, undefined);
-  assert.equal(
-    result.schema.publishedOn.storage.serialize(new Date("2024-02-29T00:00:00.000Z")),
-    "2024-02-29"
-  );
-  assert.equal(result.schema.publishedOn.storage.serialize("2024-02-29"), "2024-02-29");
-  assert.equal(result.schema.publishedOn.storage.serialize(null), null);
-  assert.throws(
-    () => result.schema.publishedOn.storage.serialize("2023-02-29"),
-    /valid YYYY-MM-DD/
-  );
+  assert.equal(result.schema.publishedOn.storage, undefined);
   assert.equal(result.schema.bookingSteps.virtual, true);
   assert.equal(result.schema.pets.virtual, true);
   assert.equal(result.normalizeId, normalizeId);
@@ -604,22 +544,18 @@ test("createJsonRestResourceScopeOptions rejects query field names for column-ba
   );
 });
 
-test("createJsonRestApiHost installs json-rest-api query projections", async () => {
-  const fakeKnex = Object.assign(() => {}, {
-    client: {
-      config: {
-        client: "sqlite3"
-      }
-    },
-    raw(sql) {
-      if (String(sql || "").includes("sqlite_version")) {
-        return [{ version: "3.35.5" }];
-      }
-      return { sql };
-    },
-    async transaction() {}
+test("createJsonRestApiHost installs json-rest-api query projections", async (t) => {
+  const knex = knexLib({
+    client: "better-sqlite3",
+    connection: { filename: ":memory:" },
+    useNullAsDefault: true
   });
-  const api = await createJsonRestApiHost({ knex: fakeKnex });
+  t.after(() => knex.destroy());
+  await knex.schema.createTable("projection_contacts", (table) => {
+    table.increments("id");
+  });
+  await knex("projection_contacts").insert({ id: 1 });
+  const api = await createJsonRestApiHost({ knex });
 
   await api.addResource("projectionContacts", {
     tableName: "projection_contacts",
@@ -636,130 +572,119 @@ test("createJsonRestApiHost installs json-rest-api query projections", async ()
     }
   });
 
-  assert.equal(typeof api.resources.projectionContacts.vars.queryFields.displayName.select, "function");
+  const result = await api.resources.projectionContacts.query({ format: "plain" });
+  assert.deepEqual(result.data, [{ id: "1", displayName: "Display" }]);
 });
 
-test("createJsonRestApiHost returns JSON-native temporal values from database records", async () => {
-  const fakeKnex = Object.assign(() => {}, {
-    client: {
-      config: {
-        client: "sqlite3"
-      }
-    },
-    async raw() {
-      return [{ version: "3.35.5" }];
-    },
-    transaction() {}
+async function createTemporalFixture() {
+  const knex = knexLib({
+    client: "better-sqlite3",
+    connection: { filename: ":memory:" },
+    useNullAsDefault: true
   });
-  const api = await createJsonRestApiHost({ knex: fakeKnex });
-
-  await api.addResource("books", createJsonRestResourceScopeOptions({
-    tableName: "books",
-    schema: {
-      id: { type: "id", primary: true },
-      publishedOn: { type: "date" },
-      scheduledAt: { type: "dateTime" },
-      opensAt: { type: "time" }
-    }
-  }));
-  await api.addResource("holidays", createJsonRestResourceScopeOptions({
-    tableName: "holidays",
-    schema: {
-      id: { type: "id", primary: true },
-      observedOn: { type: "date" }
-    }
-  }));
-
-  const scheduledAt = new Date("2024-02-29T12:34:56.000Z");
-  const record = {
-    data: {
-      type: "books",
-      id: "1",
-      attributes: {
-        publishedOn: new Date("2024-02-29T00:00:00.000Z"),
-        scheduledAt,
-        opensAt: "09:45:00"
+  try {
+    await knex.schema.createTable("holidays", (table) => {
+      table.increments("id");
+      table.date("observed_on");
+    });
+    await knex.schema.createTable("books", (table) => {
+      table.increments("id");
+      table.date("published_on");
+      table.dateTime("scheduled_at");
+      table.time("opens_at");
+      table.integer("holiday_id").references("id").inTable("holidays");
+    });
+    const api = await createJsonRestApiHost({ knex });
+    await api.addResource("holidays", createJsonRestResourceScopeOptions({
+      tableName: "holidays",
+      schema: {
+        id: { type: "id", primary: true },
+        observedOn: { type: "date" }
       }
-    },
-    included: [{
-      type: "holidays",
-      id: "7",
-      attributes: {
-        observedOn: new Date("2024-03-01T00:00:00.000Z")
+    }));
+    await api.addResource("books", createJsonRestResourceScopeOptions({
+      tableName: "books",
+      schema: {
+        id: { type: "id", primary: true },
+        publishedOn: { type: "date" },
+        scheduledAt: { type: "dateTime" },
+        opensAt: { type: "time" },
+        holidayId: { type: "id", belongsTo: "holidays", as: "holiday", nullable: true }
       }
-    }]
-  };
+    }));
+    return { api, knex };
+  } catch (error) {
+    await knex.destroy();
+    throw error;
+  }
+}
 
-  await api.runHooks("finish", {
-    record
+test("createJsonRestApiHost uses core temporal normalization for writes, reads and includes", async (t) => {
+  const { api, knex } = await createTemporalFixture();
+  t.after(() => knex.destroy());
+  const holiday = await api.resources.holidays.post({ data: { observedOn: "2024-03-01" } });
+  const book = await api.resources.books.post({
+    data: {
+      publishedOn: "2024-02-29",
+      scheduledAt: "2024-02-29T20:34:56+08:00",
+      opensAt: "09:45",
+      holiday: holiday.id
+    }
   });
 
-  assert.equal(record.data.attributes.publishedOn, "2024-02-29");
-  assert.equal(record.data.attributes.scheduledAt, "2024-02-29T12:34:56.000Z");
-  assert.equal(record.data.attributes.opensAt, "09:45:00");
-  assert.equal(record.included[0].attributes.observedOn, "2024-03-01");
+  assert.equal(book.publishedOn, "2024-02-29");
+  assert.equal(book.scheduledAt, "2024-02-29T12:34:56.000Z");
+  assert.equal(book.opensAt, "09:45:00");
+  const document = await api.resources.books.get({
+    id: book.id,
+    format: "jsonapi",
+    queryParams: { include: ["holiday"] }
+  });
+  assert.equal(document.data.attributes.publishedOn, "2024-02-29");
+  assert.equal(document.data.attributes.scheduledAt, "2024-02-29T12:34:56.000Z");
+  assert.equal(document.included[0].attributes.observedOn, "2024-03-01");
+  await assert.rejects(
+    () => api.resources.books.patch({ id: book.id, data: { publishedOn: "2023-02-29" } }),
+    (error) => error.code === "REST_API_VALIDATION"
+  );
 });
 
 test("calendar date writes and responses keep leap day across server time zones", () => {
-  const hostModuleUrl = new URL(
-    "../src/server/jsonRestApiHost.js",
-    import.meta.url
-  ).href;
+  const hostModuleUrl = new URL("../src/server/jsonRestApiHost.js", import.meta.url).href;
   const script = `
-    import {
-      createJsonRestApiHost,
-      createJsonRestResourceScopeOptions
-    } from ${JSON.stringify(hostModuleUrl)};
-    const fakeKnex = Object.assign(() => {}, {
-      client: { config: { client: "sqlite3" } },
-      async raw() { return [{ version: "3.35.5" }]; },
-      transaction() {}
-    });
-    const api = await createJsonRestApiHost({ knex: fakeKnex });
-    const scopeOptions = createJsonRestResourceScopeOptions({
-      tableName: "books",
-      schema: {
-        id: { type: "id", primary: true },
-        publishedOn: { type: "date" },
-        scheduledAt: { type: "dateTime" },
-        opensAt: { type: "time" }
-      }
-    });
-    await api.addResource("books", scopeOptions);
-    const record = {
-      data: {
-        type: "books",
-        id: "1",
-        attributes: {
-          publishedOn: new Date("2024-02-29T00:00:00.000Z"),
-          scheduledAt: new Date("2024-02-29T12:34:56.000Z"),
+    import knexLib from "knex";
+    import { createJsonRestApiHost, createJsonRestResourceScopeOptions } from ${JSON.stringify(hostModuleUrl)};
+    ${createTemporalFixture.toString()}
+    const { api, knex } = await createTemporalFixture();
+    try {
+      const book = await api.resources.books.post({
+        data: {
+          publishedOn: "2024-02-29",
+          scheduledAt: "2024-02-29T12:34:56.000Z",
           opensAt: "09:45:00"
         }
-      }
-    };
-    await api.runHooks("finish", { record });
-    process.stdout.write(JSON.stringify({
-      write: scopeOptions.schema.publishedOn.storage.serialize(
-        new Date("2024-02-29T00:00:00.000Z")
-      ),
-      publishedOn: record.data.attributes.publishedOn,
-      scheduledAt: record.data.attributes.scheduledAt,
-      opensAt: record.data.attributes.opensAt
-    }));
+      });
+      const row = await knex("books").where({ id: book.id }).first();
+      process.stdout.write(JSON.stringify({
+        write: row.published_on,
+        publishedOn: book.publishedOn,
+        scheduledAt: book.scheduledAt,
+        opensAt: book.opensAt
+      }));
+    } finally {
+      await knex.destroy();
+    }
   `;
 
   for (const timezone of ["UTC", "Australia/Perth", "America/Los_Angeles", "Pacific/Kiritimati"]) {
     const result = spawnSync(process.execPath, ["--input-type=module", "--eval", script], {
       encoding: "utf8",
-      env: {
-        ...process.env,
-        TZ: timezone
-      }
+      env: { ...process.env, TZ: timezone }
     });
 
     assert.equal(result.status, 0, result.stderr);
     assert.deepEqual(JSON.parse(result.stdout), {
-      write: "2024-02-29",
+      write: Date.parse("2024-02-29T00:00:00.000Z"),
       publishedOn: "2024-02-29",
       scheduledAt: "2024-02-29T12:34:56.000Z",
       opensAt: "09:45:00"
@@ -767,36 +692,17 @@ test("calendar date writes and responses keep leap day across server time zones"
   }
 });
 
-test("createJsonRestApiHost maps UTC database datetimes to RFC 3339 strings", async () => {
-  const fakeKnex = Object.assign(() => {}, {
-    client: { config: { client: "sqlite3" } },
-    async raw() {
-      return [{ version: "3.35.5" }];
-    },
-    transaction() {}
+test("createJsonRestApiHost maps native database datetime strings through core reads", async (t) => {
+  const { api, knex } = await createTemporalFixture();
+  t.after(() => knex.destroy());
+  await knex("books").insert({
+    id: 1,
+    published_on: "2024-02-29",
+    scheduled_at: "2024-02-29 12:34:56.123",
+    opens_at: "09:45:00"
   });
-  const api = await createJsonRestApiHost({ knex: fakeKnex });
-
-  await api.addResource("jobs", createJsonRestResourceScopeOptions({
-    tableName: "jobs",
-    schema: {
-      id: { type: "id", primary: true },
-      scheduledAt: { type: "dateTime" }
-    }
-  }));
-  const record = {
-    data: {
-      type: "jobs",
-      id: "1",
-      attributes: {
-        scheduledAt: "2024-02-29 12:34:56.123"
-      }
-    }
-  };
-
-  await api.runHooks("finish", { record });
-
-  assert.equal(record.data.attributes.scheduledAt, "2024-02-29T12:34:56.123Z");
+  const book = await api.resources.books.get({ id: "1" });
+  assert.equal(book.scheduledAt, "2024-02-29T12:34:56.123Z");
 });
 
 test("returnNullWhenJsonRestResourceMissing only swallows missing-resource errors", async () => {
@@ -841,6 +747,7 @@ test("typed invalid sparse fields become a stable 400 without message matching",
       assert.equal(error.status, 400);
       assert.equal(error.code, "JSON_API_FIELDSET_INVALID");
       assert.equal(error.message, sparseFieldError.message);
+      assert.equal(error.cause, sparseFieldError);
       return true;
     }
   );
@@ -862,6 +769,47 @@ test("typed invalid sparse fields become a stable 400 without message matching",
   );
 });
 
+test("missing-resource mapping preserves failures from unresolved or committed writes", async () => {
+  const cause = Object.freeze({ code: "REST_API_RESOURCE", subtype: "not_found" });
+  for (const transactionOutcome of ["pending", "committed", "unknown"]) {
+    const failure = new RestApiWriteError("Missing resource", { cause, transactionOutcome });
+    await assert.rejects(
+      () => returnNullWhenJsonRestResourceMissing(() => Promise.reject(failure)),
+      (error) => error === failure
+    );
+  }
+  for (const transactionOutcome of ["none", "rolledBack"]) {
+    const failure = new RestApiWriteError("Missing resource", { cause, transactionOutcome });
+    assert.equal(await returnNullWhenJsonRestResourceMissing(() => Promise.reject(failure)), null);
+  }
+});
+
+test("fieldset mapping retains write outcome and the original error chain", async () => {
+  const cause = Object.freeze(new RestApiFieldsetError({ field: "privateNotes", resourceType: "books" }));
+  const failure = new RestApiWriteError(cause.message, { cause, transactionOutcome: "committed" });
+  await assert.rejects(
+    () => returnBadRequestWhenJsonRestFieldsetInvalid(() => Promise.reject(failure)),
+    (error) => {
+      assert.equal(error.code, "JSON_API_FIELDSET_INVALID");
+      assert.equal(error.transactionOutcome, "committed");
+      assert.equal(error.cause, failure);
+      assert.equal(error.cause.cause, cause);
+      return true;
+    }
+  );
+});
+
+test("unrelated primitive failures remain unchanged through host error mapping", async () => {
+  for (const failure of [null, undefined, "failure", 7]) {
+    for (const mapError of [returnNullWhenJsonRestResourceMissing, returnBadRequestWhenJsonRestFieldsetInvalid]) {
+      await assert.rejects(
+        () => mapError(() => Promise.reject(failure)),
+        (error) => error === failure
+      );
+    }
+  }
+});
+
 test("scope resolvers understand explicit scopeValues and JSKIT visibilityContext", () => {
   assert.equal(resolveWorkspaceScopeValue({
     scopeValues: {