@classytic/repo-core 0.31.0 → 0.32.0

package/dist/update/compile.d.mts

@@ -1,5 +1,4 @@
 import { UpdateSpec } from "./types.mjs";
-//#region src/update/compile.d.ts
 /**
  * Compile an `UpdateSpec` to a Mongo operator record.
  *
@@ -41,5 +40,4 @@ interface SqlUpdatePlan {
   readonly insertDefaults: Readonly<Record<string, unknown>>;
 }
 declare function compileUpdateSpecToSql(spec: UpdateSpec): SqlUpdatePlan;
-//#endregion
 export { SqlUpdatePlan, compileUpdateSpecToMongo, compileUpdateSpecToSql };

package/dist/update/compile.mjs

@@ -1,4 +1,4 @@
-//#region src/update/compile.ts
+// src/update/compile.ts
 /**
 * Compile an `UpdateSpec` to a Mongo operator record.
 *
@@ -29,5 +29,4 @@ function compileUpdateSpecToSql(spec) {
 		insertDefaults: Object.freeze({ ...spec.setOnInsert ?? {} })
 	});
 }
-//#endregion
 export { compileUpdateSpecToMongo, compileUpdateSpecToSql };

package/dist/update/guard.d.mts

@@ -1,5 +1,4 @@
 import { UpdateSpec } from "./types.mjs";
-//#region src/update/guard.d.ts
 /**
  * True when `value` is an `UpdateSpec` — i.e. the portable, compile-to-native
  * form.
@@ -15,5 +14,4 @@ declare function isUpdateSpec(value: unknown): value is UpdateSpec;
  * pipelines.
  */
 declare function isUpdatePipeline(value: unknown): value is Record<string, unknown>[];
-//#endregion
 export { isUpdatePipeline, isUpdateSpec };

package/dist/update/guard.mjs

@@ -1,4 +1,4 @@
-//#region src/update/guard.ts
+// src/update/guard.ts
 /**
 * True when `value` is an `UpdateSpec` — i.e. the portable, compile-to-native
 * form.
@@ -20,5 +20,4 @@ function isUpdateSpec(value) {
 function isUpdatePipeline(value) {
 	return Array.isArray(value);
 }
-//#endregion
 export { isUpdatePipeline, isUpdateSpec };

package/dist/update/types.d.mts

@@ -1,4 +1,3 @@
-//#region src/update/types.d.ts
 /**
  * Update IR — driver-agnostic mutation spec.
  *
@@ -58,5 +57,4 @@ interface UpdateSpec {
  * escape hatch (e.g. outbox's `$ifNull` to preserve `firstFailedAt`).
  */
 type UpdateInput = UpdateSpec | Record<string, unknown> | Record<string, unknown>[];
-//#endregion
 export { UpdateInput, UpdateSpec };

package/dist/usage/index.d.mts

