Add iso-canon package

Author: CharGrnmn

.github/workflows/ci.yml

@@ -65,6 +65,9 @@ jobs:
           - workspace: "@razroo/iso-index"
             node: "20.6.0"
             extra: ""
+          - workspace: "@razroo/iso-canon"
+            node: "20.6.0"
+            extra: ""
           - workspace: "@razroo/iso-migrate"
             node: "20.6.0"
             extra: ""
@@ -208,6 +211,12 @@ jobs:
           node packages/iso-index/dist/cli.js query --index /tmp/jobforge.iso-index.json --kind jobforge.report.url --key "url:https://example.test/jobs/123"
           node packages/iso-index/dist/cli.js verify --index /tmp/jobforge.iso-index.json
 
+      - name: iso-canon example normalize/compare
+        run: |
+          node packages/iso-canon/dist/cli.js normalize company "OpenAI, Inc." --config packages/iso-canon/examples/jobforge-canon.json --profile jobforge
+          node packages/iso-canon/dist/cli.js key company-role --company "Anthropic, PBC" --role "Senior SWE, AI Platform - Remote US" --config packages/iso-canon/examples/jobforge-canon.json --profile jobforge
+          node packages/iso-canon/dist/cli.js compare company "OpenAI, Inc." "Open AI" --config packages/iso-canon/examples/jobforge-canon.json --profile jobforge
+
       - name: iso-migrate example plan/apply/check
         run: |
           mkdir -p /tmp/iso-migrate-smoke

.github/workflows/iso-canon-release.yml

@@ -0,0 +1,48 @@
+name: iso-canon Release to npm
+
+on:
+  release:
+    types: [published]
+
+defaults:
+  run:
+    working-directory: packages/iso-canon
+
+jobs:
+  publish:
+    if: startsWith(github.ref_name, 'iso-canon-v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      checks: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - name: Set version from release tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#iso-canon-v}"
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+
+      - name: Verify required CI passed for release commit
+        uses: ./.github/actions/verify-release-gate
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Verify package.json version matches release tag
+        run: npm run release:check-source -- "$VERSION"
+
+      - name: Install (workspace root)
+        run: npm ci
+        working-directory: .
+
+      - name: Publish to npm (with provenance)
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

INTEGRATIONS.md

@@ -1,6 +1,6 @@
 # Integrations
 
-This repo ships sixteen packages that **work on their own** but are **designed
+This repo ships seventeen packages that **work on their own** but are **designed
 to compose**. The planned cross-package compositions listed here are already
 shipped, so this file now serves as:
 
@@ -203,6 +203,19 @@ asking the model to hand-edit consumer-owned files.
 
 ---
 
+## 14. `iso-canon` ← deterministic identity keys for domain packages — **DONE**
+
+Introduced as a standalone package. `iso-canon` does not import JobForge,
+`iso-index`, `iso-ledger`, or any other domain package; it provides the
+on-disk JSON profile format and canonicalizer that domain tools can share.
+JobForge-style examples cover URL tracking cleanup, company legal suffixes,
+role aliases, and company-role dedupe keys, but the package remains generic:
+normalize URL/company/role/company-role identifiers and return explainable
+`same` / `possible` / `different` comparisons without asking the model to
+remember duplicate-matching rules.
+
+---
+
 ## Design questions that are *not* open integrations
 
 The following look like integrations but are deliberately decoupled —
@@ -252,6 +265,10 @@ don't "fix" them without a conversation first.
   It builds and verifies lookup records from configured sources. Domain
   packages still own which source wins when report, tracker, scan, cache,
   and ledger facts disagree, and when an index should be rebuilt.
+- **`iso-canon` does not decide duplicate policy for a domain.** It emits
+  stable keys and explainable comparisons. Domain packages still own whether
+  a `possible` match blocks work, warns, or routes to review, and which
+  artifact source wins when canonical keys disagree with raw records.
 - **`iso-migrate` does not decide release policy for a domain.** It plans
   and applies idempotent file edits. Domain packages still own when
   migrations run, how versions map to migration catalogs, and which

README.md

@@ -12,7 +12,7 @@ Codex, OpenCode) and stays legible across model tiers (frontier models down
 to 7B local models). The repo now covers the full loop: build portable
 harness files, route models, replay evals, parse production traces, scope
 role capabilities, select deterministic context bundles, audit runtime policy,
