json-rest-api 1.0.21 → 1.0.22

package/audit/subsystems/plugins-file.md

@@ -0,0 +1,53 @@
+# Subsystem: plugins-file (Pass 1)
+
+## Scope
+- File handling plugin + storage backends (`local-storage`, `s3-storage`) + transport detector integration.
+
+## Purpose
+- Detect multipart/file uploads, validate schema-declared file constraints, upload via configured storage backend, and merge resulting URLs into write payloads.
+
+## Key entry points
+- `plugins/core/file-handling-plugin.js`
+- `plugins/storage/local-storage.js`
+- `plugins/storage/s3-storage.js`
+- `plugins/core/connectors/lib/{busboy-detector,formidable-detector}.js`
+
+## Core data flow
+- Walkthrough (POST with file):
+  - [Verified][C5] `beforeProcessing` hook detects file-capable scope, runs detector registry, validates mime/size, uploads, then mutates `params.inputRecord.data.attributes` with stored value(s). Evidence: `file-handling-plugin.js:112-275`, `280-292`.
+
+## Hook/control flow
+- [Verified][C4] Detectors are transport-registered and protocol-agnostic via `api.rest.registerFileDetector`.
+
+## Failure modes
+- [Verified][C4] Upload failure throws validation error and attempts temp-file cleanup; cleanup failures only logged. Evidence: `file-handling-plugin.js:224-248`, `266-273`.
+- [Inferred][C3] No built-in transactional compensation for already-uploaded files if DB write later fails; rollback of storage side effects depends on custom hooks/backends.
+
+## Strengths
+- [Verified][C4] Schema-driven file field detection avoids hardcoded upload logic.
+- [Verified][C4] Required file checks handled both no-detector and missing-field cases.
+
+## Risks
+- R-FILE-001:
+  - [Inferred][C3] Potential orphaned files on downstream write rollback.
+- R-FILE-002:
+  - [Unknown][C2] Large concurrent upload pressure not benchmarked.
+
+## Missing tests
+- [Inferred][C3] Add test that simulates upload success + DB failure to verify cleanup/compensation strategy.
+
+## Explicit unknowns
+- [Unknown][C2] Backend-specific consistency guarantees for S3/local under partial failures.
+
+## Pass-1 confidence
+- Overall: **C3-C4**.
+
+## Evidence links
+- `plugins/core/file-handling-plugin.js`
+- `plugins/storage/local-storage.js`
+- `plugins/storage/s3-storage.js`
+- `docs/mini-guides/file-uploads-complete.md`
+
+## Pass-2 cross-review status
+- Reconciled in [pass2-cross-review.md](/home/merc/Development/current/json-rest-api/audit/subsystems/pass2-cross-review.md).
+- Final assertion/confidence values in this report are considered pass-2 normalized.

package/audit/subsystems/plugins-multihome.md

@@ -0,0 +1,50 @@
+# Subsystem: plugins-multihome (Pass 1)
+
+## Scope
+- Multi-tenant extraction/filter/enforcement plugin.
+
+## Purpose
+- Enforce tenant isolation by attaching tenant context, filtering queries, setting tenant field on writes, and checking ownership on single-resource operations.
+
+## Key entry points
+- `plugins/core/rest-api-multihome-plugin.js`
+
+## Core data flow
+- Walkthrough (tenant-scoped query + write):
+  - [Verified][C5] `transport:request` extracts tenant ID into `context.auth.multihome_id`. Evidence: `rest-api-multihome-plugin.js:65-84`.
+  - [Verified][C5] `knexQueryFiltering` adds tenant where clause for eligible scopes. Evidence: `rest-api-multihome-plugin.js:112-179`.
+  - [Verified][C4] `beforeSchemaValidate` enforces/sets tenant field on writes. Evidence: `rest-api-multihome-plugin.js:182-228`.
+
+## Hook/control flow
+- [Verified][C4] `checkPermissions` hook validates tenant ownership of `minimalRecord` for existing-resource operations. Evidence: `rest-api-multihome-plugin.js:232-287`.
+
+## Failure modes
+- [Verified][C4] For tenant mismatch, plugin throws generic errors with custom codes (`REST_API_RESOURCE` / `REST_API_FORBIDDEN`) instead of typed `RestApiResourceError`; transport mapping may produce non-uniform envelope semantics. Evidence: `rest-api-multihome-plugin.js:274-284`, `express-plugin.js:236-266`.
+
+## Strengths
+- [Verified][C5] Defense-in-depth: both query-time filtering and single-record permission checks.
+- [Verified][C4] Explicit handling for excluded resources and missing-tenant policy toggles.
+
+## Risks
+- R-MULTI-001:
+  - [Inferred][C3] Error typing inconsistency can alter client-observed semantics across connectors.
+- R-MULTI-002:
+  - [Unknown][C2] Dependence on extractor correctness (subdomain/header) may cause tenant mis-assignment if upstream proxy headers are untrusted.
+
+## Missing tests
+- [Inferred][C3] Add negative tests for malformed forwarded host/header extraction and spoofing scenarios.
+
+## Explicit unknowns
+- [Unknown][C2] Full trust-boundary hardening at edge proxy layer is not inspectable from this repo alone.
+
+## Pass-1 confidence
+- Overall: **C4**.
+
+## Evidence links
+- `plugins/core/rest-api-multihome-plugin.js`
+- `tests/multihome.test.js`
+- `audit/evidence/tests/access-multitenancy-test-signals.txt`
+
+## Pass-2 cross-review status
+- Reconciled in [pass2-cross-review.md](/home/merc/Development/current/json-rest-api/audit/subsystems/pass2-cross-review.md).
+- Final assertion/confidence values in this report are considered pass-2 normalized.

