first commit

docs/foundation/bitpacker/bitpacker-validation/src/register-schemas/register-schemas.md

@@ -0,0 +1,67 @@
+# Register Schemas — `@suaveplan/bitpacker-validation`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Idempotent integration with `@suaveplan/schema-registry` for the `@suaveplan/bitpacker-validation` package. Exposes `registerBitPackerValidationSchemas(registry)` which converts the package's five public boundary schemas into JSON-Schema form and registers them under `bitpacker:@suaveplan/bitpacker-validation` at version 1. Re-registration on the same registry is a no-op.
+
+The five schemas covered are: `safetyLimits` (the `SafetyChecker` constructor bundle), `safetyPerformanceOptions` (selective skip flags), `schemaSafetyLimits` (per-schema embedded `_safety` block), `bitPackerValidatorOptions` (the `BitPackerValidator` constructor bundle), and `validateSchemaOptions` (the `validateSchema` per-call bundle). Together they describe every external configuration shape the package accepts.
+
+## Features
+
+- `BITPACKER_VALIDATION_SUBJECT` constant — `"bitpacker:@suaveplan/bitpacker-validation"`
+- `BITPACKER_VALIDATION_SCHEMA_VERSION` constant — `1`
+- `registerBitPackerValidationSchemas(registry)` — idempotent registration
+- Five-key payload covering safety limits, performance options, embedded limits, validator options, and per-call options
+
+## Usage: Basic Example
+
+```ts
+import { createRegistry } from "@suaveplan/schema-registry";
+import {
+    BITPACKER_VALIDATION_SUBJECT,
+    registerBitPackerValidationSchemas,
+} from "@suaveplan/bitpacker-validation/register-schemas";
+
+const registry = createRegistry();
+registerBitPackerValidationSchemas(registry);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { createRegistry, SchemaRegistry } from "@suaveplan/schema-registry";
+import { registerBitPackerSchemas } from "@suaveplan/bitpacker/register-schemas";
+import { registerBitPackerValidationSchemas } from "@suaveplan/bitpacker-validation/register-schemas";
+
+const registry = createRegistry();
+registerBitPackerSchemas(registry);
+registerBitPackerValidationSchemas(registry);
+
+const payload = registry.getLatest("bitpacker:@suaveplan/bitpacker-validation")
+    .schema as Record<string, unknown>;
+// payload.safetyLimits, payload.bitPackerValidatorOptions, …
+```
+
+## API Reference
+
+### `BITPACKER_VALIDATION_SUBJECT: "bitpacker:@suaveplan/bitpacker-validation"`
+
+Const string. The exact subject under which this package's schemas are registered.
+
+### `BITPACKER_VALIDATION_SCHEMA_VERSION: 1`
+
+Const number. The version under which the schemas are registered.
+
+### `registerBitPackerValidationSchemas(registry: SchemaRegistry): void`
+
+Idempotent registration. Returns without writing if the subject is already present.
+
+## Implementation Notes
+
+- **Five-key payload.** Each key corresponds to one of the package's exported schemas. Downstream consumers can pick the schema by name.
+- **`unrepresentable: "any"`.** Required because some schemas use `z.custom` for class instances and callables — the JSON-Schema converter cannot represent custom types and would otherwise throw.
+- **Idempotent via `listSubjects()` membership check.** Same pattern as the rest of the bitpacker family.