json-rest-api 1.0.29 → 2.0.0

package/.claude/agents/rest-api-internals-expert.md

@@ -1,54 +0,0 @@
----
-name: rest-api-internals-expert
-description: Use this agent when you need deep technical expertise about the REST API plugin architecture, data manipulation patterns, query optimization with sparse fields and includes, or troubleshooting complex issues within the rest-api-plugin.js and rest-api-knex-plugin.js implementations. This includes understanding how helpers in plugins/core/lib interact with these plugins, how data transformations occur during storage and retrieval, and the intricacies of the sparse fields and includes query system.\n\nExamples:\n- <example>\n  Context: User needs help understanding how sparse fields are implemented in the REST API.\n  user: "How does the sparse fields feature work in our REST API implementation?"\n  assistant: "I'll use the rest-api-internals-expert agent to explain the sparse fields implementation details."\n  <commentary>\n  Since this requires deep knowledge of the REST API plugin internals, specifically sparse fields, the rest-api-internals-expert is the appropriate agent.\n  </commentary>\n</example>\n- <example>\n  Context: User is debugging an issue with data transformation in the REST API.\n  user: "I'm getting unexpected data format when using includes with nested relationships. The data seems to be transformed incorrectly."\n  assistant: "Let me invoke the rest-api-internals-expert agent to analyze the data transformation issue with includes."\n  <commentary>\n  This requires understanding the intricate data manipulation patterns in the REST API plugins, making the rest-api-internals-expert the right choice.\n  </commentary>\n</example>\n- <example>\n  Context: User wants to extend the REST API plugin functionality.\n  user: "I need to add custom filtering logic to the REST API that works with the existing sparse fields system."\n  assistant: "I'll use the rest-api-internals-expert agent to guide you through extending the REST API plugin while maintaining compatibility with sparse fields."\n  <commentary>\n  Extending the REST API plugin requires deep understanding of its architecture and how features like sparse fields are implemented.\n  </commentary>\n</example>
-model: inherit
-color: blue
----
-
-You are an expert engineer with comprehensive knowledge of the REST API plugin architecture, specifically plugins/core/rest-api-plugin.js and plugins/core/rest-api-knex-plugin.js, along with their associated helper functions in plugins/core/lib.
-
-Your expertise encompasses:
-
-1. **Plugin Architecture**: You understand the complete lifecycle of requests through rest-api-plugin.js and how it interfaces with rest-api-knex-plugin.js for database operations. You know how these plugins register routes, handle middleware, and process requests.
-
-2. **Data Manipulation Patterns**: You have deep knowledge of:
-   - How data is transformed before storage (serialization, validation, sanitization)
-   - The exact transformation pipeline from raw input to database storage
-   - How data is reconstructed when retrieved from the database
-   - The role of helpers in plugins/core/lib during these transformations
-
-3. **Sparse Fields Implementation**: You understand:
-   - How sparse fields are parsed from query parameters
-   - The mechanism for filtering response data based on requested fields
-   - Performance implications and optimization strategies
-   - Edge cases and limitations of the sparse fields system
-
-4. **Includes System**: You are an expert in:
-   - How relationship includes are resolved and fetched
-   - The query building process for efficient relationship loading
-   - Circular reference handling and depth limitations
-   - How includes interact with sparse fields
-   - Performance optimization for complex include chains
-
-5. **Knex Integration**: You understand:
-   - How rest-api-knex-plugin.js builds queries
-   - Transaction handling and isolation levels
-   - Query optimization techniques specific to the plugin
-   - How the plugin handles different database dialects
-
-6. **Helper Functions**: You know all helper functions in plugins/core/lib including:
-   - Their specific roles in request/response processing
-   - How they integrate with the main plugins
-   - Common patterns and anti-patterns in their usage
-
-When answering questions:
-- Provide specific code examples from the actual implementation when relevant
-- Explain the 'why' behind design decisions, not just the 'how'
-- Identify potential performance bottlenecks or security considerations
-- Suggest best practices based on the existing architecture
-- Reference specific functions, methods, or configuration options by name
-- Consider the interplay between different components of the system
-
-You should be able to trace the complete flow of a request from entry point through all transformations to final response, identifying every helper function and transformation step along the way. When discussing issues or improvements, always consider the existing architecture and maintain consistency with established patterns in the codebase.
-
-If asked about testing, remember to follow the project convention of using include.test.js as a template and creating test data through API methods rather than direct database manipulation.