package/audit/subsystems/plugins-positioning.md

@@ -0,0 +1,54 @@
+# Subsystem: plugins-positioning (Pass 1)
+
+## Scope
+- Fractional positioning plugin and helper math.
+
+## Purpose
+- Compute and persist sortable position values with optional group filters and `beforeId` insertion semantics.
+
+## Key entry points
+- `plugins/core/rest-api-positioning-plugin.js`
+- `plugins/core/lib/fractional-positioning.js`
+
+## Core data flow
+- Walkthrough (PATCH with `beforeId`):
+  - [Verified][C4] `beforeSchemaValidate` strips `beforeId` and managed `position` from client payload, storing intent in context. Evidence: `rest-api-positioning-plugin.js:257-323`.
+  - [Verified][C4] `beforeDataCallPatch` computes target position using grouped query and writes computed position into `context.inputRecord.data.attributes` before storage update. Evidence: `rest-api-positioning-plugin.js:339-345`, `347-545`.
+
+## Hook/control flow
+- [Verified][C4] Uses method-specific `beforeDataCall*` hooks, plus optional query-sort default hook (`beforeQuery`). Evidence: `rest-api-positioning-plugin.js:326-345`, `574-589`.
+
+## Failure modes
+- [Inferred][C3] Concurrent reordering operations can still race without explicit row locking; final ordering correctness depends on DB isolation and retry strategy.
+- [Verified][C3] Index creation best-effort errors are downgraded to warnings, which can hide performance regressions. Evidence: `rest-api-positioning-plugin.js:251-253`.
+
+## Strengths
+- [Verified][C4] Adapter-aware filter-to-column translation and scoped grouping logic.
+- [Verified][C4] Prevents direct client overwrite of managed position field.
+
+## Risks
+- R-POS-001:
+  - [Inferred][C3] Concurrency ordering race risk under heavy writes.
+- R-POS-002:
+  - [Inferred][C3] Silent index-create failure can degrade query/update performance.
+
+## Missing tests
+- [Inferred][C3] Add concurrent reorder tests (same group, multiple writers).
+- [Unknown][C2] No observed tests for index-creation fallback path.
+
+## Explicit unknowns
+- [Unknown][C2] Long-term rebalance behavior once `rebalanceThreshold` is exceeded.
+
+## Pass-1 confidence
+- Overall: **C3-C4**.
+
+## Evidence links
+- `plugins/core/rest-api-positioning-plugin.js`
+- `plugins/core/lib/fractional-positioning.js`
+- `tests/positioning.test.js`
+- `tests/positioning-advanced.test.js`
+- `tests/positioning-extended.test.js`
+
+## Pass-2 cross-review status
+- Reconciled in [pass2-cross-review.md](/home/merc/Development/current/json-rest-api/audit/subsystems/pass2-cross-review.md).
+- Final assertion/confidence values in this report are considered pass-2 normalized.

package/audit/subsystems/plugins-socketio.md

