@kindgi/schema 0.0.0-bootstrap.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Kindgi Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,53 @@
-# @kindgi/schema
+# `@kindgi/schema`
 
-A placeholder. Releases come from https://github.com/kindgi/kindgi-sdk.
+JSON Schema utilities for Kindgi. Loads specs, provides Ajv-based validation, extracts schema versions, converts Zod v4 schemas to JSON Schema, and serializes JSON canonically for signing. Consumers use this to validate incoming data against the wire contracts in [`@kindgi/specs`](../specs/).
+
+## Purpose
+
+Turn the JSON Schemas that live in `@kindgi/specs/*.schema.json` into runtime-usable validators, with cross-schema `$ref` resolution handled correctly (two-pass registration), typed `Result` errors, and version extraction that respects our `$id` + `$comment` convention.
+
+## Exports
+
+- **`createSpecRegistry(schemas)`** — build a registry from already-parsed schema documents (synchronous, no filesystem access).
+- **`loadSpecRegistry(dir)`** — build a registry by reading every `*.schema.json` from a directory (async).
+- **`SpecRegistry`** — the resulting interface:
+  - `validate<T>(id, data)` — validate data against a schema by `$id`, returning `Result<T, SchemaError>`.
+  - `getSchema(id)` — retrieve the raw parsed schema JSON.
+  - `ids()` — list every registered `$id`.
+- **`compileInlineSchema(schema)`** — compile one anonymous JSON Schema (no `$id`, no cross-schema `$ref`) into a `CompiledInlineSchema` whose `validate<T>(data)` returns `Result<T, ValidationErrorLike>`.
+- **`versionOf(schema)`** — extract `{ major, semver }` from a schema's `$id` and `$comment`.
+- **Zod authoring helpers** — `AnySchema` (a JSON Schema object or a Zod v4 schema), `isZodSchema`, `isJsonSchemaObject`, `schemaKindOf`, and `toJSONSchema` / `toJSONSchemaSync` (with `loadZodConverter` / `loadZodConverterSync`), which convert Zod to JSON Schema through Zod's native `z.toJSONSchema()`. `zod` is an optional peer dependency: it is imported only when a Zod schema is passed, and a missing or failed conversion is an `invalid-zod-conversion` error, not a throw.
+- **`canonicalize(value)`** — deterministic JSON serialization (sorted keys, `undefined` omitted, no whitespace), a subset of RFC 8785 used for signing.
+- **`SchemaError`** — typed discriminated union covering load / parse / compile / not-found / validation / Zod-conversion errors.
+
+## Example
+
+```ts
+import { loadSpecRegistry, versionOf } from '@kindgi/schema';
+import type { Flow } from '@kindgi/flow';
+
+const registry = await loadSpecRegistry('./specs');
+if (registry.kind === 'err') {
+  console.error(registry.error);
+  process.exit(1);
+}
+
+const incoming = JSON.parse(await readFile('user-flow.json', 'utf-8'));
+const validated = registry.value.validate<Flow>(
+  'https://kindgi.com/schemas/v1/flow.schema.json',
+  incoming,
+);
+
+if (validated.kind === 'ok') {
+  runGraph(validated.value);
+} else {
+  console.error(validated.error.code, validated.error.message);
+}
+```
+
+## Non-goals
+
+- **No Zod on the wire, and no JSON Schema → Zod conversion.** Zod is an authoring convenience: schemas are converted one way, Zod → JSON Schema, and every schema that is registered or exchanged is JSON Schema.
+- **No schema migration helpers.** Every schema is at its first major version, so there is nothing to migrate between.
+- **No TypeScript type generation.** Callers define TypeScript types that match schema shapes by hand, or author with Zod and derive them with `z.infer`.
+- **No custom Ajv extensions.** Uses stock Ajv Draft 2020-12 + `ajv-formats`, with no custom keywords.

package/SPEC.md