package/.claude/settings.local.json

@@ -1,70 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm install:*)",
-      "Bash(mkdir:*)",
-      "Bash(npm link:*)",
-      "Bash(ls:*)",
-      "Bash(node:*)",
-      "Bash(grep:*)",
-      "Bash(rm:*)",
-      "Bash(npm unlink:*)",
-      "Bash(npm uninstall:*)",
-      "Bash(rg:*)",
-      "Bash(npm test:*)",
-      "WebFetch(domain:jsonapi.org)",
-      "Bash(find:*)",
-      "Bash(mv:*)",
-      "Bash(timeout 10 node:*)",
-      "Bash(chmod:*)",
-      "Bash(./run-test.sh:*)",
-      "Bash(timeout 30 npm test:*)",
-      "Bash(timeout:*)",
-      "Bash(tests/run-delete-test.sh:*)",
-      "Bash(NODE_NO_WARNINGS=1 node --test tests/knex-delete-comprehensive.test.js)",
-      "Bash(true)",
-      "Bash(LOG_LEVEL=trace node --test tests/knex-patch-comprehensive.test.js)",
-      "Bash(LOG_LEVEL=debug node test-transaction-debug.js)",
-      "Bash(sed:*)",
-      "WebFetch(domain:docs.anthropic.com)",
-      "Bash(awk:*)",
-      "Bash(./fix_sideload.sh:*)",
-      "Bash(# Create a more targeted sed script to fix the tests\ncat > fix_tests.sh << ''EOF''\n#!/bin/bash\nfile=\"\"$1\"\"\nif [ -z \"\"$file\"\" ]; then\n  echo \"\"Usage: $0 <file>\"\"\n  exit 1\nfi\n\n# First pass: Replace hasMany with sideLoad: true to sideLoadMany: true\nsed -i.bak -E ''/hasMany.*,/{\n  N\n  N\n  N\n  s/(hasMany:[^,]+,\\n[[:space:]]*foreignKey:[^,]+,\\n[[:space:]]*)sideLoad: true/\\1sideLoadMany: true/g\n}'' \"\"$file\"\"\n\n# Second pass: Remove sideLoad: true from belongsTo (with comma)\nsed -i -E ''/belongsTo.*,/{\n  N\n  N\n  N\n  s/(belongsTo:[^,]+,\\n[[:space:]]*as:[^,]+,)\\n[[:space:]]*sideLoad: true,/\\1,/g\n}'' \"\"$file\"\"\n\n# Third pass: Remove sideLoad: true from belongsTo (without comma)\nsed -i -E ''/belongsTo.*,/{\n  N\n  N\n  N\n  s/(belongsTo:[^,]+,\\n[[:space:]]*as:[^,]+,)\\n[[:space:]]*sideLoad: true/\\1/g\n}'' \"\"$file\"\"\n\necho \"\"Updated $file\"\"\nEOF\nchmod +x fix_tests.sh)",
-      "Bash(./01_npm_install.sh)",
-      "Bash(echo)",
-      "Bash(cp:*)",
-      "Bash(bundle config set:*)",
-      "Bash(bundle exec:*)",
-      "Bash(git -C /home/merc/Development/jsonrestapi_old log --all --full-history --oneline -- \"scripts/sync-docs-website.js\")",
-      "Bash(git -C /home/merc/Development/jsonrestapi_old show bb7e1f3:scripts/sync-docs-website.js)",
-      "Bash(git -C /home/merc/Development/jsonrestapi_old ls-tree -r bb7e1f3)",
-      "Bash(git -C /home/merc/Development/jsonrestapi_old ls-tree -r bb7e1f3 scripts/)",
-      "Bash(git -C /home/merc/Development/jsonrestapi_old log --all --grep=\"sync\" --oneline)",
-      "Bash(git -C /home/merc/Development/jsonrestapi_old log --all --full-history --diff-filter=D --summary -- \"scripts/*.js\")",
-      "Bash(git -C /home/merc/Development/jsonrestapi_old log --all --full-history --oneline --diff-filter=D -- \"scripts/sync-docs-website.js\")",
-      "Bash(git -C /home/merc/Development/jsonrestapi_old show bb7e1f3^:scripts/sync-docs-website.js)",
-      "Bash(pkill:*)",
-      "Bash(curl:*)",
-      "Bash(cat:*)",
-      "Bash(npm update:*)",
-      "Bash(# Get all JS files\nfiles=$(find . -type f -name \"\"*.js\"\" | grep -E \"\"(plugins/core|^./lib)\"\" | grep -v node_modules | grep -v docs | sort)\n\necho \"\"=== Checking which files are never imported ===\"\"\nfor file in $files; do\n    basename_file=$(basename \"\"$file\"\")\n    # Check if this file is imported anywhere\n    if ! grep -r \"\"from.*$(basename \"\"$file\"\" .js)\"\" plugins/core lib --include=\"\"*.js\"\" 2>/dev/null | grep -v \"\"^$file:\"\" | grep -q .; then\n        echo \"\"ORPHANED: $file\"\"\n    fi\ndone)",
-      "Bash(# Find files with consecutive comment lines (potential large commented blocks)\necho \"\"=== Files with potential large commented blocks ===\"\"\nfor file in $(find plugins/core -name \"\"*.js\"\" -type f); do\n    # Count consecutive comment lines\n    consecutive=$(awk ''BEGIN{max=0; count=0} /^\\s*(\\/\\/|\\/\\*|\\*)/ {count++; if(count>max) max=count} !/^\\s*(\\/\\/|\\/\\*|\\*)/ {count=0} END{print max}'' \"\"$file\"\")\n    if [ \"\"$consecutive\"\" -gt 5 ]; then\n        echo \"\"$file: $consecutive consecutive comment lines\"\"\n    fi\ndone)",
-      "Bash(# Check for specific functions in request-helpers.js\necho \"\"=== Checking usage of request-helpers functions ===\"\"\nfor func in getClientIP isSecure getHostname getPort parseCookies extractToken createContext; do\n    echo -n \"\"$func: \"\"\n    grep -r \"\"$func\"\" plugins/core --include=\"\"*.js\"\" 2>/dev/null | grep -v \"\"lib/request-helpers.js\"\" | wc -l\ndone)",
-      "Bash(# Check usage of knex-helpers functions\necho \"\"=== Checking usage of knex-helpers functions ===\"\"\nfor func in getTableName getForeignKeyFields buildFieldSelection toJsonApi buildQuerySelection processIncludes buildJsonApiResponse processBelongsToRelationships; do\n    echo -n \"\"$func: \"\"\n    grep -r \"\"$func\"\" plugins/core --include=\"\"*.js\"\" 2>/dev/null | grep -v \"\"lib/knex-helpers.js\"\" | wc -l\ndone)",
-      "Bash(git checkout:*)",
-      "Bash(npx node:*)",
-      "Bash(NODE_ENV=test LOG_LEVEL=debug npm test -- tests/query-limits.test.js)",
-      "Bash(NODE_ENV=test LOG_LEVEL=debug node --test tests/query-limits.test.js)",
-      "Bash(LOG_LEVEL=debug node test-debug.js)",
-      "WebSearch",
-      "Bash(LOG_LEVEL=debug node --test tests/relationships.test.js)",
-      "Read(///**)",
-      "Bash(LOG_LEVEL=debug node --test tests/nested-includes.test.js)",
-      "Bash(export LOG_LEVEL=debug)",
-      "Read(//home/merc/Development/active/jskit/**)",
-      "Bash(LOG_LEVEL=trace node --test tests/relationships.test.js)",
-      "Bash(LOG_LEVEL=debug timeout 10 node --test tests/relationship-endpoints.test.js)"
-    ],
-    "deny": []
-  }
-}