@@ -0,0 +1,50 @@
+# Subsystem: plugins-socketio (Pass 1)
+
+## Scope
+- Socket.IO realtime subscription and broadcast plugin.
+
+## Purpose
+- Allow clients to subscribe to resource updates with filter validation and emit events after successful write lifecycles.
+
+## Key entry points
+- `plugins/core/socketio-plugin.js`
+
+## Core data flow
+- Walkthrough (write -> broadcast):
+  - [Verified][C4] `finish` hook queues broadcasts when a transaction exists; `afterCommit` flushes; `afterRollback` drops pending messages. Evidence: `socketio-plugin.js:576-619`.
+  - [Verified][C4] Subscription registration validates resource existence, query permission, filter schema, include/fields shape, then joins room. Evidence: `socketio-plugin.js:161-288`.
+
+## Hook/control flow
+- [Verified][C4] Broadcast filtering uses `searchSchemaStructure` and `matchesFilters` against minimal record context.
+
+## Failure modes
+- [Inferred][C3] If `minimalRecord` lacks attributes needed for subscription filters, updates may be under/over-delivered depending on filter type.
+- [Unknown][C2] Backpressure and memory behavior under very high subscription fanout not verified.
+
+## Strengths
+- [Verified][C4] Commit-aware broadcast deferral avoids notifying on rolled-back mutations.
+- [Verified][C4] Optional Redis adapter support for horizontal scaling.
+
+## Risks
+- R-SOCKET-001:
+  - [Inferred][C3] Filter evaluation fidelity depends on minimal record shape.
+- R-SOCKET-002:
+  - [Unknown][C2] Throughput limits and queue growth under load.
+
+## Missing tests
+- [Inferred][C3] Add explicit tests for afterRollback suppression and post-commit-only delivery with failing writes.
+- [Unknown][C2] Load/fanout tests absent.
+
+## Explicit unknowns
+- [Unknown][C2] Ordering guarantees across clustered deployments with Redis adapter under network partitions.
+
+## Pass-1 confidence
+- Overall: **C3-C4**.
+
+## Evidence links
+- `plugins/core/socketio-plugin.js`
+- `tests/socketio.test.js`
+
+## Pass-2 cross-review status
+- Reconciled in [pass2-cross-review.md](/home/merc/Development/current/json-rest-api/audit/subsystems/pass2-cross-review.md).
+- Final assertion/confidence values in this report are considered pass-2 normalized.

package/audit/subsystems/query-engine.md

@@ -0,0 +1,61 @@
+# Subsystem: query-engine (Pass 1)
+
+## Scope
+- Query parsing, filtering, sorting, pagination, include loading, and response shaping.
+- Exclusion: anyapi-only query branches.
+
+## Purpose
+- Implement JSON:API-style collection/single retrieval with filters, sparse fieldsets, includes, and pagination.
+
+## Key entry points
+- `plugins/core/rest-api-plugin-methods/query.js`
+- `plugins/core/lib/querying-writing/payload-validators.js`
+- `plugins/core/lib/querying/knex-query-helpers.js`
+- `plugins/core/lib/querying/knex-relationship-includes.js`
+- `plugins/core/lib/querying-writing/knex-field-helpers.js`
+- `plugins/core/lib/querying-writing/connectors-query-parser.js`
+
+## Core data flow
+- Walkthrough (query + include):
+  - [Verified][C5] Query payload parsed/validated, then permission gate runs before `helpers.dataQuery`. Evidence: `query.js:75-137`.
+  - [Verified][C5] `dataQuery` builds field selection, runs filter hooks, applies sort/pagination, then relationship identifiers/includes and JSON:API transformation. Evidence: `rest-api-knex-plugin.js:448-880`.
+  - [Verified][C4] Include engine batches by relationship type and parent IDs (not per-record) for standard hasMany/manyToMany identifier loading. Evidence: `knex-relationship-includes.js:595-625`, `1876-1903`, `1925-1927`.
+
+## Hook/control flow
+- [Verified][C4] Filtering hook chain order is explicit: polymorphic -> cross-table -> basic. Evidence: `rest-api-knex-plugin.js:152-163` and hook helper docs in `knex-query-helpers.js`.
+
+## Failure modes
+- [Verified][C4] Unknown sparse fields throw hard errors; hidden fields are suppressed even if requested. Evidence: `knex-field-helpers.js:203`, `209-214`.
+- [Inferred][C3] Include recursion still risks high query volume at deep nesting despite per-layer batching; worst-case behavior depends on relationship fanout. Evidence: `knex-relationship-includes.js:1598-1727`.
+- [Inferred][C3] Query string generation may produce duplicated delimiters (`&&`) in some link paths (doc examples show this pattern), creating cosmetic interoperability risk.
+
+## Strengths
+- [Verified][C5] Strong validation on include depth, sort whitelist, page param types.
+- [Verified][C4] `idProperty` handling is deeply integrated in selection, includes, and pagination cursor construction.
+
+## Risks
+- R-QUERY-001:
+  - [Inferred][C3] Potential performance cliff on deep includes with high cardinality.
+- R-QUERY-002:
+  - [Unknown][C2] Window-strategy fallback behavior across all supported SQL dialects not yet runtime-confirmed.
+
+## Missing tests
+- [Inferred][C3] Expand high-cardinality include tests with explicit query-count assertions.
+- [Verified][C4] Some multi-field cursor cases are skipped in suite (`pagination-cursor-multifield.test.js` has skipped tests).
+
+## Explicit unknowns
+- [Unknown][C2] Practical N+1 envelope under production dataset shape.
+
+## Pass-1 confidence
+- Overall: **C4** on correctness path; **C2-C3** on large-scale performance bounds.
+
+## Evidence links
+- `plugins/core/rest-api-plugin-methods/query.js`
+- `plugins/core/lib/querying/knex-relationship-includes.js`
+- `plugins/core/lib/querying-writing/knex-field-helpers.js`
+- `audit/evidence/code/query-include-signals.txt`
+- `audit/evidence/tests/query-include-test-signals.txt`
+
+## Pass-2 cross-review status
+- Reconciled in [pass2-cross-review.md](/home/merc/Development/current/json-rest-api/audit/subsystems/pass2-cross-review.md).
+- Final assertion/confidence values in this report are considered pass-2 normalized.