@@ -0,0 +1,120 @@
+# `@kindgi/schema` — Specification
+
+*Deep spec for humans. Complements the JSON Schemas in `@kindgi/specs` (the wire contracts) and `packages/types/SPEC.md` (the foundational types).*
+
+## Purpose in the OS
+
+Every artifact in Kindgi has its shape defined by a JSON Schema in `@kindgi/specs/*.schema.json`. Those schemas are authoritative — they cross the boundary to Python runtimes, third-party MCP tools, community adapters. But TypeScript code inside the OS needs to *use* those schemas at runtime: validate incoming data, look up schemas by `$id`, parse schema versions.
+
+`@kindgi/schema` is the layer that turns the JSON files into runtime-usable objects. It sits below every kernel/memory/tools/agents package.
+
+## Design principles
+
+1. **Ajv is the validation engine.** Not a leaky abstraction; downstream packages don't need to know about Ajv. But when they need to inspect a validation failure in detail, the raw Ajv error is available via `SchemaError.errors[]`.
+2. **Two-pass registration.** All schemas registered first, then validators compiled. This is the only way cross-schema `$ref`s (e.g. `pack.schema.json` → `tool.schema.json`) resolve correctly.
+3. **Typed `Result` errors, never thrown.** Every fallible operation returns `Result<T, SchemaError>`. Consumers explicitly handle both branches.
+4. **Sync when possible, async only when doing I/O.** `createSpecRegistry(schemas)` is sync; `loadSpecRegistry(dir)` is async. Not everything has to be a Promise.
+5. **Fail-fast at construction.** A broken schema during registration returns immediately — downstream validators would be meaningless.
+
+## The Registry
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│ SpecRegistry                                                    │
+│                                                                 │
+│  schemas:    Map<$id, unknown>       ← raw parsed JSON         │
+│  validators: Map<$id, ValidateFn>    ← compiled Ajv validators │
+│                                                                 │
+│  validate<T>(id, data) → Result<T, SchemaError>                │
+│  getSchema(id)         → Result<unknown, SchemaError>          │
+│  ids()                 → readonly string[]                     │
+└───────────────────────────────────────────────────────────────┘
+```
+
+### Construction paths
+
+Two entry points, one internal builder:
+
+- `createSpecRegistry(schemas)` — synchronous. Every schema is already parsed. Suitable for tests and in-memory use.
+- `loadSpecRegistry(dir)` — asynchronous. Reads every `*.schema.json` from `dir`, parses JSON, delegates.
+
+Both return `Result<SpecRegistry, SchemaError>`. Failure at any point (bad `$id`, non-parseable JSON, Ajv rejection) surfaces as `err`.
+
+### Validate semantics
+
+`validate<T>(id, data)` returns:
+- `{ kind: 'ok', value: data as T }` on success. The `T` type parameter is caller-asserted — Ajv validated the shape matches the JSON Schema, but the caller declares what TypeScript type that corresponds to. Callers keep the pairing correct until we add TS codegen from schemas.
+- `{ kind: 'err', error }` on failure. The error is a discriminated union: `schema-not-found` (id not registered), `validation-error` (Ajv rejected the data, raw `errors[]` available).
+
+Validators are pre-compiled at construction time — `validate` is a hot-path operation with no per-call compilation cost.
+
+## Version extraction
+
+`versionOf(schema)` parses two things:
+- **Major version** from `$id` — the `v<N>` segment in `https://kindgi.com/schemas/v<N>/<name>.schema.json`. Returned as `SchemaMajor` (branded number).
+- **Full semver** from `$comment: "schema-version: X.Y.Z"`. Returned as `Semver` (branded string).
+
+The regex patterns are strict:
+```
+$id:      ^https://kindgi\.com/schemas/v(\d+)/([a-z][a-z0-9-]*)\.schema\.json$
+$comment: ^schema-version: (\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?)$
+```
+
+Semver prereleases (`1.0.0-rc.3`) are supported. Non-conforming `$id` or `$comment` returns `err`.
+
+**Not checked here:** consistency between the `$id` major (`v1`) and the `$comment` major (`1.x.y`). That's a lint concern — if `$id: v2` but `$comment: schema-version: 1.5.0`, this function still returns ok with major=2 and semver=1.5.0. A separate consistency check (in `@kindgi/specs`' `scripts/validate.mjs`, run by `pnpm run spec:validate`) catches drift.
+
+## Error shapes
+
+`SchemaError` is a discriminated union. Consumers switch on `code`:
+
+| Code | Fields | When |
+|---|---|---|
+| `schema-load-error` | `path`, `cause` | Filesystem I/O failed |
+| `schema-parse-error` | `path`, `cause` | JSON.parse threw |
+| `schema-compile-error` | `id`, `cause` | Schema structurally invalid or Ajv rejected during registration |
+| `schema-not-found` | `id` | Validate/get for an unregistered `$id` |
+| `validation-error` | `id`, `errors[]` | Ajv found data invalid; `errors[]` is the raw Ajv report |
+
+Every error has `code` and `message`. Consumers should match on `code`; `message` is documentation-grade but not part of the contract.
+
+## Testing strategy
+
+**Unit** (`src/*.test.ts`):
+- `version.test.ts` — valid and invalid `$id` / `$comment` combinations, prereleases, higher majors.
+- `registry.test.ts` — empty registry, populated registry, cross-`$ref` resolution, missing `$id`, non-object schemas, validate positive/negative, `getSchema`, `schema-not-found`.
+
+**Integration** (`tests/*.test.ts`):
+- `specs-integration.test.ts` — loads the real `@kindgi/specs` directory, exercises every registered schema, validates a real flow document, confirms error paths.
+
+## Zod as optional authoring surface
+
+JSON Schema stays the **authoritative wire form**. Every artifact registered in `SpecRegistry`, every manifest exchanged over MCP / HTTP / cross-runtime discovery, every schema published in `@kindgi/specs/*.schema.json` remains a Draft 2020-12 JSON Schema document. Nothing changes for non-TS consumers.
+
+With Zod v4 as the workspace-wide version, `@kindgi/schema` exposes three helpers that let downstream packages (`@kindgi/tools`, `@kindgi/guardrails`, and consumers below) accept **either** JSON Schema **or** Zod v4 schemas at authoring time:
+
+- `isZodSchema(value): value is ZodLikeSchema` — structural check for the `_zod` + `~standard` shape Zod v4 stamps on every schema. No runtime import of `zod`; safe when the peer dep is absent.
+- `schemaKindOf(value): 'zod' | 'json-schema'` — sugar over `isZodSchema`.
+- `toJSONSchema(schema): Result<JSONSchemaObject, InvalidZodConversionError>` — async, dynamic-imports `zod` on first use. Companion `toJSONSchemaSync` accepts a pre-loaded converter for sync authoring paths; the corresponding `loadZodConverterSync()` uses Node's `createRequire` so `defineTool` / `defineCheck` stay synchronous.
+
+**`zod` is a peer dependency** on every package that accepts Zod authoring. Workspaces that never write Zod never install it and never pay any resolution cost. Callers who pass a Zod schema without `zod` on their `node_modules` get a typed `invalid-zod-conversion` error surfaced through the returned `Result` — never a module-resolution crash.
+
+**Fidelity + limitations** — `z.toJSONSchema()` covers Zod primitives, objects, arrays, unions, discriminated unions, literals, enums, records, tuples, optional/nullable/nonoptional wrappers, defaults, catches, coerced primitives, refinements, and pipes. Unrepresentable constructs (`z.function()`, `z.symbol()`, `.transform()` chains whose output has no JSON Schema equivalent) throw at conversion — we surface those as `invalid-zod-conversion` at the boundary so authors see the failure immediately, not at wire time.
+
+**Not supported** — `z.fromJSONSchema()` (the reverse direction) and other TS validation libraries (Effect Schema, Valibot, …).
+
+## Non-goals
+
+- **No wire-level Zod.** Every artifact on the wire is a JSON Schema. Language-agnostic MCP + OpenAPI + Python/Go/Rust consumers must never see Zod.
+- **No TS type generation from JSON Schemas.** Callers maintain matching TS types by hand, or author with Zod and derive them via `z.infer<...>`.
+- **No custom Ajv keywords or extensions.** Stock Ajv Draft 2020-12 + `ajv-formats` only.
+- **No schema migration between majors.** Not needed until any schema has a v2.
+- **No caching of loaded registries across calls.** Callers manage their own registry lifecycle.
+
+## Change discipline
+
+`SpecRegistry` is a stable interface — additions are non-breaking, removals or signature changes are semver-major.
+
+`SchemaError` union is stable — adding a new variant is non-breaking as long as consumers exhaustively switch on `code` with a default case (or accept unknown codes gracefully).
+
+`versionOf` output shape (`{ major, semver }`) is stable. Adding fields (e.g. `prerelease`) is non-breaking.