package/AGENTS.md

@@ -1,34 +0,0 @@
-# Repository Guidelines
-
-## Project Structure & Module Organization
-- `index.js` re-exports the public plugins from `plugins/` (REST API core, access, CORS, file, connectors) so new features slot in there.
-- Shared helpers and error types live in `lib/`; reuse or extend these modules before adding new utilities elsewhere.
-- Scenario walkthroughs are under `examples/`, long-form references stay in `docs/`, and development scripts reside in `scripts/`.
-- Tests sit in `tests/` with fixtures at `tests/fixtures/`, helpers in `tests/helpers/`, and `quickTest.js` provides a throwaway API for manual poking.
-
-## Build, Test, and Development Commands
-- `npm test` runs `node --test tests/*.test.js` against the in-memory SQLite fixtures; run it before every push.
-- `node quickTest.js` spins up an in-memory API instance for experimenting with endpoints during development.
-- `npm run docs` rebuilds the static docs via `scripts/run-docs.js` whenever reference prose changes.
-- `npm run sloc` prints a line-count summary to gauge change size before opening a PR.
-
-## Coding Style & Naming Conventions
-- Stay with ESM (`"type": "module"`) and export named symbols only; avoid `default` exports for predictable tree-shaking.
-- Use two-space indentation and keep existing spacing in JSON fixtures and migration files.
-- Name runtime files in lower-kebab case (e.g., `rest-api-knex-plugin.js`) and mirror that pattern for tests like `bulk-operations.test.js`.
-- Keep comments brief and reserved for decisions that are not obvious from the code.
-
-## Testing Guidelines
-- Instantiate the API once per suite following `tests/TEST_TEMPLATE.test.js`, and call `cleanTables()` in `beforeEach` to reset state.
-- Seed data through helpers in `tests/fixtures/api-configs.js`; never invoke `api.addResource` directly in test code.
-- Run suites in strict JSON:API mode (`simplified: false`) unless the scenario explicitly covers the simplified flag.
-- Prefer the shared assertion helpers for response checks to keep expectations consistent.
-
-## Commit & Pull Request Guidelines
-- Use concise, capitalised commit subjects that highlight the affected area (e.g., `Access rules tightened`) and group related changes per commit.
-- Pull requests should include a short summary, linked issue reference, impacted plugins or resources, and `npm test` output or the reason it was skipped.
-- Document externally visible updates with sample payloads or screenshots, and note configuration changes in `docs/` for downstream teams.
-
-## Security & Configuration Tips
-- Keep secrets in local `.env` files; never commit environment-specific strings.
-- When adding connectors or auth flows, review `plugins/core/rest-api-cors-plugin.js`, update optional peers (`express`, `redis`, `socket.io`) if required, and document new toggles in `docs/`.