package/audit/subsystems/relationships.md

@@ -0,0 +1,55 @@
+# Subsystem: relationships (Pass 1)
+
+## Scope
+- Relationship read/write methods and relationship processing helpers.
+- Exclusion: anyapi-specific link backends.
+
+## Purpose
+- Keep relationship semantics consistent across `POST/PUT/PATCH` resource writes and explicit relationship endpoints.
+
+## Key entry points
+- `plugins/core/rest-api-plugin-methods/{get-related,get-relationship,post-relationship,patch-relationship,delete-relationship}.js`
+- `plugins/core/lib/writing/{relationship-processor,many-to-many-manipulations}.js`
+
+## Core data flow
+- Walkthrough (PATCH relationship endpoint):
+  - [Verified][C4] `patchRelationship` proxies to scope `patch` with synthesized `inputRecord.data.relationships`. Evidence: `patch-relationship.js:27-42`.
+  - [Verified][C5] Resource-level `patch` then executes standard validation, permission checks, storage update, and relationship synchronization. Evidence: `patch.js:58-165`.
+
+## Hook/control flow
+- [Verified][C4] Relationship endpoint methods run `checkPermissions` and endpoint-specific hook suffixes before mutation. Evidence: `post-relationship.js:49-52`, `delete-relationship.js:47-49`, `patch-relationship.js:24-25`.
+
+## Failure modes
+- [Verified][C5] `patch-relationship` error handling defect (undefined symbol path) can break rollback hook execution on failures. Evidence: `patch-relationship.js:52-54`, `common.js:210-215`.
+- [Inferred][C3] `getRelated` many-to-many fallback may degrade to multiple GET calls when included resources are absent, increasing latency with many IDs. Evidence: `get-related.js:306-341`.
+
+## Strengths
+- [Verified][C5] Relationship processor cleanly separates belongsTo updates, polymorphic writes, and many-to-many pivot sync list generation.
+- [Verified][C4] Many-to-many sync logic preserves existing pivot records where possible (`updateManyToManyRelationship`).
+
+## Risks
+- R-REL-001:
+  - [Verified][C5] Relationship PATCH error-path reliability defect.
+- R-REL-002:
+  - [Inferred][C3] High cardinality many-to-many read paths can incur extra per-id lookups in fallback branch.
+
+## Missing tests
+- [Inferred][C4] Add explicit failure-path tests for relationship endpoint transaction rollback + hook behavior.
+- [Unknown][C2] Add stress test for many-to-many fallback retrieval volume.
+
+## Explicit unknowns
+- [Unknown][C2] Exact behavior parity between relationship endpoints and base methods under all plugin combinations is not fully runtime-proven yet.
+
+## Pass-1 confidence
+- Overall: **C4**.
+
+## Evidence links
+- `plugins/core/rest-api-plugin-methods/patch-relationship.js`
+- `plugins/core/rest-api-plugin-methods/get-related.js`
+- `plugins/core/lib/writing/relationship-processor.js`
+- `plugins/core/lib/writing/many-to-many-manipulations.js`
+- `audit/evidence/tests/relationship-test-signals.txt`
+
+## Pass-2 cross-review status
+- Reconciled in [pass2-cross-review.md](/home/merc/Development/current/json-rest-api/audit/subsystems/pass2-cross-review.md).
+- Final assertion/confidence values in this report are considered pass-2 normalized.

package/audit/subsystems/rest-orchestration.md