-cache reusable artifacts, migrate consumer projects, validate artifact contracts, and persist local workflow truth. The only narrower surface is `iso-trace model-score`, which still
+cache reusable artifacts, canonicalize identity keys, migrate consumer projects, validate artifact contracts, and persist local workflow truth. The only narrower surface is `iso-trace model-score`, which still
 depends on transcripts exposing stable model metadata.
 
 Today, agent workflow reliability is fragmented on three axes:
@@ -27,11 +27,11 @@ Today, agent workflow reliability is fragmented on three axes:
    unstructured rationale all drop silently at 7B. You don't find out
    until the agent misbehaves in production.
 3. **Runtime fragmentation.** Workflows rely on fragile prompt prose for
-  fan-out limits, context loading, artifact reuse, project upgrades, role permissions, output shape, duplicate checks, and
+  fan-out limits, context loading, artifact reuse, identity keys, project upgrades, role permissions, output shape, duplicate checks, and
   "what already happened." Those invariants belong in deterministic local packages,
   not in repeatedly re-tokenized instructions.
 
-Sixteen packages solve that in one pipeline with runtime control and a
+Seventeen packages solve that in one pipeline with runtime control and a
 feedback loop:
 
 - **Four build-time tools** turn your authored source into every harness's file layout:
@@ -41,7 +41,7 @@ feedback loop:
   [`@razroo/iso-route`](./packages/iso-route) compiles *one model policy* into each harness's config.
 - **One wrapper** runs the whole build chain:
   [`@razroo/iso`](./packages/iso) chains the above into a single `iso build`.
-- **Eight runtime-control libraries** handle durable execution, context selection, artifact caching, artifact lookup, project migration, role capabilities, artifact shape, and operational truth:
+- **Nine runtime-control libraries** handle durable execution, context selection, artifact caching, artifact lookup, identity canonicalization, project migration, role capabilities, artifact shape, and operational truth:
   [`@razroo/iso-orchestrator`](./packages/iso-orchestrator) provides resumable
   steps, keyed mutexes, and bounded fan-out for side-effectful agent workflows,
   [`@razroo/iso-context`](./packages/iso-context) resolves context bundles,
@@ -50,6 +50,8 @@ feedback loop:
   content-addressed local artifacts with TTL-aware reads and pruning,
   [`@razroo/iso-index`](./packages/iso-index) builds and queries compact
   local indexes that point to authoritative facts across artifacts,
+  [`@razroo/iso-canon`](./packages/iso-canon) produces stable URL,
+  company, role, and company-role keys for duplicate checks,
   [`@razroo/iso-migrate`](./packages/iso-migrate) plans and applies
   idempotent consumer-project file migrations,
   [`@razroo/iso-capabilities`](./packages/iso-capabilities) resolves,
@@ -75,6 +77,7 @@ feedback loop:
                                                                                                      │                      │    iso-context ─▶ context bundle plan
                                                                                                      │                      │    iso-cache ─▶ artifact reuse
                                                                                                      │                      │    iso-index ─▶ artifact lookup
+                                                                                                     │                      │    iso-canon ─▶ identity keys
                                                                                                      │                      │    iso-migrate ─▶ project upgrades
                                                                                                      │                      │    iso-capabilities ─▶ role permission policy
   ┌────────────────────┐                                                                             │ .codex/config.toml    │
@@ -129,6 +132,8 @@ the repo now supports a tighter loop:
   refetching or rederiving safe inputs on every run.
 - `iso-index build/query/has` keeps artifact lookup local instead of
   grepping and loading growing state/report trees into prompts.
+- `iso-canon normalize/key/compare` keeps duplicate/entity keys local
+  instead of repeatedly restating URL, company, and role matching rules.
 - `iso-migrate plan/apply/check` keeps consumer project upgrades local
   instead of hand-editing package scripts, dependency ranges, and ignores.
 - `iso-capabilities check/render` keeps role permission matrices local
@@ -161,6 +166,9 @@ of the prompt:
 - `iso-index` makes artifact lookup executable: text/TSV/markdown-table/JSONL
   sources compile into a compact queryable index, so agents can ask where a
   fact lives without repeatedly grepping or loading growing files.
+- `iso-canon` makes identity canonicalization executable: URLs, companies,
+  roles, and company-role pairs compile to stable keys with explainable
+  `same` / `possible` / `different` comparisons.
 - `iso-migrate` makes project upgrades executable: JSON pointer edits, line
   insertion, exact replacement, and guarded file writes run as idempotent
   migrations instead of one-off shell patches.