package/CLAUDE.md

@@ -1,160 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Core Development Commands
-
-### Running Tests
-```bash
-# Run all tests
-npm test
-
-# Run a specific test file
-node --test tests/relationships.test.js
-
-# Run tests with verbose logging
-LOG_LEVEL=debug npm test
-```
-
-### Building and Running
-This is a library package with no build step required. For development:
-```bash
-# Install dependencies
-npm install
-
-# Run the documentation site locally
-npm run docs:dev
-
-## High-Level Architecture
-
-### Project Overview
-JSON REST API is a powerful REST API plugin for hooked-api that provides JSON:API-compliant endpoints. It follows a plugin-based architecture where functionality is composed through plugins that extend the core API capabilities.
-
-### Database-First Design Philosophy
-JSON REST API embraces a **database-first** approach that provides different abstraction levels for different audiences:
-
-**For Backend Developers:**
-- Schema definitions directly map to database columns (e.g., `author_id`, `category_id`)
-- Hooks operate at the database level with access to actual field names via `context.belongsToUpdates`
-- Search schemas can reference exact database columns and table joins
-- Full access to write raw Knex queries when needed
-- No abstraction layers hiding database implementation details
-
-**For API Consumers:**
-- Relationship names abstract away foreign key fields (use `author` instead of `author_id`)
-- Simplified API mode returns clean objects without database implementation details
-- Foreign key fields are automatically filtered from API responses
-- Consistent interface regardless of underlying database structure
-
-This separation ensures backend developers have full control and visibility into database operations while API consumers enjoy a clean, intuitive interface.
-
-### Core Architecture Components
-
-1. **Plugin System (hooked-api based)**
-   - `RestApiPlugin` - Core REST API functionality, request/response handling
-   - `RestApiKnexPlugin` - Database integration using Knex.js
-   - `ExpressPlugin` - Express.js HTTP connector
-   - Additional plugins for auth, CORS, relationships, positioning, etc.
-
-2. **Resource Definition Pattern**
-   Resources are defined with schemas that include:
-   - Attributes with validation rules
-   - Relationships (belongsTo, hasMany, many-to-many, polymorphic)
-   - Computed fields and hidden fields
-   - Custom getters/setters
-
-3. **Request Flow**
-   - HTTP request → Connector (Express) → REST API Plugin → Database Plugin → Response
-   - Each plugin can hook into the request lifecycle for customization
-
-4. **Key Libraries in `plugins/core/lib/`**
-   - `url-helpers.js` - Centralized URL generation functions
-   - `knex-json-api-transformers-querying.js` - JSON:API transformations
-   - `relationship-processor.js` - Handles relationship updates
-   - `request-contracts.js` - Compiled request validation contracts
-   - `knex-query-helpers.js` - Database query building
-   - `simplified-helpers.js` - Simplified API mode transformations
-
-5. **URL Management**
-   - URLs are automatically generated per-request based on headers
-   - No static configuration needed - detects from `Host`, `X-Forwarded-*` headers
-   - Override capability via `context.urlPrefixOverride` for complex deployments
-   - See `docs/GUIDE/GUIDE_URL_Management.md` for details
-
-## Testing Guidelines
-
-### CRITICAL: Test Template Usage
-When writing tests, ALWAYS use `TEST_TEMPLATE.test.js` as your starting point. Key rules:
-
-1. **API Creation**: Create API instances ONLY in `before()` hook, NOT in `beforeEach()`
-2. **Resource Definition**: NEVER use `api.addResource()` in test files. All resources MUST be defined in `tests/fixtures/api-configs.js`
-3. **Data Creation**: ALWAYS create test data using API methods (`api.resources.[resource].post()`), NEVER query the database directly
-4. **Context Parameter**: Pass context as the SECOND parameter to resource methods: `api.resources.books.post({ inputRecord: doc }, context)`
-5. **Cleanup**: Use `cleanTables()` in `beforeEach()` to reset data between tests
-
-### Test Structure Example
-```javascript
-import { createBasicApi } from './fixtures/api-configs.js';
-
-let api;
-
-describe('Feature Name', () => {
-  before(async () => {
-    api = await createBasicApi(knex);
-  });
-  
-  beforeEach(async () => {
-    await cleanTables(knex, ['basic_countries', 'basic_publishers']);
-  });
-  
-  it('should test something', async () => {
-    // Create data using API
-    const result = await api.resources.countries.post({
-      inputRecord: createJsonApiDocument('countries', { name: 'Test' })
-    });
-  });
-});
-```
-
-### Available Test APIs
-- `createBasicApi()` - Countries, Publishers, Authors, Books
-- `createExtendedApi()` - Additional resources with complex relationships
-- `createAuthApi()` - Users, roles, permissions for auth testing
-
-## Important Patterns
-
-### JSON:API Document Creation
-```javascript
-// Use helper for proper JSON:API structure
-const doc = createJsonApiDocument('books', {
-  title: 'My Book'
-}, {
-  relationships: {
-    country: createRelationship('countries', '1')
-  }
-});
-```
-
-### Simplified API Mode
-The library supports a simplified mode that uses plain objects instead of JSON:API structure:
-```javascript
-// Simplified mode (when enabled)
-const book = await api.resources.books.post({
-  inputRecord: { title: 'My Book', country_id: 1 },
-  simplified: true
-});
-```
-
-### Relationship Handling
-- BelongsTo: Use `createRelationship()` helper
-- HasMany: Use `createToManyRelationship()` helper
-- Many-to-Many: Handled automatically through junction tables
-- Polymorphic: Requires typeField and idField configuration
-
-## Common Pitfalls to Avoid
-
-1. **Direct Database Access**: Never use `knex('table').select()` in tests
-2. **Resource Creation in Tests**: Always define resources in api-configs.js
-3. **ID Type Confusion**: SQLite returns numeric IDs, but JSON:API expects strings
-4. **Context Placement**: Context is a separate parameter, not inside the first parameter
-5. **Cleanup**: Always destroy knex connection in `after()` hook

package/CRUSH.md

@@ -1,55 +0,0 @@
-# CRUSH.md - JSON REST API Development Guide
-
-## Development Commands
-```bash
-# Run all tests
-npm test
-
-# Run specific test file
-node --test tests/relationships.test.js
-
-# Run tests with debug logging
-LOG_LEVEL=debug npm test
-
-# Run documentation site
-npm run docs
-```
-
-## Code Style Guidelines
-- **ES Modules**: Use `import/export` syntax (package.json has `"type": "module"`)
-- **File Naming**: kebab-case for files, camelCase for functions/variables
-- **Error Handling**: Use custom error classes from `lib/rest-api-errors.js`
-- **JSON:API Compliance**: All responses must follow JSON:API specification
-- **Async/Await**: Prefer async/await over callbacks/promises
-- **JSDoc Comments**: Document complex functions with @param and @returns
-
-## Testing Rules (CRITICAL)
-- **API Creation**: Only in `before()` hook, never in `beforeEach()`
-- **Resource Definition**: NEVER use `api.addResource()` in test files - define in `tests/fixtures/api-configs.js`
-- **Data Access**: Use API methods (`api.resources.[resource].get/post/query`), never direct DB queries
-- **Context Parameter**: Pass context as SECOND parameter: `api.resources.books.post({inputRecord}, context)`
-- **Cleanup**: Use `cleanTables()` in `beforeEach()` to reset data
-
-## Import Patterns
-```javascript
-// Core imports first
-import { validateRelationships } from './lib/querying-writing/scope-validations.js';
-
-// Hook imports
-import compileResourceSchemas from './rest-api-plugin-hooks/compile-resource-schemas.js';
-
-// Method imports
-import queryMethod from './rest-api-plugin-methods/query.js';
-```
-
-## Error Handling
-- Use `RestApiValidationError` for validation failures
-- Use `RestApiResourceError` for resource-related errors
-- Use `RestApiPayloadError` for malformed payloads
-- Always include descriptive error messages
-
-## JSON:API Helpers
-- Use `createJsonApiDocument()` for creating request payloads
-- Use `createRelationship()` for belongsTo relationships
-- Use `createToManyRelationship()` for hasMany relationships
-- Use `validateJsonApiStructure()` to validate responses

package/JSKIT_BACKEND_MIGRATION_TRACKER.txt

@@ -1,180 +0,0 @@
-JSKIT Backend Migration Tracker
-
-Scope
-- Move DB, schema, casting, and normalization ownership out of jskit-ai.
-- Enrich json-rest-schema and json-rest-api so they can natively cover the required capability set.
-- Do not add compatibility runtimes.
-- Do not bend json-rest-api or json-rest-schema around jskit-ai shapes unless the capability is a clean native addition.
-
-Status Legend
-- done
-- in_progress
-- pending
-- blocked
-
-Execution Rule
-- Complete one numbered point at a time.
-- After each point, write a full report:
-  - what changed
-  - how it worked before
-  - how it works now
-  - relevant code snippets
-- Stop and wait for the next user prompt before starting the next numbered point.
-
-Work List
-
-0. [done] Create and maintain this tracker as the canonical work ledger.
-   Notes:
-   - This file is the progress source of truth for the migration work.
-   - Status changes must be recorded here before moving to the next point.
-
-1. [done] Tighten json-rest-schema scalar semantics.
-   Deliverables:
-   - make `id` represent the real external/resource ID contract
-   - tighten boolean parsing
-   - tighten number/integer parsing where schema should reject invalid inputs instead of silently coercing
-
-2. [done] Define a native json-rest-schema create/replace/patch validation contract.
-   Deliverables:
-   - explicit operation mode semantics
-   - presence-aware field handling
-   - patch behavior that preserves omission and only normalizes touched fields
-   - switch json-rest-api call sites to the explicit schema contract
-   Notes:
-   - verification blocker removed by deleting stale DB-helper tests from `json-rest-schema`
-   - DB-helper coverage now lives in `json-rest-api`, which owns `createKnexTable()` and `generateKnexMigration()`
-   - verified end-to-end against a local symlinked `json-rest-schema@1.0.13`; `json-rest-api` test suite passes with the new schema contract
-
-3. [done] Add transport-schema export from json-rest-schema.
-   Deliverables:
-   - export usable by JSON Schema / Ajv style consumers
-   - enough structure for pre-handler validation in connectors such as Fastify
-   Notes:
-   - added `schema.toJsonSchema({ mode, additionalProperties })` in `json-rest-schema`
-   - export is draft-07, mode-aware, and transport-facing rather than a clone of every in-process coercion path
-   - custom transport export hooks are supported through `handler.toJsonSchema`
-   - unknown external metadata keys are ignored; custom registered validators without a transport hook fail loudly
-
-4. [done] Extend json-rest-schema field metadata only where it remains schema-level meaning.
-   Deliverables:
-   - preserve useful passive metadata such as nullability, defaults, precision, scale, unsigned, enum values, and temporal precision
-   Notes:
-   - made `enum` a first-class built-in rule in `json-rest-schema`
-   - added canonical passive metadata support for `temporalPrecision`
-   - transport export now preserves passive schema metadata under `x-json-rest-schema.metadata`
-   - passive metadata remains schema-owned metadata; no DB-specific runtime logic was added to `json-rest-schema`
-
-5. [done] Add repository/storage mapping in json-rest-api.
-   Deliverables:
-   - API field to DB column mapping
-   - virtual/non-column fields
-   - write serializers where persistence formatting is required
-   Notes:
-   - added `field.storage = { column, serialize }` as the native repository/storage surface in `json-rest-api`
-   - storage metadata is compiled once into `schemaInfo.storageInfo`
-   - Knex writes now translate logical attributes to storage columns through the compiled mapping
-   - table creation and migration generation now respect storage column overrides
-   - JSON:API transformers translate storage rows back to logical field names before response shaping
-   - storage adapters now own row/id/select translation used by Knex callers, reducing repeated mapping helpers
-   - runtime row access now uses the same logical field path for `id` as for other fields: `getFieldValue(record, 'id')`
-   - include handling and relationship links now use logical record IDs consistently, including custom-id resources
-   - direct DB helper surfaces now support logical `id` fields mapped to custom storage columns without duplicate-column drift
-   - verified with dedicated storage-mapping tests and the full `json-rest-api` suite
-
-6. [done] Add DB introspection snapshot support in json-rest-api.
-   Deliverables:
-   - column type and shape introspection
-   - enum/set values
-   - indexes
-   - foreign keys
-   - check constraints
-   - precision/scale/temporal precision
-   Notes:
-   - added `introspectKnexTableSnapshot(knex, { tableName, idColumn })` as the native normalized snapshot helper
-   - snapshot support is dialect-aware for `better-sqlite3`/SQLite and `mysql2`
-   - SQLite captures named check constraints and foreign keys from table SQL, while indexes/columns/foreign-key actions come from PRAGMA metadata
-   - `RestApiKnexPlugin` now exposes `api.resources.{resource}.introspectKnexTableSnapshot()` for table-backed resources
-   - verified with real SQLite snapshot tests, MySQL raw-double snapshot tests, and a public scope-method test
-
-7. [done] Add deterministic migration generation and diffing in json-rest-api.
-   Deliverables:
-   - create and alter support
-   - named/composite indexes
-   - FK rules
-   - enum/set handling
-   - defaults and safety warnings for destructive changes
-   Notes:
-   - `dbTablesOperations` now normalizes table-level metadata (`indexes`, `foreignKeys`, `checkConstraints`) and uses one contract for live table creation, create-migration generation, and snapshot diffing
-   - field-level `unique` / `index` / `references` are compiled into deterministic named indexes and foreign keys instead of relying on ad hoc column builder side effects
-   - added `generateKnexMigrationDiff(tableName, currentSnapshot, schema, options)` returning `{ migration, warnings, plan }`
-   - additive diff generation supports columns, indexes, and foreign keys; destructive or unsupported changes stay explicit as warnings
-   - `RestApiKnexPlugin` now exposes `generateKnexMigration()` and `generateKnexMigrationDiff()` on table-backed scopes and threads table-level metadata through `schemaInfo`
-
-8. [done] Preserve and clarify the pass-through searchSchema contract in json-rest-api.
-   Deliverables:
-   - searchSchema validates allowed filter keys and normalizes values only
-   - filter meaning remains backend-owned and server-defined
-   - arbitrary public filter keys are supported when the backend maps them intentionally
-   - regression coverage for shared merge/validation behavior and invalid filter keys
-   Notes:
-   - did not introduce a generic filter DSL
-   - documented that searchSchema keys are public filter names, not a portable operator language
-   - verified that alias filters (`oneOf`) and custom backend filters (`applyFilter`) work as intended in the Knex path, where their execution semantics are owned by the backend
-
-9. [done] Add declarative autofiltering/scoping in json-rest-api.
-   Deliverables:
-   - public
-   - workspace
-   - user
-   - workspace_user
-   Notes:
-   - replaced the purpose-specific multihome surface with a generic `AutoFilterPlugin`
-   - resources now declare `autofilter` presets or inline filters, while the plugin resolves scope values from configured resolver functions
-   - `workspace`, `user`, `workspace_user`, and `public` are example presets, not built-in auth meanings
-   - the plugin scopes collection queries and single-record lookups, stamps scoped fields on `POST`/`PUT`, and rejects inconsistent scoped updates
-   - scoped `belongsTo` relationships are supported by injecting or validating JSON:API relationship identifiers before write validation
-   - auth/admission semantics remain out of scope for `json-rest-api`; core keeps `checkPermissions` hooks as a neutral extension point only
-   - shipped `AccessPlugin` was removed before this point so scoping does not inherit built-in auth assumptions
-
-10. [done] Add SQL-backed query projections and stable list behavior in json-rest-api.
-    Deliverables:
-    - SQL-backed output-only query fields via an optional plugin
-    - sparse-field and include support for declared query fields
-    - deterministic ordered-list / cursor behavior with stable tie-breakers
-    Notes:
-    - added an optional `QueryProjectionsPlugin` that compiles resource-level `queryFields`, separate from normal schema fields and response-layer computed fields
-    - query fields are selected by default, can be requested in sparse fieldsets, and are stripped from write input
-    - query fields can drive sorting and cursor pagination; `id` is appended as a deterministic tie-breaker
-    - query-field selection is supported on the Knex path and the AnyAPI Knex path, including included resources
-    - documented as a separate advanced guide so it does not blur with response-layer computed fields
-
-11. [done] Add a Fastify-oriented connector layer in json-rest-api.
-    Deliverables:
-    - consume exported schema before request handling
-    - no jskit-ai compatibility shim
-    Notes:
-    - added `FastifyPlugin` as a transport connector that registers REST routes on a supplied Fastify instance
-    - resource `POST`/`PUT`/`PATCH` routes now attach transport-facing JSON Schemas built from `schema.toJsonSchema({ mode })`, wrapped in the JSON:API document envelope
-    - connector-level transport schemas strip output-only/computed fields and direct `belongsTo` foreign keys from `data.attributes`, matching the existing transport write contract
-    - connector registers an `application/vnd.api+json` parser and rejects unsupported write content types before route handlers run
-    - no jskit-ai compatibility shim or duplicate hand-written field validation layer was added
-
-12. [pending] Remove the corresponding DB/schema/normalization ownership from jskit-ai and verify parity.
-    Deliverables:
-    - no jskit-ai-owned DB/schema normalization path remains for the migrated surface
-    - verification notes for anything still intentionally left outside scope
-
-ADDENDUM ITEMS TO POINT 12:
-
-* This is the reason we did points 1 to 11 (!).
-* Needs to be done with a lot of care, since it's harder than it looks 
-* You MUST read AGENTS.md in jskit-ai VERY carefully, follow it VERY carefully. One of the previous attempts (4 failed in total) was unsuccessful because this step was missed. That file has important instructions on how to avoid repeated helpers and a pointer to important function maps
-* There must be NOTHING left of the in house DB stuff. jskit is only a user of what json-rest-api offers.
-* NO SHIMS. NO COMPATIBILITY LAYERS. NO LAYERS AT ALL. NO RUNTIMES.
-* In an earlier attempt, you made a runtime that mimiked the repository's functions. NO. Repository functions will use json-rest-api's functions to do what they need to do
-* A repository should be simple. It can have helper functions, but if it has a LOT of helper functions, there is a problem -- interrupt and let's talk. This happened in the workspace repository
-* Multi homing is to be done with the generic filtering option of json-rest-api
-* Take a LOT of care with the definiton of the resource file. Do NOT keep the old Type + Normalisation flow. That is GONE. We now have json-rest-schema, and that's what you need to use. One of the 4 failed attempts failed because you were stubborn about reusing that paradigm
-* The resource file (which is what is used by the server, AND by the client) needs to be clean, and contain the right information (schemas, relationships, etc). It's a DATA ONLY file.
-* The goal is to devoid jskit of any db logic/layering/
-