@@ -0,0 +1,66 @@
+# Subsystem: rest-orchestration (Pass 1)
+
+## Scope
+- Core REST method orchestration and shared method helpers.
+- Exclusion: anyapi-specific branches are not evaluated.
+
+## Purpose
+- Normalize request context, enforce payload/permission contract ordering, route to storage helpers, and apply hook lifecycle around CRUD and relationship operations.
+
+## Key entry points
+- `plugins/core/rest-api-plugin.js`
+- `plugins/core/rest-api-plugin-methods/{query,get,post,put,patch,delete}.js`
+- `plugins/core/rest-api-plugin-methods/{post-relationship,patch-relationship,delete-relationship,get-related,get-relationship}.js`
+- `plugins/core/rest-api-plugin-methods/common.js`
+- `plugins/core/rest-api-plugin-hooks/{register-scope-routes,register-relationship-routes}.js`
+
+## Core data flow
+- Walkthrough (write path: POST/PUT/PATCH):
+  - [Verified][C5] `setupCommonRequest` establishes `context.inputRecord`, schema shortcuts, transaction, type/ID consistency checks. Evidence: `common.js:54-197`.
+  - [Verified][C5] Write methods call validation and relationship access checks before `helpers.dataPost/dataPut/dataPatch`. Evidence: `post.js:53-121`, `put.js:57-194`, `patch.js:58-134`.
+  - [Verified][C5] Permission gate executes before irreversible storage operation (`scope.checkPermissions` before `beforeDataCall` + data helper). Evidence: `post.js:97-121`, `put.js:170-194`, `patch.js:102-134`, `delete.js:67-84`.
+
+## Hook/control flow
+- [Verified][C5] Standardized lifecycle hooks exist for pre-processing, schema validation, data call, finish, commit/rollback handling. Evidence: `common.js:285-410`, methods throughout.
+- [Verified][C4] Relationship routes map explicitly to dedicated methods and reuse shared checks. Evidence: `register-relationship-routes.js:33-68`.
+
+## Failure modes
+- [Verified][C5] **Concrete defect**: `patch-relationship` catch block calls `handleWriteMethodError` and `log` without import/parameter wiring, likely causing `ReferenceError` and masking original failures.
+  - Evidence: `patch-relationship.js:52-54`; compare correct pattern in `post-relationship.js:1-3,15,107-109` and `delete-relationship.js:1-3,14,114-116`.
+- [Inferred][C4] Error-path rollback semantics in `patch-relationship` are unreliable because missing `runHooks` argument to `handleWriteMethodError` would break `afterRollback` hook even if symbol existed. Evidence: `common.js:210-215`, `patch-relationship.js:53`.
+
+## Strengths
+- [Verified][C5] Clear centralization of cross-cutting behavior in `common.js`.
+- [Verified][C4] Consistent permission placement before storage write calls.
+- [Verified][C4] Route registration is explicit and auditable.
+
+## Risks
+- R-REST-001:
+  - [Verified][C5] Relationship PATCH error-path defect (undefined symbol path).
+  - Impact: high (error handling reliability, rollback hooks).
+- R-REST-002:
+  - [Inferred][C3] Route handler/context shaping differences between scope routes and relationship routes can create subtle transport-level behavior drift.
+  - Evidence: `register-scope-routes.js:10-53` vs `register-relationship-routes.js:10-30`.
+
+## Missing tests
+- [Inferred][C4] Add targeted failure-path tests for `PATCH /relationships/*` with forced storage errors to verify rollback + error envelope.
+- [Unknown][C2] No direct test evidence yet for all hook lifecycle transitions under nested transaction reuse.
+
+## Explicit unknowns
+- [Unknown][C2] Whether plugin hooks depend on currently missing rollback hook in relationship PATCH path.
+
+## Pass-1 confidence
+- Overall: **C4**.
+
+## Evidence links
+- `plugins/core/rest-api-plugin.js`
+- `plugins/core/rest-api-plugin-methods/common.js`
+- `plugins/core/rest-api-plugin-methods/patch-relationship.js`
+- `plugins/core/rest-api-plugin-methods/post-relationship.js`
+- `plugins/core/rest-api-plugin-methods/delete-relationship.js`
+- `plugins/core/rest-api-plugin-hooks/register-scope-routes.js`
+- `plugins/core/rest-api-plugin-hooks/register-relationship-routes.js`
+
+## Pass-2 cross-review status
+- Reconciled in [pass2-cross-review.md](/home/merc/Development/current/json-rest-api/audit/subsystems/pass2-cross-review.md).
+- Final assertion/confidence values in this report are considered pass-2 normalized.

package/audit/subsystems/schema-core.md

