Add iso-index package

Author: CharGrnmn

.github/workflows/ci.yml

@@ -62,6 +62,9 @@ jobs:
           - workspace: "@razroo/iso-cache"
             node: "20.6.0"
             extra: ""
+          - workspace: "@razroo/iso-index"
+            node: "20.6.0"
+            extra: ""
           - workspace: "@razroo/iso-contract"
             node: "20.6.0"
             extra: ""
@@ -195,6 +198,13 @@ jobs:
           node packages/iso-cache/dist/cli.js has "jd:example" --cache /tmp/iso-cache-example
           node packages/iso-cache/dist/cli.js verify --cache /tmp/iso-cache-example
 
+      - name: iso-index example build/query
+        run: |
+          node packages/iso-index/dist/cli.js build --config packages/iso-index/examples/jobforge-index.json --root packages/iso-index/examples/jobforge-project --out /tmp/jobforge.iso-index.json
+          node packages/iso-index/dist/cli.js has --index /tmp/jobforge.iso-index.json --key "company-role:example-labs:staff-agent-engineer"
+          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-contract example validate/render
         run: |
           node packages/iso-contract/dist/cli.js validate jobforge.tracker-row --contracts packages/iso-contract/examples/jobforge-contracts.json --input @packages/iso-contract/examples/tracker-row.json

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

@@ -0,0 +1,48 @@
+name: iso-index Release to npm
+
+on:
+  release:
+    types: [published]
+
+defaults:
+  run:
+    working-directory: packages/iso-index
+
+jobs:
+  publish:
+    if: startsWith(github.ref_name, 'iso-index-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-index-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 fourteen packages that **work on their own** but are **designed
+This repo ships fifteen 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:
 
@@ -177,6 +177,19 @@ without asking the model to refetch or rederive safe artifacts.
 
 ---
 
+## 12. `iso-index` ← deterministic artifact lookup for domain packages — **DONE**
+
+Introduced as a standalone package. `iso-index` does not import JobForge,
+`iso-cache`, `iso-ledger`, `iso-contract`, or any other domain package; it
+provides the on-disk JSON index format and extractor rules that domain
+tools can share. JobForge-style examples cover report URLs/scores,
+tracker markdown tables, scan-history TSVs, and ledger JSONL records, but
+the package remains generic: build compact lookup records from configured
+text, TSV, markdown-table, and JSONL sources, then query/has/verify them
+without asking the model to grep or load entire artifact trees.
+
+---
+
 ## Design questions that are *not* open integrations
 
 The following look like integrations but are deliberately decoupled —
@@ -222,3 +235,7 @@ don't "fix" them without a conversation first.
   integrity. Domain packages still own which artifacts are safe to cache,
   how long they stay fresh, and which side-effectful operations must never
   be replayed from cache.
+- **`iso-index` does not decide source precedence for a domain.**
+  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.

README.md

@@ -31,7 +31,7 @@ Today, agent workflow reliability is fragmented on three axes:
    "what already happened." Those invariants belong in deterministic local packages,
    not in repeatedly re-tokenized instructions.
 
-Fourteen packages solve that in one pipeline with runtime control and a
+Fifteen 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,13 +41,15 @@ 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`.
-- **Six runtime-control libraries** handle durable execution, context selection, artifact caching, role capabilities, artifact shape, and operational truth:
+- **Seven runtime-control libraries** handle durable execution, context selection, artifact caching, artifact lookup, 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,
   estimates tokens, checks budgets, and renders deterministic context packs,
   [`@razroo/iso-cache`](./packages/iso-cache) stores and verifies
   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-capabilities`](./packages/iso-capabilities) resolves,
   checks, and renders role-level tool/MCP/command/filesystem/network policy,
   [`@razroo/iso-contract`](./packages/iso-contract) validates, parses, and
@@ -70,6 +72,7 @@ feedback loop:
                                                                                                      │                      │    iso-guard ─▶  policy pass / fail
                                                                                                      │                      │    iso-context ─▶ context bundle plan
                                                                                                      │                      │    iso-cache ─▶ artifact reuse