@@ -1,4 +1,3 @@
-//#region src/usage/index.d.ts
 /**
  * Usage-counter contract for the @classytic ecosystem.
  *
@@ -73,5 +72,4 @@ declare function usagePeriod(date?: Date): string;
 declare function createMemoryUsageStore(): UsageStore & {
   clear(): void;
 };
-//#endregion
 export { UsageBucket, UsageStore, createMemoryUsageStore, usagePeriod };

package/dist/usage/index.mjs

@@ -1,4 +1,4 @@
-//#region src/usage/index.ts
+// src/usage/index.ts
 /**
 * Canonical period key for a date — calendar month, UTC: `2026-07`.
 * Monthly is the billing-native granularity.
@@ -32,5 +32,4 @@ function createMemoryUsageStore() {
 		}
 	};
 }
-//#endregion
 export { createMemoryUsageStore, usagePeriod };

package/llms.txt

@@ -0,0 +1,29 @@
+# @classytic/repo-core
+
+Contract layer under mongokit, sqlitekit and arc. No root import: use subpaths (@classytic/repo-core/pagination, /errors, ...). Skill: skills/repo-core/SKILL.md.
+
+| Need | Use |
+|---|---|
+| List response shape on the wire | `toCanonicalList` from `@classytic/repo-core/pagination` |
+| Page result types | `OffsetPaginationResult`, `KeysetPaginationResult`, `PaginatedResult` |
+| Error JSON body | `toErrorContract`, `ErrorContract` from `@classytic/repo-core/errors` |
+| Throw an HTTP error | `createError`, `isHttpError` |
+| Error code vocabulary | `ERROR_CODES`, `ARC_ERROR_CODES`, `CURSOR_ERROR_CODES` |
+| Duplicate key to 409 | `toDuplicateKeyHttpError` |
+| Query string to filter, sort, page | `parseUrl` from `@classytic/repo-core/query-parser` |
+| Filters and sort to URL params (client side) | `formatQuery`, `stringifyQuery` from `@classytic/repo-core/query-parser` |
+| Portable filters | `and`, `eq`, `in_`, `between` from `@classytic/repo-core/filter` |
+| Merge tenant scope into a filter | `buildTenantScope`, `mergeScope` |
+| Portable update spec | `update`, `incFields` from `@classytic/repo-core/update` |
+| Keyset cursors | `encodeCursor`, `decodeCursor`, `mergeKeysetPages` |
+| Run once per idempotency key | `runIdempotent`, `fingerprintRequest` |
+| Retry transient errors | `withRetry`, `retryingTransaction` |
+| Batch lookups (N+1) | `createBatchLoader` |
+| Read-only repository | `asReadOnlyRepo` |
+| Hook priorities and event names | `HOOK_PRIORITY`, `HOOK_EVENTS` |
+| Cache adapter contract | `CacheAdapter`, `createMemoryCacheAdapter` |
+| Purge step for tenant cleanup | `definePurgeStep` |
+| Cross-kit conformance tests | `runStandardRepoConformance` from `@classytic/repo-core/testing` |
+
+Details: references/contracts.md (envelopes, errors, grammar), references/kit-authoring.md (kits, plugins, conformance).
+Mongo implementation: skill mongokit.

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.31.0",
-  "description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design \u2014 no plugins ship here; each kit owns its own.",
+  "version": "0.32.0",
+  "description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design — no plugins ship here; each kit owns its own.",
   "type": "module",
   "sideEffects": false,
   "files": [
     "dist",
+    "skills",
+    "llms.txt",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -161,20 +163,29 @@
     "format": "biome format src tests --write",
     "check": "biome ci src tests --diagnostic-level=error",
     "knip": "knip",
+    "check:skills": "node scripts/check-skills.mjs",
     "push": "classytic-push",
-    "prepublishOnly": "npm run check && npm run build && npm run typecheck && npm test",
+    "prepublishOnly": "npm run check && npm run build && npm run check:skills && npm run typecheck && npm test",
     "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
     "release": "npm run push -- main && npm run release:tag && npm publish",
     "publish:dry": "npm publish --dry-run --access public",
     "publish:npm": "npm publish --access public"
   },
+  "peerDependencies": {
+    "fast-check": "^4.10.2"
+  },
+  "peerDependenciesMeta": {
+    "fast-check": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
-    "@biomejs/biome": "^2.4.12",
+    "@biomejs/biome": "^2.5.15",
     "@classytic/dev-tools": "^0.2.0",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^4.1.4",
-    "fast-check": "^4.7.0",
+    "fast-check": "^4.10.2",
     "knip": "^6.3.0",
     "publint": "^0.3.18",
     "tsdown": "^0.22.14",

package/skills/repo-core/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: repo-core
+description: Driver-agnostic repository contracts shared by mongokit, sqlitekit and arc - list envelopes, ErrorContract and error codes, Filter IR, URL query grammar, keyset cursors, idempotency claims, hooks, cache adapter. Use when typing a list response, mapping errors, parsing query strings, or writing a kit or plugin. Triggers - repo-core, ErrorContract, toCanonicalList, parseUrl, Filter IR.
+metadata:
+  minVersion: "0.31.1"
+  package: "@classytic/repo-core"
+  note: "No root entry. Import from the exact subpath."
+---
+
+# @classytic/repo-core
+
+The contract layer under every kit. Zero runtime dependencies, tree-shakeable, subpath imports only (`@classytic/repo-core/<subpath>`; there is no root import). App code uses it for envelopes, errors, filters and query parsing; kit authors also use `repository`, `hooks`, `testing`.
+
+## Do not hand-roll
+
+| Need | Use |
+|---|---|
+| Wire list shape (`{ method, data, ... }` or `{ data }`) | `toCanonicalList`, `isPaginatedResult` (`/pagination`) |
+| Page result types | `OffsetPaginationResult`, `KeysetPaginationResult`, `PaginatedResult` |
+| Error JSON body | `toErrorContract` -> `ErrorContract` (`/errors`) |
+| Throwable HTTP error | `createError`, `isHttpError` |
+| Status to code | `statusToErrorCode`, `ERROR_CODES` |
+| Duplicate key to 409 | `toDuplicateKeyHttpError`, `DUPLICATE_KEY_DETAIL_CODE` |
+| Version conflict | `VersionConflictError`, `isVersionConflictError` |
+| Query string to filter, sort, page, select | `parseUrl` (`/query-parser`) |
+| Filters and sort to URL params (inverse of `parseUrl`) | `formatQuery`, `stringifyQuery` (`/query-parser`) |
+| Escape or vet user regex | `escapeRegex`, `assessRegex` |
+| Portable filters | `and`, `or`, `eq`, `in_`, `between`, `contains` (`/filter`) |
+| Evaluate a filter in memory | `matchFilter`, `asPredicate` |
+| Tenant filter merge | `buildTenantScope`, `mergeScope` |
+| Portable updates | `update`, `incFields`, `setFields` (`/update`) |
+| Cursor encode, decode, sort checks | `encodeCursor`, `decodeCursor`, `validateKeysetSort` |
+| One keyset page over several sources | `mergeKeysetPages` |
+| Run once per idempotency key | `runIdempotent`, `fingerprintRequest` (`/idempotency`) |
+| Retry transient failures | `withRetry`, `retryingTransaction` (`/repository`) |
+| Batch N+1 lookups | `createBatchLoader` (`/loader`) |
+| Seal a repo you do not own the writes of | `asReadOnlyRepo` |
+| Cache adapter and test double | `CacheAdapter`, `createMemoryCacheAdapter` (`/cache`) |
+| Hook order and event names | `HOOK_PRIORITY`, `HOOK_EVENTS` (`/hooks`) |
+| Publish repo domain events | `registerRepositoryEvents` (`/events`) |
+| Tenant purge as a cleanup step | `definePurgeStep` (`/cleanup`) |
+| Stable content hash | `contentHash`, `stableStringify` (`/hash`) |
+| Tenant config | `resolveTenantConfig` (`/tenant`) |
+| Standard Schema (zod, valibot) check | `validateStandardSchema` (`/schema`) |
+| Lock or usage test doubles | `createMemoryLockAdapter`, `createMemoryUsageStore` |
+| Prove a kit conforms | `runStandardRepoConformance` (`/testing`) |
+
+## Golden path
+
+List route (kit result to wire):
+
+```ts
+import { toCanonicalList } from '@classytic/repo-core/pagination';
+import { parseUrl } from '@classytic/repo-core/query-parser';
+
+const q = parseUrl(req.query, { allowedFilterFields: ['status', 'createdAt'], fieldTypes: { createdAt: 'date' }, maxLimit: 200 });
+const { filter, ...rest } = q;
+reply.send(toCanonicalList(await repo.getAll({ ...rest, filters: filter })));   // paged results keep `method`; a bare array becomes { data }
+```
+
+Errors (throw `HttpError`, serialize once at the edge):
+
+```ts
+import { createError, toErrorContract } from '@classytic/repo-core/errors';
+const err = createError(409, 'Already paid');
+err.code = 'order.already_paid';
+reply.code(409).send(toErrorContract(err));   // { code, message, status, details?, meta? }
+```
+
+Filter IR (same on every kit; native filters also work):
+
+```ts
+import { and, eq, in_, between } from '@classytic/repo-core/filter';
+await repo.findAll!(and(eq('status', 'open'), in_('kind', ['a', 'b']), between('total', 10, 100)));
+```
+
+Idempotent side effect:
+
+```ts
+import { fingerprintRequest, runIdempotent } from '@classytic/repo-core/idempotency';
+const run = await runIdempotent({ store, identity: { operation: 'charge', key, scope: { orgId } },
+  requestFingerprint: fingerprintRequest(body), execute: async () => charge(body) });
+// run.outcome: 'executed' | 'replayed' | 'in_flight' (retryAfterMs) | 'exhausted'
+```
+
+## Gotchas
+
+- Envelope rows are in `data` (never `docs`). Narrow with `result.method`.
+- `parseUrl` returns `filter` (Filter IR) but `getAll` reads `filters`: rename the key. mongokit's `QueryParser` already returns `filters`.
+- `ErrorContract.code` has three families: `ERROR_CODES` (`conflict`), `ARC_ERROR_CODES` (`arc.conflict`), domain strings (`order.already_paid`). Switch on code, not message.
+- `createError(status, message)` takes two arguments; set `code`, `meta`, `validationErrors` on the result.
+- `CURSOR_ERROR_CODES`: `repo.cursor.invalid` and `repo.cursor.scope_mismatch` (400); restart paging on both.
+- `before` and `mode` are reserved query params (not filters).
+- `update({})` with no mutation throws; `undefined` values in `set` are dropped (use `unset` to clear).
+- Duplicate-key values are PII: `exposeValues` is opt-in.
+- A kit declares what it supports in `capabilities`; feature-detect instead of try and catch.
+
+## Never
+
+- Re-declare `HttpError`, `ErrorContract` or the page types in an app or kit.
+- Import a root `@classytic/repo-core` (does not exist) or `dist/` paths.
+- Parse `req.query` by hand for list routes.
+
+## References
+
+- `references/contracts.md`: read for envelope shapes, error codes, query grammar operators, cursor behavior.
+- `references/kit-authoring.md`: read when writing a kit, plugin, conformance harness, hooks, cache or purge step.
+- Kit behavior: skill `mongokit`. HTTP wiring: skill `arc`.

package/skills/repo-core/references/contracts.md

@@ -0,0 +1,69 @@
+# Contracts: envelopes, errors, query grammar
+
+## Page envelopes (`/pagination`)
+
+```
+offset:    { method: 'offset',    data, page, limit, total, pages, hasNext, hasPrev }
+keyset:    { method: 'keyset',    data, limit, hasMore, next, prev?, hasPrev?, end? }
+aggregate: { method: 'aggregate', data, ... }   // page or keyset shaped, from aggregatePaginate
+bare:      { data }                              // BareListResult, from a non-paged list
+```
+
+`OffsetPaginationResult<T, TExtra>` and `KeysetPaginationResult<T, TExtra>` take a typed extras bag (a kit may add `warning`). `PaginatedResult<T>` is the
+wire union; discriminate with `'method' in res`. `prev`, `hasPrev`, `end` are optional: absent means the kit does not answer, not "none".
+`end` is the cursor at the page's last row even when `next` is null (resume a change feed from it).
+
+`toCanonicalList(x)` copies a paged result or wraps a bare array. Call it once at the HTTP edge; clients type responses as `PaginatedResult<T>`.
+
+Cursors: `encodeCursor`, `decodeCursor`, `validateCursorSort`, `validateCursorVersion` (kit authors). Offset math: `calculateSkip`, `calculateTotalPages`,
+`validateLimit`, `validatePage`. `mergeKeysetPages(sources, sort, { limit, cursor, secret })` returns one page with ONE composite cursor bound to the
+source names, scopes and sort (HMAC-signed when `secret` is set); it returns `{ docs, next, hasNext }`.
+
+## Errors (`/errors`)
+
+Throwable `HttpError`: `status`, optional `code`, `meta`, `validationErrors[]` (`validator`, `error`, `path`), `duplicate` (`fields`, `values?`).
+Wire `ErrorContract`: `{ code, message, status?, details?: ErrorDetail[], correlationId?, meta? }`, flat, no `{ error: {} }` wrapper.
+`toErrorContract(err)` maps `validationErrors` and `duplicate.fields` to `details` (`path`, `code`, `message`); `status` without `code` derives the code
+through `statusToErrorCode`.
+
+| Family | Examples | Source |
+|---|---|---|
+| cross-cutting | `validation_error`, `not_found`, `conflict`, `unauthorized`, `forbidden`, `rate_limited`, `idempotency_conflict`, `precondition_failed`, `internal_error`, `service_unavailable`, `timeout` | `ERROR_CODES` |
+| arc | `arc.conflict`, `arc.validation_error`, `arc.idempotency_key_reused`, `arc.org.access_denied`, `arc.pagination.invalid_mode` | `ARC_ERROR_CODES` |
+| reasons | `ORG_CONTEXT_REQUIRED`, `MIXED_UPDATE_SHAPE`, `ALL_FIELDS_STRIPPED` | `ARC_REASON_CODES` |
+| cursors | `repo.cursor.invalid`, `repo.cursor.scope_mismatch` | `CURSOR_ERROR_CODES` |
+| domain | `order.already_paid` | your package, dotted lowercase |
+
+A duplicate key can surface as `conflict` (thrown by a kit) or `arc.conflict` (raised by the HTTP layer); clients treat both as a 409. Validate a
+contract body in tests with `errorContractSchema` and `errorDetailSchema`. Hosts that accept unmapped library errors (auth providers, framework 404s) normalize
+them into the contract at the edge.
+
+`conservativeMongoIsDuplicateKey` and `conservativeMongoIsTransientConflict` classify raw driver errors when you have no kit repository to ask.
+
+## Query grammar (`/query-parser`)
+
+`parseUrl(input, options)` accepts `URLSearchParams`, an iterable of pairs, or a record. Result: `{ filter, limit, sort?, select?, populate?, page?, after?, search? }`.
+
+| URL | Meaning |
+|---|---|
+| `status=active` | equals; repeated keys mean in |
+| `age[gte]=18&age[lt]=65` | range |
+| `role[in]=a,b`, `role[nin]=a` | membership |
+| `name[contains]=jo`, `[startsWith]`, `[endsWith]`, `[ieq]` | literal, case-insensitive text |
+| `price[between]=10,100` | inclusive range |
+| `deletedAt[exists]=false` | null or missing |
+| `title[regex]=^a&title[options]=i` | regex, checked for ReDoS |
+| `sort=-createdAt,name`, `select=a,b,-c` | sort and projection |
+| `page=2&limit=50`, `after=<cursor>`, `before=<cursor>`, `mode=keyset` | paging (reserved) |
+
+Client side, `formatQuery({ filters: [{ field, op?, value }], sort, page, limit, search })` emits exactly these params (`stringifyQuery` gives the string). `between: [from, to]` is sent as `gte` + `lte`; `in`/`nin` take arrays; empty values are omitted; unrepresentable values throw `QueryGrammarError`.
+
+Options: `allowedFilterFields`, `allowedOperators`, `allowedSortFields`, `fieldTypes` (`boolean`, `date`, `number`...), `defaultLimit` (20), `maxLimit` (1000),
+`maxSearchLength` (200), `maxRegexLength`. Every allow-list refuses with a `QueryGrammarError` (400, `INVALID_QUERY_INPUT`); nothing is silently dropped, nothing truncated.
+Repeated control params are refused. Lower-level readers: `readFilterClauses`, `readPageRequest`, `readSort`, `readSelect`, `clausesToFilter`.
+
+## Filter IR (`/filter`)
+
+Builders: `eq ne gt gte lt lte in_ nin exists contains startsWith endsWith iEq like regex between isNull isNotNull and or not anyOf noneOf raw TRUE FALSE`.
+`and()` with no children is `TRUE`. `recordToFilter(record)` converts a flat record. `walkFilter`, `mapFilter`, `collectFields` traverse; `coerceFilterDates` turns ISO strings
+into dates. `matchFilter(filter, row)` evaluates in memory (policy checks, tests). `raw(sql, params)` is SQL-kit only.

package/skills/repo-core/references/kit-authoring.md

@@ -0,0 +1,75 @@
+# Writing a kit, plugin or conformance harness
+
+## Repository base (`/repository`)
+
+A kit extends `RepositoryBase` and implements `MinimalRepo` (`getAll`, `getById`, `create`, `update`, `delete`) plus as much of `StandardRepo` as the backend
+supports. Every operation goes: `_buildContext` (runs `before:*` hooks and policy plugins) -> native call -> `_emitAfter`. Options on `RepositoryBaseOptions`:
+`name`, `plugins`, `hooks` (`sync` or `async`), `pluginOrderChecks` (`warn`, `throw`, `off`), `schema`, `updateSchema` (any Standard Schema validator), `events`.
+Validation runs at `HOOK_PRIORITY.VALIDATION`; event publishing never fails the operation (failures go to `error:events`).
+
+Do not narrow an existing contract type: additive optional fields are safe, renames and new required fields are breaking. Method signatures use `unknown` for
+sessions and `readonly string[]` for arrays so kits stay assignable.
+
+`StandardRepo` extras (optional unless noted): `claim`, `claimVersion` (required CAS), `applyTransition`, `findOneAndUpdate`, `getOne`, `getByIds`, `findAll`, `count`, `exists`,
+`distinct`, `getOrCreate`, `createMany`, `updateMany`, `deleteMany`, `bulkUpsert`, `purgeByField`, `purgeByFilter`, `archiveByFilter`, `aggregate`, `lookupPopulate`,
+`isDuplicateKeyError`, `isTransientConflictError`. Declare what works in `capabilities` (`transactions`, `upsert`, `aggregate`, `aggregateOps`, `readOnly`, `arrayOperators`...).
+
+## Plugins and hooks (`/hooks`)
+
+```ts
+import { HOOK_EVENTS, HOOK_PRIORITY } from '@classytic/repo-core/hooks';
+import type { Plugin } from '@classytic/repo-core/repository';
+
+export const stampOrg = (orgId: string): Plugin => ({
+  name: 'stamp-org',
+  apply(repo) {
+    repo.on(HOOK_EVENTS.BEFORE_CREATE, (ctx) => { ctx.data = { ...ctx.data, organizationId: orgId }; }, { priority: HOOK_PRIORITY.POLICY });
+  },
+});
+```
+
+Priorities: `POLICY` 100, `VALIDATION` 150, `CACHE` 200, `OBSERVABILITY` 300, `DEFAULT` 500 (lower runs first). Events per op: `before:`, `after:`, `error:` for create, update, delete,
+getById, getAll, createMany, updateMany, deleteMany, findOneAndUpdate, restore. Listening to an event a kit never emits is a silent no-op.
+`PLUGIN_ORDER_CONSTRAINTS`: soft-delete before batch-operations; multi-tenant before cache and before soft-delete. `validatePluginOrder` enforces them.
+
+Domain events: pass `events: { transport, source }` and every mutating op publishes `<resource>.<verb>`. Do not also enable arc's auto events for the same resource (double publish).
+
+## Cache (`/cache`)
+
+`CacheAdapter` is `{ get, set(key, value, ttlSeconds?), delete, clear?, addToSet?, increment? }`. `cachePlugin` options: `adapter`, `enabled`, `invalidating`, `defaults`
+(`staleTime`, `gcTime`, `swr`, `tags`, `bypass`), `perOpDefaults`, `prefix`, `autoTagsFromScope`, `jitter`. `withTimeout(adapter, ...)` bounds a slow cache so it degrades to a miss.
+`createMemoryCacheAdapter` and `createTtlMemo` are in-process helpers.
+
+## Idempotency (`/idempotency`)
+
+`IdempotencyClaimStore` is the persistence contract (kits ship one: mongokit `createIdempotencyStore`, `createMemoryIdempotencyStore` in repo-core). `runIdempotent` drives
+claim, execute, complete with leases (`leaseMs`, default 30 s), checkpoints (`attempt.checkpoint(progress)`) and replay. A reused key with a different body fails
+`FINGERPRINT_MISMATCH`. `classifyFailure` returns `terminal` (store the failure), `transient` (release for retry) or `ambiguous` (keep the lease). `IdempotencyError.code` is one of
+`FINGERPRINT_MISMATCH`, `MISSING_REPLAY`, `LEASE_LOST`, `ALREADY_TERMINAL`, `INVALID_CLAIM`, `UNFINGERPRINTABLE`.
+
+## Other subpaths
+
+| Subpath | Content |
+|---|---|
+| `/lock` | `LockAdapter`, `createMemoryLockAdapter` |
+| `/usage` | `UsageStore`, `usagePeriod`, `createMemoryUsageStore` |
+| `/sync` | change-log and command-stream store contracts |
+| `/loader` | `createBatchLoader({ batch, maxBatchSize, requireAllResolved })` |
+| `/cleanup` | `definePurgeStep` (fail-closed scope, preview, chunked purge, proof of absence) |
+| `/adapter` | `DataAdapter` contract, `asRepositoryLike`, `isRepository` for arc |
+| `/schema` | `SchemaGenerator`, `validateStandardSchema`, field rule helpers |
+| `/operations` | `CORE_OP_REGISTRY`, `describe`, `listOperations` |
+| `/aggregate` | aggregation cursor and normalization helpers |
+| `/lookup` | `LookupSpec`, `LookupPopulateResult` types |
+| `/context` | `RepositoryContext` type |
+
+## Conformance (`/testing`, needs the optional peer `fast-check` for property suites)
+
+```ts
+import { runStandardRepoConformance } from '@classytic/repo-core/testing';
+runStandardRepoConformance({ name: 'my-kit', idField: 'id', features, setup, makeDoc });   // setup() returns { repo, cleanup }
+```
+
+Gated groups (aggregate ops, bulkUpsert, readModel, mergeKeyset) run only when the kit declares the capability. Other suites: `runLockAdapterConformance`, `runUsageStoreContract`,
+`runPurgeConformance`, `runChangeLogStoreConformance`, `runQueryGrammarConformance`. Use `harness.makeDoc` for fixtures and `harness.idField` for ids; never inline a kit shape.
+An unsupported op must throw a clear error naming the kit and the alternative, never approximate silently.