@@ -0,0 +1,64 @@
+# Subsystem: schema-core (Pass 1)
+
+## Scope
+- Repositories: `json-rest-schema` + schema compilation path in `json-rest-api`.
+- Exclusion: anyapi internals are out of scope.
+
+## Purpose
+- Compile and enforce schema contracts (types, validators, relationships, getter/setter/computed metadata) before runtime read/write paths.
+
+## Key entry points
+- `json-rest-schema/src/index.js`
+- `json-rest-schema/src/Schema.js`
+- `json-rest-schema/src/CorePlugin.js`
+- `plugins/core/lib/querying-writing/compile-schemas.js`
+- `plugins/core/rest-api-plugin-hooks/compile-resource-schemas.js`
+
+## Core data flow
+- Walkthrough (resource registration path):
+  - [Verified][C5] `scope:added -> compileResourceSchemas -> compileSchemas` builds `scope.vars.schemaInfo` once per scope. Evidence: `plugins/core/rest-api-plugin.js:117-120`, `plugins/core/rest-api-plugin-hooks/compile-resource-schemas.js:3-6`, `plugins/core/lib/querying-writing/compile-schemas.js:124-335`.
+  - [Verified][C5] `compileSchemas` separates computed fields, enriches belongsTo types, builds validation schema and search schema, then caches `schemaInfo` with `schemaStructure`, `searchSchemaStructure`, `schemaRelationships`, `idProperty`, getters/setters metadata. Evidence: `compile-schemas.js:132-335`.
+  - [Verified][C5] `Schema.validate()` in `json-rest-schema` enforces unknown-field errors, per-field cast/validator pipeline, and default/null completion behavior for full validation. Evidence: `/home/merc/Development/current/json-rest-schema/src/Schema.js:177-225`.
+
+## Hook/control flow
+- [Verified][C4] Schema enrichment hooks are first-class (`schema:enrich`, `searchSchema:enrich`), allowing plugin extensions before schema instances are finalized. Evidence: `compile-schemas.js:183-190`, `217-224`.
+- [Verified][C4] Relationship definitions for runtime include both explicit `scopeOptions.relationships` and schema-derived belongsTo metadata checks. Evidence: `compile-schemas.js:231-244`.
+
+## Failure modes
+- [Verified][C5] Invalid schema config fails fast at scope-add time (missing `as` on belongsTo, invalid getter/setter dependencies, invalid computed definition). Evidence: `compile-schemas.js:142-148`, `237-242`, `260-315`.
+- [Inferred][C3] Global mutable registries in `json-rest-schema` (`globalTypes`, `globalValidators`) can create cross-test/plugin coupling if mutated dynamically after schema creation order changes. Evidence: `/home/merc/Development/current/json-rest-schema/src/index.js:13-43`, `64-74`.
+
+## Strengths
+- [Verified][C5] Clear separation between schema compile phase and request execution phase.
+- [Verified][C4] Search schema auto-generation and index intent (`ensureSearchFieldsAreIndexed`) are centralized.
+- [Verified][C4] Getter/setter dependency ordering provides deterministic execution semantics.
+
+## Risks
+- R-SCHEMA-001:
+  - [Inferred][C3] Global registry mutation risk in long-lived process/plugin hot-load scenarios.
+  - Impact: medium; can create non-local behavior shifts.
+  - Evidence: `/home/merc/Development/current/json-rest-schema/src/index.js:13-43`.
+- R-SCHEMA-002:
+  - [Unknown][C2] No direct benchmark evidence yet for schema validation overhead under high-field payloads.
+
+## Missing tests
+- [Unknown][C2] No explicit concurrency/ordering tests found for dynamic plugin registration in `json-rest-schema`.
+- [Inferred][C3] Add tests for `schema:enrich` + `searchSchema:enrich` conflict resolution ordering.
+
+## Explicit unknowns
+- [Unknown][C2] Runtime memory growth profile with many scopes and large computed dependency graphs.
+- [Unknown][C2] Backward-compatibility expectations for runtime mutation of global validators/types.
+
+## Pass-1 confidence
+- Overall: **C4 (high)** for correctness of structural claims, **C2-C3** for performance/operational unknowns.
+
+## Evidence links
+- `audit/evidence/code/import-hotspots-non-anyapi.txt`
+- `plugins/core/lib/querying-writing/compile-schemas.js`
+- `/home/merc/Development/current/json-rest-schema/src/Schema.js`
+- `/home/merc/Development/current/json-rest-schema/src/index.js`
+- `/home/merc/Development/current/json-rest-schema/src/CorePlugin.js`
+
+## Pass-2 cross-review status
+- Reconciled in [pass2-cross-review.md](/home/merc/Development/current/json-rest-api/audit/subsystems/pass2-cross-review.md).
+- Final assertion/confidence values in this report are considered pass-2 normalized.

package/audit/subsystems/storage-knex.md