+                                                                                                     │                      │    iso-index ─▶ artifact lookup
                                                                                                      │                      │    iso-capabilities ─▶ role permission policy
   ┌────────────────────┐                                                                             │ .codex/config.toml    │
   │ models.yaml        │ ───────────────────── iso-route build ─────────────────────────────────────▶│ opencode.json         │
@@ -121,6 +124,8 @@ the repo now supports a tighter loop:
   instead of repeating context-loading matrices in prompts.
 - `iso-cache put/get/verify` keeps reusable artifacts local instead of
   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-capabilities check/render` keeps role permission matrices local
   instead of repeating tool/MCP/filesystem boundaries in prompts.
 - `iso-trace model-score` catches tool-schema failures that weaker routes
@@ -148,6 +153,9 @@ of the prompt:
 - `iso-cache` makes artifact reuse executable: stable keys,
   content-addressed blobs, TTL-aware reads, integrity verification, and
   pruning without asking a model to refetch safe inputs.
+- `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-capabilities` makes role boundaries executable: resolve inherited
   tool/MCP/command/filesystem/network policy, check proposed actions, and
   render compact harness guidance without asking a model to remember a
@@ -245,6 +253,13 @@ of the prompt:
   expired/orphaned artifacts so domain packages can reuse safe inputs
   without model calls or MCP overhead.
 
+- **[`packages/iso-index`](./packages/iso-index)** — [`@razroo/iso-index`](https://www.npmjs.com/package/@razroo/iso-index)
+  Deterministic local artifact index for agent workflows. Builds compact
+  lookup indexes from configured text, TSV, markdown-table, and JSONL
+  sources, then supports `query/has/verify` so domain packages can find
+  authoritative facts without loading whole artifact trees into prompt
+  context.
+
 - **[`packages/iso-contract`](./packages/iso-contract)** — [`@razroo/iso-contract`](https://www.npmjs.com/package/@razroo/iso-contract)
   Deterministic artifact contracts for agent workflows. Loads JSON
   contract catalogs, validates records, and parses/renders JSON, TSV,
@@ -401,6 +416,16 @@ iso-cache verify
 iso-cache prune --expired
 ```
 
+### `@razroo/iso-index` — where is the authoritative fact?
+
+```bash
+iso-index build --config index.json --root . --out .iso-index.json
+iso-index query "example labs" --index .iso-index.json
+iso-index has --index .iso-index.json --key "company-role:example-labs:staff-agent-engineer"
+iso-index verify --index .iso-index.json
+iso-index explain --config index.json
+```
+
 ### `@razroo/iso-contract` — what shape must this artifact have?
 
 ```bash
@@ -439,6 +464,7 @@ iso/
     ├── iso-ledger/       # append-only operational event/state ledger
     ├── iso-context/      # deterministic context bundle policy
     ├── iso-cache/        # deterministic content-addressed artifact cache
+    ├── iso-index/        # deterministic local artifact lookup index
     ├── iso-contract/     # deterministic artifact contracts
     └── iso-capabilities/ # deterministic role capability policy
 ```
@@ -459,6 +485,7 @@ npm --workspace @razroo/iso-guard run test      # iso-guard policy engine tests
 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-contract run test   # iso-contract artifact contract tests
 npm --workspace @razroo/iso-capabilities run test # iso-capabilities policy tests
 
@@ -496,7 +523,7 @@ build, and `npm publish --provenance`.
 ## End-to-end example
 
 [`examples/pipeline/`](./examples/pipeline) is an executable demonstration
-that exercises **seven of the fourteen packages end-to-end** in one `npm run
+that exercises **seven of the fifteen 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
@@ -515,7 +542,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-contract`, and `iso-capabilities`
+`iso-harness`, `iso`, `iso-eval`, `iso-trace`, `iso-route`, `iso-guard`, `iso-ledger`, `iso-context`, `iso-cache`, `iso-index`, `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-index
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial release: deterministic local artifact index for agent workflows with text, TSV, markdown-table, and JSONL source indexing, query/has/verify CLI commands, examples, and tests.

packages/iso-index/CHANGELOG.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 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.