@@ -268,6 +276,12 @@ of the prompt:
   authoritative facts without loading whole artifact trees into prompt
   context.
 
+- **[`packages/iso-canon`](./packages/iso-canon)** — [`@razroo/iso-canon`](https://www.npmjs.com/package/@razroo/iso-canon)
+  Deterministic canonicalization and entity matching for agent workflows.
+  Normalizes URLs, companies, roles, and company-role pairs into stable
+  keys, then compares them with an explainable score so domain packages
+  can keep duplicate checks out of prompt prose.
+
 - **[`packages/iso-migrate`](./packages/iso-migrate)** — [`@razroo/iso-migrate`](https://www.npmjs.com/package/@razroo/iso-migrate)
   Deterministic project migrations for agent workflow packages. Plans,
   applies, checks, and explains idempotent JSON/text file upgrades so
@@ -440,6 +454,15 @@ iso-index verify --index .iso-index.json
 iso-index explain --config index.json
 ```
 
+### `@razroo/iso-canon` — what stable key names this entity?
+
+```bash
+iso-canon normalize url "https://www.example.com/jobs/123?utm_source=x"
+iso-canon key company-role --company "Anthropic, PBC" --role "Senior SWE - Remote US"
+iso-canon compare company "OpenAI, Inc." "Open AI" --config canon.json --profile jobforge
+iso-canon explain --config canon.json --profile jobforge
+```
+
 ### `@razroo/iso-migrate` — what project-owned files need upgrading?
 
 ```bash
@@ -488,6 +511,7 @@ iso/
     ├── iso-context/      # deterministic context bundle policy
     ├── iso-cache/        # deterministic content-addressed artifact cache
     ├── iso-index/        # deterministic local artifact lookup index
+    ├── iso-canon/        # deterministic identity canonicalization
     ├── iso-migrate/      # deterministic consumer project migrations
     ├── iso-contract/     # deterministic artifact contracts
     └── iso-capabilities/ # deterministic role capability policy
@@ -510,6 +534,7 @@ npm --workspace @razroo/iso-ledger run test     # iso-ledger event/state tests
 npm --workspace @razroo/iso-context run test    # iso-context bundle/budget tests
 npm --workspace @razroo/iso-cache run test      # iso-cache artifact cache tests
 npm --workspace @razroo/iso-index run test      # iso-index artifact lookup tests
+npm --workspace @razroo/iso-canon run test      # iso-canon identity key tests
 npm --workspace @razroo/iso-migrate run test    # iso-migrate project migration tests
 npm --workspace @razroo/iso-contract run test   # iso-contract artifact contract tests
 npm --workspace @razroo/iso-capabilities run test # iso-capabilities policy tests
@@ -548,7 +573,7 @@ build, and `npm publish --provenance`.
 ## End-to-end example
 
 [`examples/pipeline/`](./examples/pipeline) is an executable demonstration
-that exercises **seven of the sixteen packages end-to-end** in one `npm run
+that exercises **seven of the seventeen packages end-to-end** in one `npm run
 test:pipeline` invocation: `agentmd lint` + `render` → `isolint lint` →
 `iso-route build` (from a bundled `models.yaml` that extends the
 `standard` preset) → `iso-harness build` (which consumes iso-route's
@@ -567,7 +592,7 @@ downstream repo would use.
 
 `npm run test:pack` goes one level further: it packs the local workspaces into
 tarballs, installs them into fresh temp projects, and smoke-tests the packaged
-`iso-harness`, `iso`, `iso-eval`, `iso-trace`, `iso-route`, `iso-guard`, `iso-ledger`, `iso-context`, `iso-cache`, `iso-index`, `iso-migrate`, `iso-contract`, and `iso-capabilities`
+`iso-harness`, `iso`, `iso-eval`, `iso-trace`, `iso-route`, `iso-guard`, `iso-ledger`, `iso-context`, `iso-cache`, `iso-index`, `iso-canon`, `iso-migrate`, `iso-contract`, and `iso-capabilities`
 CLIs. This guards against packaging regressions that workspace-only tests can
 miss.
 

package-lock.json

@@ -0,0 +1,7 @@
+# @razroo/iso-canon
+
+## 0.1.0
+
+- Initial release with deterministic URL, company, role, and company-role canonicalization.
+- Adds explainable entity comparison for duplicate checks and drift detection.
+- Ships a JobForge-style profile example and CLI smoke surface.

packages/iso-canon/CHANGELOG.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Razroo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.