@@ -0,0 +1,57 @@
+# Subsystem: storage-knex (Pass 1)
+
+## Scope
+- Knex-backed storage helpers and storage adapter abstraction.
+- Exclusion: anyapi-specific storage paths.
+
+## Purpose
+- Provide database CRUD primitives used by REST methods, including adapter translation hooks and query construction support.
+
+## Key entry points
+- `plugins/core/rest-api-knex-plugin.js`
+- `plugins/core/lib/storage/storage-adapter.js`
+- `plugins/core/lib/querying-writing/{database-value-normalizers,compile-schemas,knex-json-api-transformers}.js`
+- `plugins/core/lib/querying-writing/{field-utils,schema-helpers,database-capabilities,knex-field-helpers}.js`
+
+## Core data flow
+- Walkthrough (PATCH):
+  - [Verified][C5] Method layer provides transaction in `context.db`; storage helper checks existence then applies merged attributes/relationship FK updates and strips non-db fields. Evidence: `patch.js:116-134`, `rest-api-knex-plugin.js:1030-1078`.
+  - [Verified][C5] Adapter abstraction translates columns/values and applies base resource scope when canonical adapter is used. Evidence: `storage-adapter.js:25-49`, `68-147`.
+
+## Hook/control flow
+- [Verified][C4] Query filtering hooks are invoked by dataQuery/countQuery via `context.knexQuery` handoff to hook chain. Evidence: `rest-api-knex-plugin.js:491-507`, `787-804`.
+- [Verified][C4] `helpers.newTransaction` is exposed and used by method layer for managed transactions. Evidence: `rest-api-knex-plugin.js:213-215`, `common.js:126-130`.
+
+## Failure modes
+- [Verified][C4] `dataPut` performs create/update branching and duplicate existence checks; race between existence check and write is possible without higher isolation/constraints. Evidence: `rest-api-knex-plugin.js:974-1007`.
+- [Inferred][C3] Error semantics depend heavily on upstream method orchestration; storage helpers do not independently enforce permission ordering.
+
+## Strengths
+- [Verified][C5] Clear separation between orchestration and storage implementation.
+- [Verified][C4] `idProperty` handling is consistently aliased/selectable across get/query/write helpers.
+
+## Risks
+- R-STORAGE-001:
+  - [Inferred][C3] Possible TOCTOU edge on update/delete existence checks under concurrent writers.
+- R-STORAGE-002:
+  - [Unknown][C2] No explicit retry/backoff strategy for transient DB faults.
+
+## Missing tests
+- [Inferred][C3] Add concurrency tests for PUT/PATCH/DELETE conflict windows.
+- [Unknown][C2] Add tests for adapter translation edge cases across all relationship filter forms.
+
+## Explicit unknowns
+- [Unknown][C2] Real DB behavior variance (SQLite vs Postgres vs MySQL) for returning/locking paths is not yet runtime-verified.
+
+## Pass-1 confidence
+- Overall: **C4** for structure/call order; **C2-C3** for concurrency behavior.
+
+## Evidence links
+- `plugins/core/rest-api-knex-plugin.js`
+- `plugins/core/lib/storage/storage-adapter.js`
+- `audit/evidence/code/transaction-signals.txt`
+- `audit/evidence/code/idproperty-signals.txt`
+
+## Pass-2 cross-review status
+- Reconciled in [pass2-cross-review.md](/home/merc/Development/current/json-rest-api/audit/subsystems/pass2-cross-review.md).
+- Final assertion/confidence values in this report are considered pass-2 normalized.

package/audit/subsystems/tests.md

@@ -0,0 +1,48 @@
+# Subsystem: tests (Pass 1)
+
+## Scope
+- Test suite structure and invariant coverage signal (excluding anyapi tests).
+
+## Purpose
+- Provide confidence on correctness/regression resistance for critical behaviors.
+
+## Inventory signal
+- [Verified][C5] Non-anyapi test files: 30 (`tests/*.test.js` excluding anyapi). Evidence: `audit/evidence/tests/test-suite-list-non-anyapi.txt`.
+- [Verified][C5] Skipped tests: 10, all in multi-field cursor pagination suite. Evidence: `audit/evidence/tests/skipped-tests.txt`.
+
+## Coverage strengths
+- [Verified][C4] Relationship semantics have dedicated suites (`relationships`, `relationship-endpoints`, custom idProperty relationship tests).
+- [Verified][C4] Plugin-focused suites exist for access, CORS, multihome, positioning, socketio, bulk.
+- [Verified][C4] Include depth and sparse-field interactions are tested.
+
+## Coverage gaps
+- [Inferred][C4] Critical cursor edge cases are deferred via skipped tests, lowering confidence for pagination invariants under complex sort tuples.
+- [Inferred][C3] Limited explicit failure-path assertions for rollback hooks (especially relationship PATCH defect path) found in static scan.
+- [Unknown][C2] Query-count/N+1 guard tests are not evident from static test names/signals.
+
+## Risks
+- R-TEST-001:
+  - [Verified][C4] Skipped pagination tests leave known edge space unverified.
+- R-TEST-002:
+  - [Inferred][C3] Runtime invariants may be indirectly covered but not explicitly mapped per invariant ID.
+
+## Missing tests
+- [Inferred][C4] Add targeted regression for `patch-relationship` error path (undefined handler/log).
+- [Inferred][C3] Add explicit N+1/query-count budget tests for representative include graphs.
+- [Inferred][C3] Add rollback + afterRollback hook assertions across all relationship endpoint mutations.
+
+## Explicit unknowns
+- [Unknown][C2] Current CI timing/flakiness profile (not observed yet; runtime run pending).
+
+## Pass-1 confidence
+- Overall: **C3-C4** (good breadth, specific deep-edge gaps).
+
+## Evidence links
+- `audit/evidence/tests/test-suite-list-non-anyapi.txt`
+- `audit/evidence/tests/skipped-tests.txt`
+- `audit/evidence/tests/relationship-test-signals.txt`
+- `audit/evidence/tests/query-include-test-signals.txt`
+
+## Pass-2 cross-review status
+- Reconciled in [pass2-cross-review.md](/home/merc/Development/current/json-rest-api/audit/subsystems/pass2-cross-review.md).
+- Final assertion/confidence values in this report are considered pass-2 normalized.

