Add iso-facts package

Author: CharGrnmn

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

@@ -0,0 +1,48 @@
+name: iso-facts Release to npm
+
+on:
+  release:
+    types: [published]
+
+defaults:
+  run:
+    working-directory: packages/iso-facts
+
+jobs:
+  publish:
+    if: startsWith(github.ref_name, 'iso-facts-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-facts-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 nineteen packages that **work on their own** but are **designed
+This repo ships twenty 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:
 
@@ -243,6 +243,19 @@ remember sensitive-data handling rules.
 
 ---
 
+## 17. `iso-facts` ← deterministic fact materialization for domain packages — **DONE**
+
+Introduced as a standalone package. `iso-facts` does not import JobForge,
+`iso-index`, `iso-contract`, `iso-canon`, `iso-preflight`, or any other
+domain package; it provides the on-disk JSON fact policy and fact set formats
+that domain tools can share. JobForge-style examples cover report URLs/scores,
+scan-history TSV rows, tracker tables, JSONL outcomes, and preflight candidate
+JSON, but the package remains generic: extract/query/has/verify/check
+provenance-rich fact records from local artifacts without asking a model to
+reread broad source trees.
+
+---
+
 ## Design questions that are *not* open integrations
 
 The following look like integrations but are deliberately decoupled —
@@ -292,6 +305,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-facts` does not decide domain truth or stale-fact policy.**
+  It materializes configured facts with provenance. Domain packages still own
+  source precedence, staleness rules, conflict handling, and how facts feed
+  contracts, preflight gates, ledgers, or downstream prompts.
 - **`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

README.md

@@ -13,8 +13,9 @@ 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, canonicalize identity keys, plan dispatches, settle
-dispatch results, redact sensitive output, migrate consumer projects, validate
-artifact contracts, and persist local workflow truth. The only narrower surface is `iso-trace model-score`, which still
+dispatch results, redact sensitive output, materialize source-backed facts,
+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:
@@ -29,11 +30,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, identity keys, project upgrades, role permissions, output shape, duplicate checks, post-dispatch settlement, redaction, and
+  fan-out limits, context loading, artifact reuse, fact extraction, identity keys, project upgrades, role permissions, output shape, duplicate checks, post-dispatch settlement, redaction, and
   "what already happened." Those invariants belong in deterministic local packages,
   not in repeatedly re-tokenized instructions.
 
-Nineteen packages solve that in one pipeline with runtime control and a
+Twenty 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:
@@ -43,7 +44,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`.
-- **Twelve runtime-control libraries** handle durable execution, context selection, artifact caching, artifact lookup, identity canonicalization, preflight dispatch planning, postflight settlement, redaction, project migration, role capabilities, artifact shape, and operational truth:
+- **Thirteen runtime-control libraries** handle durable execution, context selection, artifact caching, artifact lookup, fact materialization, identity canonicalization, preflight dispatch planning, postflight settlement, redaction, 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,
@@ -52,6 +53,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-facts`](./packages/iso-facts) extracts, queries, verifies,
+  and checks provenance-rich local facts,
   [`@razroo/iso-canon`](./packages/iso-canon) produces stable URL,
   company, role, and company-role keys for duplicate checks,
   [`@razroo/iso-preflight`](./packages/iso-preflight) validates
@@ -87,6 +90,7 @@ feedback loop:
                                                                                                      │                      │    iso-context ─▶ context bundle plan
                                                                                                      │                      │    iso-cache ─▶ artifact reuse
                                                                                                      │                      │    iso-index ─▶ artifact lookup
+                                                                                                     │                      │    iso-facts ─▶ fact materialization
                                                                                                      │                      │    iso-canon ─▶ identity keys
                                                                                                      │                      │    iso-preflight ─▶ dispatch plan
                                                                                                      │                      │    iso-postflight ─▶ settlement gate
@@ -145,6 +149,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-facts build/query/has/verify` keeps source-backed fact extraction
+  local instead of asking a model to reread broad artifact trees.
 - `iso-canon normalize/key/compare` keeps duplicate/entity keys local
   instead of repeatedly restating URL, company, and role matching rules.
 - `iso-preflight plan/check` keeps dispatch eligibility and batching local
@@ -186,6 +192,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-facts` makes fact materialization executable: local artifacts compile
+  into provenance-rich fact records that can be queried, verified, and checked
+  before downstream contracts or dispatch gates run.
 - `iso-canon` makes identity canonicalization executable: URLs, companies,
   roles, and company-role pairs compile to stable keys with explainable
   `same` / `possible` / `different` comparisons.
@@ -305,6 +314,13 @@ of the prompt:
   authoritative facts without loading whole artifact trees into prompt
   context.
 
+- **[`packages/iso-facts`](./packages/iso-facts)** — [`@razroo/iso-facts`](https://www.npmjs.com/package/@razroo/iso-facts)
+  Deterministic fact materialization for agent workflows. Extracts
+  provenance-rich facts from configured text, TSV, markdown-table, JSONL,
+  and JSON sources, then supports `query/has/verify/check` so domain
+  packages can feed source-backed facts into contracts and dispatch gates
+  without model calls.
+
 - **[`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
@@ -503,6 +519,17 @@ iso-index verify --index .iso-index.json
 iso-index explain --config index.json
 ```
 
+### `@razroo/iso-facts` — what facts can this workflow trust?
+
+```bash
+iso-facts build --config facts.json --root . --out .iso-facts.json
+iso-facts query --facts .iso-facts.json --fact job.url
+iso-facts has --facts .iso-facts.json --fact job.score
+iso-facts verify --facts .iso-facts.json
+iso-facts check --facts .iso-facts.json --config facts.json
+iso-facts explain --config facts.json
+```
+
 ### `@razroo/iso-canon` — what stable key names this entity?
 
 ```bash
@@ -585,6 +612,7 @@ iso/
     ├── iso-context/      # deterministic context bundle policy
     ├── iso-cache/        # deterministic content-addressed artifact cache
     ├── iso-index/        # deterministic local artifact lookup index
+    ├── iso-facts/        # deterministic source-backed fact materialization
     ├── iso-canon/        # deterministic identity canonicalization
     ├── iso-preflight/    # deterministic preflight dispatch planning
     ├── iso-postflight/   # deterministic postflight settlement
@@ -611,6 +639,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-facts run test      # iso-facts materialization tests
 npm --workspace @razroo/iso-canon run test      # iso-canon identity key tests
 npm --workspace @razroo/iso-preflight run test  # iso-preflight dispatch planning tests
 npm --workspace @razroo/iso-postflight run test # iso-postflight settlement tests
@@ -653,7 +682,7 @@ build, and `npm publish --provenance`.
 ## End-to-end example
 
 [`examples/pipeline/`](./examples/pipeline) is an executable demonstration
-that exercises **seven of the nineteen packages end-to-end** in one `npm run
+that exercises **seven of the twenty 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
@@ -672,7 +701,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-canon`, `iso-preflight`, `iso-postflight`, `iso-redact`, `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-facts`, `iso-canon`, `iso-preflight`, `iso-postflight`, `iso-redact`, `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,8 @@
+# @razroo/iso-facts
+
+## 0.1.0
+
+- Initial release.
+- Adds deterministic fact extraction from text, TSV, markdown tables, JSONL,
+  and JSON files.
+- Adds `build`, `query`, `has`, `verify`, `check`, and `explain` CLI commands.

packages/iso-facts/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.