package/dist/canonical.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Canonical JSON serialization — deterministic, reproducible byte-shape
+ * suitable for signing.
+ *
+ * A simplified RFC 8785 (JSON Canonicalization Scheme, JCS) implementation
+ * covering the subset of JSON the framework emits: primitives, arrays, and
+ * objects with sorted string keys.
+ *
+ * Rules:
+ *   - Object keys are sorted lexicographically.
+ *   - `undefined` values are omitted entirely (they're never signed).
+ *   - `null` is preserved.
+ *   - Numbers are serialized via `JSON.stringify` — sufficient for the
+ *     integer + normal-float range the framework emits; if callers ever
+ *     emit denormalized doubles or high-precision values, revisit.
+ *   - Strings use JSON escaping (again via `JSON.stringify`).
+ *   - No whitespace between tokens.
+ *
+ * This lives in the public `@kindgi/schema` package because:
+ *   - Signature verifiers on the SDK side must reproduce the exact
+ *     same bytes to check signatures — moving this to closed code
+ *     would break client-side verify.
+ *   - The algorithm is a public commitment: existing signatures become
+ *     unverifiable if this changes.
+ */
+export declare function canonicalize(value: unknown): string;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAuBnD"}

package/dist/canonical.js

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Canonical JSON serialization — deterministic, reproducible byte-shape
+ * suitable for signing.
+ *
+ * A simplified RFC 8785 (JSON Canonicalization Scheme, JCS) implementation
+ * covering the subset of JSON the framework emits: primitives, arrays, and
+ * objects with sorted string keys.
+ *
+ * Rules:
+ *   - Object keys are sorted lexicographically.
+ *   - `undefined` values are omitted entirely (they're never signed).
+ *   - `null` is preserved.
+ *   - Numbers are serialized via `JSON.stringify` — sufficient for the
+ *     integer + normal-float range the framework emits; if callers ever
+ *     emit denormalized doubles or high-precision values, revisit.
+ *   - Strings use JSON escaping (again via `JSON.stringify`).
+ *   - No whitespace between tokens.
+ *
+ * This lives in the public `@kindgi/schema` package because:
+ *   - Signature verifiers on the SDK side must reproduce the exact
+ *     same bytes to check signatures — moving this to closed code
+ *     would break client-side verify.
+ *   - The algorithm is a public commitment: existing signatures become
+ *     unverifiable if this changes.
+ */
+export function canonicalize(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new Error(`Cannot canonicalize non-finite number: ${String(value)}`);
+        }
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        const parts = value.map((item) => canonicalize(item));
+        return `[${parts.join(',')}]`;
+    }
+    if (typeof value === 'object') {
+        const obj = value;
+        const keys = Object.keys(obj)
+            .filter((k) => obj[k] !== undefined)
+            .sort();
+        const parts = keys.map((k) => `${JSON.stringify(k)}:${canonicalize(obj[k])}`);
+        return `{${parts.join(',')}}`;
+    }
+    throw new Error(`Cannot canonicalize value of type ${typeof value}`);
+}
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IAChE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,0CAA0C,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC7E,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC5D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;QACtD,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAChC,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,KAA0C,CAAC;QACvD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;aAC1B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC;aACnC,IAAI,EAAE,CAAC;QACV,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC9E,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAChC,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,qCAAqC,OAAO,KAAK,EAAE,CAAC,CAAC;AACvE,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Typed errors emitted by @kindgi/schema.
+ *
+ * Every error carries:
+ *   - `code`  — machine-readable discriminator for `if (err.code === ...)` matching.
+ *   - `message` — human-readable summary.
+ *   - Case-specific fields (path, id, cause, errors[]).
+ *
+ * Consumers should switch on `code`, not on `message`. Message strings are
+ * documentation-grade but not part of the API contract.
+ */
+export type SchemaError = SchemaLoadError | SchemaParseError | SchemaCompileError | SchemaNotFoundError | ValidationError | InvalidZodConversionError;
+/** Filesystem error while reading a schema file or specs directory. */
+export interface SchemaLoadError {
+    readonly code: 'schema-load-error';
+    readonly message: string;
+    readonly path: string;
+    readonly cause: unknown;
+}
+/** JSON parse error while reading a schema file. */
+export interface SchemaParseError {
+    readonly code: 'schema-parse-error';
+    readonly message: string;
+    readonly path: string;
+    readonly cause: unknown;
+}
+/**
+ * Ajv rejected the schema during registration/compilation.
+ * Also used when a schema is structurally invalid (missing `$id`, etc).
+ */
+export interface SchemaCompileError {
+    readonly code: 'schema-compile-error';
+    readonly message: string;
+    readonly id: string;
+    readonly cause: unknown;
+}
+/** Requested a schema by `$id` that isn't registered. */
+export interface SchemaNotFoundError {
+    readonly code: 'schema-not-found';
+    readonly message: string;
+    readonly id: string;
+}
+/**
+ * Data did not validate against the schema. `errors` holds Ajv's error report,
+ * intentionally typed as `unknown[]` — consumers must cast to `AjvError[]` if
+ * they want to inspect fields, so this package doesn't leak the Ajv API shape.
+ */
+export interface ValidationError {
+    readonly code: 'validation-error';
+    readonly message: string;
+    readonly id: string;
+    readonly errors: readonly unknown[];
+}
+/**
+ * A Zod schema was passed at an authoring boundary and either
+ *   - the `zod` peer dependency is not installed, or
+ *   - `z.toJSONSchema(schema)` threw (unrepresentable Zod construct —
+ *     e.g. `.transform()` targeting a runtime side-effect, function
+ *     schemas, uncontained cycles).
+ *
+ * `cause` is the underlying Error, preserved for surfacing to the author.
+ */
+export interface InvalidZodConversionError {
+    readonly code: 'invalid-zod-conversion';
+    readonly message: string;
+    readonly cause: unknown;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GACnB,eAAe,GACf,gBAAgB,GAChB,kBAAkB,GAClB,mBAAmB,GACnB,eAAe,GACf,yBAAyB,CAAC;AAE9B,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB"}

package/dist/errors.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { canonicalize } from './canonical.js';
+export type { InvalidZodConversionError, SchemaCompileError, SchemaError, SchemaLoadError, SchemaNotFoundError, SchemaParseError, ValidationError, } from './errors.js';
+export { compileInlineSchema, createSpecRegistry, loadSpecRegistry } from './registry.js';
+export type { CompiledInlineSchema, SpecRegistry, ValidationErrorLike } from './registry.js';
+export { versionOf } from './version.js';
+export type { SchemaVersion } from './version.js';
+export { isJsonSchemaObject, isZodSchema, loadZodConverter, loadZodConverterSync, parseWithSchema, schemaKindOf, toJSONSchema, toJSONSchemaSync, } from './zod.js';
+export type { AnySchema, JSONSchemaObject, SchemaIo, SchemaIssue, SchemaKind, ZodConverter, ZodLikeSchema, } from './zod.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EACV,yBAAyB,EACzB,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC1F,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,UAAU,EACV,YAAY,EACZ,aAAa,GACd,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export { canonicalize } from './canonical.js';
+export { compileInlineSchema, createSpecRegistry, loadSpecRegistry } from './registry.js';
+export { versionOf } from './version.js';
+export { isJsonSchemaObject, isZodSchema, loadZodConverter, loadZodConverterSync, parseWithSchema, schemaKindOf, toJSONSchema, toJSONSchemaSync, } from './zod.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAU9C,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAE1F,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,gBAAgB,GACjB,MAAM,UAAU,CAAC"}