package/audit/subsystems/transport-express.md

@@ -0,0 +1,55 @@
+# Subsystem: transport-express (Pass 1)
+
+## Scope
+- Express connector and request helpers.
+- Exclusion: anyapi paths.
+
+## Purpose
+- Convert HTTP traffic to scope method calls, enforce transport-level media rules, and map internal errors to JSON:API-style HTTP responses.
+
+## Key entry points
+- `plugins/core/connectors/express-plugin.js`
+- `plugins/core/connectors/lib/request-helpers.js`
+- `plugins/core/connectors/lib/{busboy-detector,formidable-detector}.js`
+
+## Core data flow
+- Walkthrough (GET request):
+  - [Verified][C5] Middleware builds request context (`createContext`), runs `transport:request`, then route handler dispatches to scope method handler with parsed query. Evidence: `express-plugin.js:116-177`, `295-308`, `register-scope-routes.js:31-53`.
+  - [Verified][C5] Response status rules are method-sensitive (POST 201/204, DELETE 204, PUT/PATCH 204 on empty body). Evidence: `express-plugin.js:310-326`.
+
+## Hook/control flow
+- [Verified][C5] Transport hooks are run on both success and error paths (`transport:request`, `transport:response`). Evidence: `express-plugin.js:151`, `268-279`, `333-341`.
+- [Verified][C4] Wildcard route path uses `router.use` with method gate for match-all behavior (used by CORS OPTIONS). Evidence: `express-plugin.js:393-414`.
+
+## Failure modes
+- [Verified][C4] Non-library errors default to 500 with direct `error.message` in response; may expose internal messages in production unless upstream sanitizes. Evidence: `express-plugin.js:210-217`.
+- [Inferred][C3] Inconsistent error coding from plugins (e.g., custom `error.code`) can degrade status mapping determinism because only known codes map to specific status branches. Evidence: `express-plugin.js:219-266`.
+
+## Strengths
+- [Verified][C5] Clear error mapping for `REST_API_VALIDATION`, `REST_API_RESOURCE`, `REST_API_PAYLOAD`.
+- [Verified][C4] Content-type gate for write methods and structured 404 handling under mount path.
+
+## Risks
+- R-TRANSPORT-001:
+  - [Inferred][C3] Potential information leakage via raw `error.message` on unexpected errors.
+- R-TRANSPORT-002:
+  - [Unknown][C2] Behavior under malformed large payloads near `requestSizeLimit` not yet runtime-validated.
+
+## Missing tests
+- [Inferred][C3] Add tests for unknown exception mapping to verify production-safe envelope strategy.
+- [Unknown][C2] Add tests for transport hook failure isolation (`transport:response` throwing).
+
+## Explicit unknowns
+- [Unknown][C2] Reverse proxy edge-case behavior for URL prefix calculation under mixed forwarded headers.
+
+## Pass-1 confidence
+- Overall: **C4**.
+
+## Evidence links
+- `plugins/core/connectors/express-plugin.js`
+- `plugins/core/connectors/lib/request-helpers.js`
+- `audit/evidence/code/error-model-signals.txt`
+
+## Pass-2 cross-review status
+- Reconciled in [pass2-cross-review.md](/home/merc/Development/current/json-rest-api/audit/subsystems/pass2-cross-review.md).
+- Final assertion/confidence values in this report are considered pass-2 normalized.

package/audit/traces/trace-read-get.md

@@ -0,0 +1,22 @@
+# Trace: Read Get
+
+## Scope
+- Non-anyapi path only.
+
+## Scenario
+- Retrieve single resource by ID (`books.get`).
+
+## Input shape
+- Method call: `api.resources.books.get({ id, simplified: false })`
+
+## Call path
+1. Route dispatch to `scope.get` from `register-scope-routes` ([register-scope-routes.js](/home/merc/Development/current/json-rest-api/plugins/core/rest-api-plugin-hooks/register-scope-routes.js)).
+2. `get.js` performs `dataGetMinimal` + `scope.checkPermissions` then `helpers.dataGet` ([get.js](/home/merc/Development/current/json-rest-api/plugins/core/rest-api-plugin-methods/get.js)).
+3. Storage helper resolves idProperty-aware query and transforms output ([rest-api-knex-plugin.js](/home/merc/Development/current/json-rest-api/plugins/core/rest-api-knex-plugin.js)).
+
+## Runtime evidence
+- `npm test` confirms single get path:
+  - `ok 1 - should retrieve a single resource` at `audit/evidence/tests/npm-test-json-rest-api.log:5480`
+
+## Result
+- [Verified][C4] Non-anyapi get flow is operational under test.