@weftlet/toolkit 0.2.1 → 0.4.0

package/docs/RELEASING.md

@@ -1,6 +1,19 @@
 # Weftlet npm releases
 
-`@weftlet/core@0.2.0` and `@weftlet/toolkit@0.2.0` are published through GitHub OIDC.
+`@weftlet/core` and `@weftlet/toolkit` are published through GitHub OIDC. The latest verified
+release checkpoint is recorded in [validation](VALIDATION.md); the following are historical
+publication records. For release 0.2.1,
+[run 40382864083](https://github.com/jchewitt/weftlet/actions/runs/40382864083) completed
+preparation, publication and release records on its first attempt at commit
+`5d1db91bf19ed493a20849b2d0f92d3aeac35dfe`. Registry archives match the reviewed archives;
+provenance and package tags identify that commit. A fresh public-registry installation passes
+the identity regression, real SCIP/RDF/SHACL, querying and repeat artifact reuse without live
+model calls. [Fix PR #15](https://github.com/jchewitt/weftlet/pull/15) and
+[release PR #16](https://github.com/jchewitt/weftlet/pull/16) record the change. Genuine consumer
+acceptance remains pending in the [1.0 plan](RELEASE-1.0-PLAN.md); detailed upstream evidence
+is in [validation](VALIDATION.md).
+
+The earlier 0.2.0 release also used GitHub OIDC.
 [Run 40344526047](https://github.com/jchewitt/weftlet/actions/runs/40344526047) completed at
 commit `ffe7f1d81f0421b35220bd7ba5b1555246c7a0e1`, including registry integrity checks,
 package tags and GitHub Releases. The first attempt published core, then toolkit publication
@@ -34,8 +47,8 @@ preparation route; native Windows has focused CI coverage. See [validation](VALI
    **before** npm publication. Do not manually bump manifests or edit the generated plan.
 4. The plan change triggers **Weftlet release**. It validates and prepares both archives, publishes
    core followed by toolkit using npm trusted publishing, then verifies registry integrity.
-5. After both versions are verified, a separate job creates tags such as `@weftlet/core@0.2.0`
-   and `@weftlet/toolkit@0.2.0`, plus corresponding GitHub Releases, at that exact source commit.
+5. After both versions are verified, a separate job creates tags such as `@weftlet/core@0.2.1`
+   and `@weftlet/toolkit@0.2.1`, plus corresponding GitHub Releases, at that exact source commit.
    Existing tags are never moved. The publication job does not commit back to main.
 
 The bot uses GitHub's built-in token, not a personal access token. GitHub may require Settings →
@@ -148,7 +161,7 @@ Package-specific tags identify the exact published source, for example:
 
 ```sh
 git fetch --tags
-git switch --detach '@weftlet/toolkit@0.2.0'
+git switch --detach '@weftlet/toolkit@0.2.1'
 ```
 
 Tags support inspection and reproduction, not mutation of npm history. To roll a consumer back,
@@ -158,8 +171,8 @@ Verify a new public release in a fresh disposable project, substituting its vers
 
 ```sh
 npm init -y
-npx --yes @weftlet/toolkit@0.2.0 init --yes
-npx --yes @weftlet/toolkit@0.2.0 config validate
+npx --yes @weftlet/toolkit@0.2.1 init --yes
+npx --yes @weftlet/toolkit@0.2.1 config validate
 ```
 
 Check registry hashes, transitive core resolution and provenance. Deprecating the previous

package/docs/ROADMAP.md

@@ -1,15 +1,56 @@
 # Delivery roadmap
 
+Release checkpoint: 2026-10-26, after verified 0.3.0 publication. Evidence is recorded in
+[validation](VALIDATION.md); this roadmap is not a live registry status.
+
 Project: `jchewitt/weftlet`. Extraction provenance is recorded in the
 [source inventory](SOURCE-INVENTORY.md).
 
 Forward direction is captured in the [Weftlet 2.0 product plan](WEFTLET-2.0-PLAN.md):
 consumer hardening, cited code-derived drafts, scoped approvals and reconciliation, an optional
 review website, source publication, managed AI and guided setup. “2.0” is a planning label;
-the published packages remain 0.2.0. The received consumer findings are tracked in the
-[consumer hardening and 1.0 task list](RELEASE-1.0-PLAN.md): first release the blocking
-document-identity patch, then address setup, reuse, diagnostics and document coverage before
-official 1.0 acceptance. The 2.0 plan distinguishes proposed work from delivered capability.
+the verified release at this checkpoint is 0.3.0. The received consumer findings are tracked in the
+[consumer hardening and 1.0 task list](RELEASE-1.0-PLAN.md): the document-identity patch is
+published and passes upstream checks; genuine consumer acceptance remains pending. T02's
+no-model preview and T05's cold-validation improvement shipped in 0.3.0. Operational cache reuse
+and timeout diagnostics are development increments; document coverage and other acceptance work
+remain open before official 1.0.
+The 2.0 plan distinguishes proposed work from delivered capability.
+
+The maintainer reported SHACL pushing generation past a 30-minute timeout before graph
+publication. T02 and the focused T05 optimization shipped together in 0.3.0 through
+[release PR #19](https://github.com/jchewitt/weftlet/pull/19), following local and hosted
+Ubuntu/Windows checks and independent source/archive review. A genuine consumer re-run is
+still required; the remaining 1.0 features did not delay this performance release.
+
+[Hydration planning](ADR-016-hydration-preview.md) shares committed selection and semantic cache
+identity with execution, reports human/JSON scope and work estimates, and preserves source versus
+assertion authority. It performs no model work or graph writes. The current JavaScript validator
+still checks the complete in-memory N3 graph on each hydration; saved queries do not repeat
+validation. [The T05 union optimization](ADR-017-shacl-validation-union.md) indexes all SPO triples
+in one temporary validation graph, preserving the same shapes and canonical named evidence.
+Bounded public experiments measured substantial cold-path improvement, alongside about 1.3 GiB
+RSS in the prototype at 10,000 unique-node facts; the production harness including serialization
+peaked near 1.6 GiB. They do not reproduce the private consumer's overall timeout.
+Early checks, in-phase progress, result reuse and incremental validation remain open; no Rust
+engine, graph database or validation-result cache is introduced by this focused release.
+
+[T03 operational cache reuse](ADR-018-operational-semantic-cache.md) is merged with local and
+hosted checks passing and is not part of published 0.3.0. Built-in Codex user
+artifacts can survive changes to timeout/retry/concurrency/document/byte limits while snapshots
+retain their full configuration identity. Exact legacy reads and explicit no-model adoption
+preserve prior artifacts; custom providers remain conservative.
+[T04 diagnostics](ADR-019-semantic-failure-diagnostics.md) add safe failure reports, opaque source
+mapping and accurate settled progress without changing extraction/cache identity. T04 is merged
+with local and hosted Ubuntu/Windows checks passing; release remains pending. Broader T05 and
+T06/T07 work remain open.
+
+A subsequent 0.3.0 consumer report makes [T08 physical-file kind consistency](ADR-020-canonical-physical-file-producers.md)
+the next release priority. Its neutral contract consumer fix and public core factory are merged
+with deterministic producer adoption, version guards and passing local/hosted Ubuntu/Windows
+checks. Publication is pending; the consumer's framework adapter migration and full acceptance
+remain consumer-owned.
+This fix preserves semantic artifacts and does not reinterpret model assertions to hide conflicts.
 
 | Milestone | Delivered and checked | Remaining limits |
 | --- | --- | --- |
@@ -97,7 +138,7 @@ preparation/publication under `@launch-echo`; the maintainer completed the 0.1.0
 source-application reintegration remain outside the authorized scope. See [release instructions](RELEASING.md).
 
 The maintainer authorized the Weftlet migration on 2026-10-21. Both `@weftlet/core` and
-`@weftlet/toolkit` are published at 0.2.0 through GitHub OIDC; the publication and verification
+`@weftlet/toolkit` are published at 0.3.0 through GitHub OIDC; the publication and verification
 record is in [validation](VALIDATION.md). Changesets prepares reviewed version PRs for the fixed package group;
 merging a release plan triggers publication and package-specific tags/GitHub Releases.
 See [ADR 009](ADR-009-release-automation.md) and [release instructions](RELEASING.md).

package/docs/VALIDATION.md

@@ -8,7 +8,309 @@ The milestone entries below record the original cloud checks. Subsequent
 establishes live Codex success on Windows and the full deterministic checks on WSL,
 while identifying remaining native Windows issues.
 
-## Repository document identity patch, 2026-10-26
+## T08 deterministic physical-file kinds, 2026-10-26
+
+Implemented after 0.3.0; this checkpoint does not claim npm publication or private consumer
+acceptance. [ADR 020](ADR-020-canonical-physical-file-producers.md) separates the neutral fix from
+the consumer-owned framework adapter migration. The reported 120-ID partition is consumer
+evidence; the upstream tests below are independent public reproductions, not that private replay.
+
+- Local `pnpm context-graph:publication-check` passed: 384 deterministic tests (17 core,
+  367 toolkit), one optional OML skip, 13 advisory architecture findings, inventory, licenses and
+  fresh packed-consumer checks. No rule, baseline, exception or SHACL shape was relaxed.
+- Sixteen new core cases verify the exported pure physical-file mapping, exact path spelling,
+  document/test/production distinctions and absence of inferred existence or intent. The package
+  retains no runtime package dependencies. Its public JS/declaration assets are required in the archive.
+- Three public composition cases use actual file and contract extraction from committed Prisma
+  schema/production/spec/test/Markdown consumers, actual bundled SCIP indexing and document links.
+  They assert exact retained citations/digests, confidence, authority and conceptual contract IDs.
+  A kind-only historical control restores the old Component label on an actual test-consumer fact
+  and fails strict SHACL; unchanged current producer output conforms. This control is not claimed
+  as execution of the installed 0.3.0 package. A public adapter-shaped fixture imports only core's
+  factory for its physical nodes; it is not the private framework implementation.
+- The overlay case reindexes real source changes without routing configured, retains canonical
+  kinds/draft authority, and proves its new identity differs from the frozen 0.3.0 formula.
+  A separately labeled retained-inference fixture still fails strict SHACL when incompatible;
+  previous heads, snapshots and assertion bytes remain intact. It is neither rewritten nor suppressed.
+- Routing and governance regressions compose real producer facts with neutral extraction and
+  strict SHACL. They retain routing binding IDs, provenance/authority and architectural attributes;
+  document endpoints join canonical Document identities, test files remain Evidence, and business
+  module/contract identities stay separate. Governance analyzer 3 differs from the frozen prior ID.
+- Twelve compatibility cases reject old/missing assembly, contract, SCIP-fact and configured
+  routing metadata for current validation. Production application tests still query historical
+  facts unchanged at the same commit/configuration, label extraction incompatibility separately
+  from checkout staleness, and invoke no provider, indexer, hydration or graph refresh.
+- Existing hydration/reuse/rename/delete tests pass with graph-v7 and preserve older snapshot
+  records. Semantic artifact/provider/prompt identity stays unchanged; no model call or private
+  cache rewrite is required by this deterministic fix. Non-document model kinds remain unreviewed
+  assertions and can still fail strict SHACL; this increment does not silently reinterpret them.
+- Fresh packed installation checks a public `@weftlet/core` adapter import against actual neutral
+  contract test-consumer facts, strict SHACL, real SCIP, RDF/SPARQL projection, CLI/npx and MCP.
+  Independent review found no remaining blocker. All 79 original source path/hash pairs are intact.
+
+[PR 27](https://github.com/jchewitt/weftlet/pull/27) merged at
+`7b3b0a4af260a6fa70f1107b3c5c315826c22c0e`. Exact feature head
+`493c68faada31f35e4c7dd5d047e70ac5c96b2ad` passed hosted Ubuntu and native Windows checks
+in [push run 40420049204](https://github.com/jchewitt/weftlet/actions/runs/40420049204) and
+[PR run 40420084937](https://github.com/jchewitt/weftlet/actions/runs/40420084937).
+Publication is pending the separately reviewed 0.4.0 release. No private application files
+or installed consumer packages were modified. The consumer must upgrade both released packages,
+migrate/version its framework extractor, run composed adapter tests, then complete full hydration
+and repeat acceptance before its adoption blocker can be declared resolved.
+
+## T04 semantic failure diagnostics, 2026-10-26
+
+Implemented in development source after 0.3.0; no new npm publication is claimed.
+[ADR 019](ADR-019-semantic-failure-diagnostics.md) records the safe failure envelope, opaque
+source correlation, settled progress and recovery boundaries. T04 does not change prompts,
+artifact keys, source/assertion authority, timeout defaults or graph validation.
+
+- Local `pnpm context-graph:publication-check` passed: 351 deterministic tests (1 core,
+  350 toolkit), one optional OML skip, inventory, licenses and fresh packed-consumer checks.
+- 20 new application cases use committed public fixtures and real artifact/snapshot storage.
+  They cover retained completed work, resumed reuse, cache hits, timeout/root-cause ordering,
+  synchronous sibling cancellation, late provider results, in-flight writes, late storage failure,
+  cancellation between sources and final completed/remaining counts. The previous snapshot/head
+  remains intact after failure. An injected Codex runner verifies elapsed time across retries
+  is separate from the configured per-attempt limit; no real model is called.
+- Unknown provider messages, private abort reasons and unrecognized error codes are excluded
+  from public reports. Missing infrastructure, invalid output, unresolved mappings, low confidence
+  and cache problems retain distinct safe diagnoses. The existing RDF regression now checks the
+  typed unresolved-policy error and unchanged prior head; its positive, missing-link, contradiction
+  and full SHACL checks remain in place.
+- Four CLI subprocess cases cover actual module timeouts, unknown module errors, missing provider
+  infrastructure, source-ID mapping through local preview, progress/error privacy, empty failure
+  stdout, JSON-only stderr with `--quiet`, and preserved previous snapshot bytes. The installed
+  consumer verifies public error/helper exports, required runtime assets, matching preview IDs and
+  safe structured failure from an unavailable provider. Existing installed CLI/npx, real SCIP,
+  RDF/SPARQL/SHACL, viewer and MCP initialization/missing-snapshot checks pass.
+- Governance reports 13 advisory findings: the 12 prior findings plus a new `semantic.ts` size
+  signal (510 nonblank/noncomment lines against the 500-line threshold). Independent review
+  considered the addition; scheduling/reporting is separated into its own module. The warning
+  remains visible. No rule, baseline or exception was changed; line count is not proof of
+  modularity or a product violation.
+- Independent review found no remaining blocker. All 79 original source path/hash pairs are
+  unchanged. [PR 25](https://github.com/jchewitt/weftlet/pull/25) merged at
+  `a919b82eab35808985d5c497bbe59ccfcba8bfcb`. Exact feature head
+  `a755dcdd2c0f97a7507f02f64b907a231162bf78` passed hosted Ubuntu and native Windows checks
+  in [push run 40417172248](https://github.com/jchewitt/weftlet/actions/runs/40417172248)
+  and [PR run 40417209468](https://github.com/jchewitt/weftlet/actions/runs/40417209468).
+  Both runs completed successfully; the Windows suite includes the new application/CLI failure
+  tests and existing provider/process tests, plus inventory and license checks.
+
+These checks use public deterministic fixtures and local child processes, not live models or
+private consumer data. Genuine consumer acceptance remains separate. Native Windows is covered
+by the hosted runs above; the local run is Linux/Node 24.19.0/pnpm 10.18.2.
+Published packages remain at 0.3.0 at this checkpoint. Broader T05, T06 and T07 remain separate
+1.0 increments.
+
+## T03 operational semantic-cache reuse, 2026-10-26
+
+Implemented in development source after 0.3.0; no new npm publication is claimed here.
+[ADR 018](ADR-018-operational-semantic-cache.md) records the built-in Codex user-cache partition,
+the five operational settings that may share artifacts, and conservative custom-provider behavior.
+Snapshot profiles, full configuration digests, workspace paths and the 0.2.1/0.3.0 artifact-key
+contract remain unchanged. No credential environment values are read to construct cache identity.
+
+- [PR 22](https://github.com/jchewitt/weftlet/pull/22) merged at
+  `5b889854e8a4b3a84653770e3244dee39d4b7d37`. Exact feature head
+  `c92689699fb09c80246edd61b692fca086ff6e83` passed hosted Ubuntu and focused native Windows
+  checks in [push run 40411921483](https://github.com/jchewitt/weftlet/actions/runs/40411921483)
+  and [PR run 40411954882](https://github.com/jchewitt/weftlet/actions/runs/40411954882).
+  Both runs completed successfully; Windows includes all four new cache test suites plus
+  inventory and license checks. Independent review found no remaining blocker. All 79 original
+  source path/hash pairs remain unchanged.
+- Local `pnpm context-graph:publication-check` passed: 327 deterministic tests (1 core,
+  326 toolkit), one optional OML skip, 12 existing advisory architecture findings, inventory,
+  licenses and fresh packed-consumer checks. No new architecture baseline or exception was added.
+- 28 configuration cases distinguish supported operational/default settings from model/policy/
+  authentication descriptors, unknown fields, repository/checkout and custom-provider changes.
+  The full snapshot storage profile still changes when its configuration changes.
+- 11 integration/storage cases cover an interrupted run followed by a longer timeout: the
+  completed source is reused, the unfinished source is extracted, and the new snapshot records
+  the complete current configuration. Old-configuration evidence fails current snapshot checks;
+  a saved query can still label it as historical. An actual application hydration uses real
+  bundled SCIP and cached semantic artifacts with a tripwire against unexpected Codex calls.
+- Legacy fixtures independently reproduce the frozen 0.3.0 profile/key formulas. Planning
+  neither copies artifacts nor creates directories; hydration promotes only validated entries
+  from the exact compatible legacy profile. Unrelated profiles and incomplete temporary files
+  are ignored. Old artifact bytes, raw output and provenance remain intact.
+- 21 adoption cases exercise explicit previous-config recovery, dry-run/index/filesystem
+  preservation, current and historical agent scope, budgets, source changes and omitted coverage.
+  Incompatible policies, authentication descriptors, unknown fields, providers and checkouts are
+  refused. Corrupt, unreadable and conflicting entries are reported without overwriting them.
+- Concurrent-writer tests cover matching/different outputs and malformed identity metadata with
+  a deceptively matching output-digest field. Both adoption and hydration promotion fully inspect
+  the retained entry before claiming success. Forced extraction preserves the old artifact.
+- Three CLI subprocess cases verify that adoption runs before provider/adapter initialization,
+  preserves the active checkout, supports historical refs, rejects malformed invocation, and
+  returns structured nonzero results for cache or budget problems. The fresh packed consumer
+  checks the public API/runtime helpers and installed adoption command with unavailable provider
+  and adapter modules; its dry run selects the committed source without storage writes.
+
+These are public deterministic fixtures, including an injected Codex runner, not live model
+extractions or private consumer acceptance. Existing full SHACL and fresh snapshot publication
+remain required after cache reuse. Published packages remain at 0.3.0 at this checkpoint;
+the minor changeset is pending a separate release. T04 timeout diagnostics and the remaining
+1.0 work are separate increments.
+
+## Weftlet 0.3.0 preview and SHACL performance release, 2026-10-26
+
+T02 and the focused cold-validation portion of T05 shipped ahead of the remaining 1.0 work.
+Both `@weftlet/core@0.3.0` and `@weftlet/toolkit@0.3.0` are public npm `latest` at this
+checkpoint. Core advances with the fixed release group and has no code change in this release.
+
+- [Preview PR 18](https://github.com/jchewitt/weftlet/pull/18) merged at
+  `63c70f85b26a6cc60f8bc0615a86f6042a61ecd0`.
+  [SHACL PR 20](https://github.com/jchewitt/weftlet/pull/20) merged at
+  `e45fda59037293a6ded20da70b812bbd385500a5`. Its final head
+  `ec7bb87ea3287a6322eeb09fa72ba53b3f1eec4e` passed hosted Ubuntu and focused Windows
+  checks in [run 40402839679](https://github.com/jchewitt/weftlet/actions/runs/40402839679)
+  and [run 40402826889](https://github.com/jchewitt/weftlet/actions/runs/40402826889).
+- [Release PR 19](https://github.com/jchewitt/weftlet/pull/19) advanced both versions to 0.3.0.
+  Exact head `897e731222180cc58ccf8acfe9cc2cd6252245b5` passed local `pnpm release:prepare`
+  and [dispatched Ubuntu/Windows checks](https://github.com/jchewitt/weftlet/actions/runs/40403315203).
+  The bot's automatic PR run required GitHub approval and ran no jobs; the explicit dispatch
+  validated that same head. The version PR contains only generated release metadata/changelogs
+  and consumed changesets, with no implementation changes.
+- [Trusted-publishing run 40403950446](https://github.com/jchewitt/weftlet/actions/runs/40403950446)
+  completed preparation, publication and release records on attempt 1 at merged commit
+  `ffc332adb84b8f9e854370ff4799aab32e189356`. Both package-specific tags and GitHub Releases
+  identify that commit, and main's package versions agree with npm.
+- Local publication checks passed 264 deterministic tests (1 core, 263 toolkit), one optional
+  OML skip, 12 existing advisory architecture findings, inventory, licenses and fresh packed-consumer
+  CLI/npx/MCP, preview, real SCIP, RDF/SPARQL/SHACL and viewer checks. Independent code review
+  found no remaining blocker. No shape, assertion, baseline or exception was removed or added to
+  conceal a failure. The 79 original source path/hash pairs remain unchanged.
+- Independent archive review covered core's 11 entries and toolkit's 196 entries. Runtime assets,
+  declarations, examples, README, Apache license and attribution/notices are present. No Git state,
+  credentials, caches, private consumer payloads or compiled tests were included. Toolkit's packed
+  core dependency is `^0.3.0`. Public archives match both the hosted prepared archives and locally
+  reviewed archives byte for byte. Public SLSA provenance subjects match their SHA-512 hashes and
+  identify the expected source, repository, `publish.yml` and workflow attempt. This is a provenance
+  content/source check, not a separate cryptographic signature audit.
+- A fresh Linux/Node 24.19.0 consumer installed only toolkit 0.3.0 directly from npm with
+  `--ignore-scripts`; core resolved transitively to 0.3.0. Both package-lock registry URLs and
+  integrity hashes matched the reviewed archives. The public two-document fixture retained
+  2 semantic facts within 17 total facts, including 4 real SCIP facts. Impact returned 17 facts;
+  SPARQL returned four canonical document references. Cold hydration extracted 2/reused 0;
+  the repeat extracted 0/reused 2 with identical snapshot identity, content digest and bytes.
+- Installed cold/warm `hydrate --plan --json` worked with the provider module unavailable,
+  reported 2 expected extractions then 2 reusable artifacts, preserved source authority and
+  performed no preview storage writes or provider calls. Saved queries still worked with the
+  provider disabled. Hydration used a deterministic fixture provider; no external model calls
+  were made during these checks.
+
+The installed public `RdfEvidenceGraph.validate()` also passed bounded, fresh-process public
+synthetic checks, preserving exact canonical serialization:
+
+| Facts / topology | Original quads | Validation including union | Whole-process maximum RSS |
+| --- | ---: | ---: | ---: |
+| 2,000 unique | 56,003 | 0.632 s | 492 MiB |
+| 10,000 unique | 280,003 | 2.903 s | 1,640 MiB |
+
+These are single-run synthetic measurements. Memory includes imports, fixtures and serialization;
+the extra union has a material memory cost. This installed-package probe ran on Linux; hosted
+Windows covers the new parity tests separately. Neither establishes the private consumer's total
+generation time. Full consumer hydration/repeat acceptance, live semantic quality, broader T05
+progress/reuse work and the remaining [1.0 tasks](RELEASE-1.0-PLAN.md) remain open. The SHACL
+change preserves compatible 0.2.1 semantic artifacts and does not require forced re-extraction.
+
+## T05 cold SHACL validation improvement, 2026-10-26
+
+Pre-release source checkpoint following the T02 preview merge; npm was still at 0.2.1.
+The subsequent 0.3.0 publication is recorded above. [ADR 017](ADR-017-shacl-validation-union.md)
+records the measured graph-wildcard lookup cost and the temporary all-triples union used by the
+unchanged JavaScript SHACL validator. The canonical named dataset and every assertion remain intact.
+
+Public synthetic production measurements use Linux/Node 24.19.0, N3 2.7.2 and
+rdf-validate-shacl 0.6.5. Each case ran once in a fresh child process with a 45-second hard deadline:
+
+| Facts / topology | Nodes / original quads | Canonical construction | Production validation, including union | Whole-process maximum RSS |
+| --- | --- | ---: | ---: | ---: |
+| 2,000 unique | 4,000 / 56,003 | 0.194 s | 0.779 s | 490 MiB |
+| 10,000 unique | 20,000 / 280,003 | 1.091 s | 2.920 s | 1,638 MiB |
+
+Both production cases conform and retain the exact before/after serialized dataset digest.
+The original-path public experiment measured 31.502 seconds of SHACL for the 2,000-fact unique
+case; its 5,000-fact shared case produced no verdict before the 45-second process deadline.
+The ADR records those separate prototype measurements and their boundaries. These are single-run
+measurements, not latency guarantees or a reproduction of the consumer's complete 30-minute run.
+Memory includes libraries, fixture generation and before/after serialization; the production
+harness peaked near 1.6 GiB at 10,000 unique facts. Its legacy comparison also reparses a second
+named store, so its RSS must not be treated as an old-versus-new production memory comparison.
+
+Reproduce from a built source checkout with
+`pnpm benchmark:shacl --counts 2000,10000 --topologies unique --modes optimized`.
+The bounded harness records runtime, build hashes, sizes, phase timings, conformance and
+serialization preservation. It exercises the public production validator; no private-store mutation,
+provider call or private consumer data is used. A small paired legacy/optimized smoke agreed;
+a 1 ms deadline probe killed the children and correctly reported no verdict.
+
+Local `pnpm context-graph:publication-check` passes: 264 deterministic tests (1 core,
+263 toolkit), one optional OML skip, 12 existing advisory architecture findings, source inventory,
+licenses and fresh packed-consumer CLI/npx/MCP, preview, real SCIP, RDF/SPARQL/SHACL and viewer
+checks. All 79 original source path/hash pairs remain unchanged. No architecture baseline or
+exception was added. The new internal shape module is required in the packed runtime inventory.
+
+The 25 new regressions compare complete normalized diagnostics with direct validation of the
+original named dataset. Cases cover empty/duplicate input, kinds, authorities, confidence and
+citation bounds/types/order, empty provenance fields and colliding fact IDs. Separate assertions
+preserve exact serialization, named-graph attributes/citations/review state and `facts()` through
+repeated validation. A 2,200-fact case detects the invalid final assertion without timing gates.
+The existing full hydration integration still verifies that failed SHACL preserves the last head.
+The shape Turtle is byte-for-byte unchanged from the T02 merge; no shape or assertion was dropped.
+
+Hosted checks and release status were pending at this source checkpoint; their results are above.
+Early identity preflight, in-phase progress, validation-result reuse and incremental validation
+remain separate work. Each hydration still performs full SHACL before publishing; saved queries
+do not repeat validation. Private consumer full hydration/repeat acceptance remains pending.
+
+## T02 no-model hydration preview, 2026-10-26
+
+Pre-release source checkpoint, while npm was still at 0.2.1. Subsequent 0.3.0 publication is above. See
+[ADR-016](ADR-016-hydration-preview.md) for source, cache and readiness semantics.
+
+[PR 18](https://github.com/jchewitt/weftlet/pull/18) merged at
+`63c70f85b26a6cc60f8bc0615a86f6042a61ecd0`. Its final head
+`6711362f9ff234d65ac3101dcf3ec0b0033519ec` passed hosted Ubuntu and Windows checks in
+[run 40400487168](https://github.com/jchewitt/weftlet/actions/runs/40400487168) and
+[run 40400478490](https://github.com/jchewitt/weftlet/actions/runs/40400478490).
+An earlier Ubuntu run exposed a temporary-fixture cleanup race; disabling automatic Git
+maintenance in that fixture and bounded cleanup retries resolved it before merge.
+
+- Local `pnpm context-graph:publication-check` passed: 239 deterministic tests (1 core,
+  238 toolkit), one optional OML skip, 12 advisory architecture findings, inventory, licenses
+  and fresh packed-consumer checks. No additional architecture baseline or exception was added.
+- Ten independent-repository planner cases cover exact committed bytes despite dirty/untracked
+  files, unchanged Git index and filesystem hashes, approved sources versus unreviewed assertions,
+  explicit evidence-root classification, empty selection, cold/warm/forced cache, malformed or
+  unreadable artifacts, output-digest corruption, budgets, duplicate IDs, missing selectors and
+  historical agent selection with explicit omissions. The warm test independently checks the
+  literal released 0.2.1 key formula, then verifies actual SemanticHydrator reuse.
+- Two real-process CLI cases cover human/JSON output, blocked and warning-only exit codes,
+  historical refs and force preview. Side-effecting provider/adapter modules are never imported;
+  unavailable Codex/SCIP/OML configuration does not prevent planning. Source bodies/raw provider
+  output are excluded from the plan. No snapshot or artifact directory is created by preview.
+- Existing hydration rename/delete tests still pass, including removal of the last document.
+  Explicit empty semantic scope now performs zero semantic extraction even with committed docs
+  present. New graph-v6 snapshots remain distinct from old assemblies; valid semantic cache keys
+  and output digests retain the 0.2.1 contract.
+- A fresh packed consumer exercises installed `hydrate --plan --json` with absent provider and
+  repository adapter modules, selects its committed document, reports one expected extraction,
+  and creates no graph storage. The public planner export and every runtime helper are present.
+  The remaining installed smoke covers real SCIP, RDF/SPARQL/SHACL, visualization and MCP.
+- Independent review found and resolved an initial selector-gating regression: unmatched selectors
+  are warnings, preserving deletion behavior. Incomplete preview scope needs review and exits 1;
+  it does not establish a new execution policy. No blocking review finding remains.
+
+No paid/live model call, npm publication or private source-application change was made for T02.
+Recursive document coverage and operational-config cache reuse remain separate. This increment
+does not optimize SHACL. The maintainer's report that validation pushes generation past a
+30-minute timeout makes [T05](RELEASE-1.0-PLAN.md#t05--detect-inexpensive-conflicts-early-and-explain-validation-work)
+the next focused release priority; no consumer timing diagnosis is claimed here.
+
+## Weftlet 0.2.1 document identity patch, 2026-10-26
 
 The public reproduction confirms the reported 0.2.0 defect: two unchanged semantic
 assertions give one repository document ID different kinds and fail single-kind SHACL.
@@ -16,6 +318,23 @@ assertions give one repository document ID different kinds and fail single-kind
 cache contract and immutable snapshot migration. The consumer follow-ups are tracked in
 the [1.0 plan](RELEASE-1.0-PLAN.md).
 
+[Fix PR 15](https://github.com/jchewitt/weftlet/pull/15) was validated at
+`42ba9b79dc0562a412cd5a048e42b77234530d94` by both hosted Ubuntu/Windows runs
+[40381728487](https://github.com/jchewitt/weftlet/actions/runs/40381728487) and
+[40381772577](https://github.com/jchewitt/weftlet/actions/runs/40381772577).
+[Release PR 16](https://github.com/jchewitt/weftlet/pull/16) advanced both package versions
+to 0.2.1. Its exact head `da07772110d4c762e3178a7345b426263e14a22f` passed local
+`pnpm release:prepare` and the explicitly dispatched
+[Ubuntu/Windows checks](https://github.com/jchewitt/weftlet/actions/runs/40382270147).
+The bot PR's separate automatic run required GitHub approval; the dispatched run tested
+that same commit and completed successfully.
+
+[Trusted-publishing run 40382864083](https://github.com/jchewitt/weftlet/actions/runs/40382864083)
+completed on attempt 1 at merged commit `5d1db91bf19ed493a20849b2d0f92d3aeac35dfe`.
+Both public npm `latest` tags resolve to 0.2.1. Package tags `@weftlet/core@0.2.1`
+and `@weftlet/toolkit@0.2.1`, plus their GitHub Releases, identify that exact commit.
+Main's package versions match the publication.
+
 - Local `pnpm context-graph:publication-check` passed: 227 deterministic tests (1 core,
   226 toolkit), one optional OML skip, 12 advisory architecture findings, inventory,
   licenses and a fresh packed-consumer CLI/npx/MCP, real SCIP and RDF/SHACL smoke.
@@ -31,12 +350,31 @@ the [1.0 plan](RELEASE-1.0-PLAN.md).
   mentioned in plain prose retains a cited implementation-gap diagnostic.
 - Independent review found and resolved that missing-path diagnostic regression. No blocking
   findings remained. All 79 original imported source paths and source hashes are preserved.
+- Independent release review inspected the actual core/toolkit archives (11/184 file entries),
+  generated versions, changelogs and plan. Runtime assets, public examples and licenses/notices
+  are present; no Git history, credentials, caches or private consumer report data were included.
+  The packed toolkit dependency is `@weftlet/core: ^0.2.1`.
+- Public npm archives match the hosted prepared archives and locally reviewed archives byte
+  for byte. Public SLSA provenance subjects match the SHA-512 archive hashes and identify this
+  source commit, repository, `publish.yml` and workflow attempt. This checks provenance content
+  and source identity, not a separate cryptographic signature audit.
+- A fresh Linux/Node 24.19.0 public-registry consumer installed only toolkit 0.2.1 directly
+  (`npm install --ignore-scripts`); core resolved transitively to 0.2.1. Both package-lock
+  registry URLs and integrity hashes matched the reviewed archives. The installed CLI
+  initialized and validated an independent public fixture with two source documents. A
+  deterministic provider reproduced the legacy conflicting classifications: hydration retained
+  2 semantic facts within 17 total facts, including 4 real SCIP facts, and SHACL conformed.
+  Cold hydration extracted 2/reused 0; the repeat extracted 0/reused 2 with unchanged snapshot
+  identity, content digest and bytes. Impact returned 17 facts and SPARQL returned the four
+  canonical document references. Saved queries still worked after the provider was disabled.
+  No live model call was made.
 
 These are deterministic upstream checks, not live semantic-quality or private consumer
 acceptance results. The consumer's full hydration was stopped after its isolated reproduction;
 no complete consumer SHACL verdict or published snapshot is claimed. Full-graph validation
-latency remains a separate investigation. Release and hosted-check evidence will be recorded
-after the patch completes the normal publishing workflow.
+latency remains a separate investigation. The first refresh requires new semantic extraction;
+historical cache/snapshot files should be retained. T01's upstream patch is published, while
+genuine consumer acceptance and the remaining T02–T07 work are still pending.
 
 ## Weftlet 0.2.0 publication, 2026-10-26
 

package/docs/WEFTLET-2.0-PLAN.md

@@ -1,7 +1,8 @@
 # Weftlet 2.0 product plan
 
 Status: proposed direction captured at the maintainer's request on 2026-10-26.
-Baseline: published `@weftlet/core` and `@weftlet/toolkit` **0.2.0**, with release evidence in
+Planning baseline: published `@weftlet/core` and `@weftlet/toolkit` **0.2.0**. The consumer
+identity fix has since shipped in **0.2.1**, with release evidence in
 [VALIDATION.md](VALIDATION.md). **“2.0” names this product plan; it does not announce npm
 version 2.0.0, a delivery date, or a single large release.** Changes should ship through small,
 reviewed milestones using the existing Changesets workflow.
@@ -48,15 +49,15 @@ Existing gap reports do not establish completeness of a project's business requi
 
 The maintainer supplied a consumer integration report on 2026-10-26. The
 [consumer hardening and 1.0 task list](RELEASE-1.0-PLAN.md) records its seven items and acceptance
-criteria. First ship the blocking repository-document identity/kind fix as an isolated patch;
-then work through the other improvements toward an official 1.0. Ordinary reliability fixes
-ship independently of the companion platform described here.
+criteria. The repository-document identity/kind patch shipped in 0.2.1 and passes upstream
+regressions; genuine consumer acceptance remains pending. Work through the other improvements
+toward an official 1.0 independently of the companion platform described here.
 
 | Intake item | Status | Next action |
 | --- | --- | --- |
 | Consumer integration report | Received; task list recorded | Preserve private evidence with the consumer and use public-safe upstream reproductions |
-| Reproduction and severity | Identity/kind defect is the reported adoption blocker | Reproduce two-document conflict upstream; keep validation latency a separate investigation |
-| Fix/release mapping | Blocker patch in progress; remaining tasks planned | Release T01 first, then T02–T07 and genuine consumer acceptance before official 1.0 |
+| Reproduction and severity | Reported identity/kind blocker has a passing upstream regression | Obtain the genuine consumer re-run; keep validation latency a separate investigation |
+| Fix/release mapping | T01 upstream patch published in 0.2.1; T02–T07 remain open | Complete bounded follow-ups and genuine consumer acceptance before official 1.0 |
 
 For each finding, retain toolkit/version, repository SHA, relevant configuration and scope,
 exact command or MCP request, expected/actual behavior, logs/exit status, snapshot identity,
@@ -127,7 +128,7 @@ explicit migration ADR.
 
 | Milestone | Depends on | Deliverable and completion evidence |
 | --- | --- | --- |
-| **M0 — Consumer hardening** | Received report; [1.0 task list](RELEASE-1.0-PLAN.md) | Ship the identity/kind blocker patch first, then bounded setup/reuse/diagnostics/coverage improvements and genuine consumer acceptance. Release independently of the companion platform. |
+| **M0 — Consumer hardening** | Identity patch 0.2.1 shipped; [1.0 task list](RELEASE-1.0-PLAN.md) | Complete bounded setup/reuse/diagnostics/coverage improvements and genuine consumer acceptance. Release independently of the companion platform. |
 | **M1 — Claims, lineage and approvals** | M0 triage | Versioned records, durable derivation, revision-scoped approvals, actor trust and explicit legacy handling. Prove generated documents cannot acquire approval through paths or repeated extraction. Verify persistence/RDF/projection/query equivalence and old-snapshot readability. |
 | **M2 — Code-derived drafts** | M1 | Opt-in generation for selected TypeScript modules using existing local Codex first; structured candidate claims and Markdown rendered from those claims. Demonstrate no-doc and partial-doc fixtures with citations, unknown rationale, bounded cost, cache reuse and rename/delete invalidation. |
 | **M3 — Decisions and reconciliation** | M1–M2 | Capture explicit accepted requirements/decisions, compare changes from code and documents, distinguish scope differences from conflicts, and propose focused amendments. Demonstrate a resolved documentation disagreement with a remaining implementation gap. |
@@ -273,7 +274,7 @@ Resolve these decisions in small ADRs as their milestones approach:
 
 ## Next handoff
 
-1. Resolve and publish the identity/kind blocker patch under M0, then obtain a genuine consumer re-run.
+1. Obtain a genuine consumer re-run of the published 0.2.1 identity/kind patch under M0.
 2. Complete the remaining [1.0 tasks](RELEASE-1.0-PLAN.md) and review acceptance without waiting for the website or managed AI.
 3. Design M1's minimal records and compatibility rules, then implement M2 on bounded public fixtures.
 4. Review real extraction/review results before committing to hosted scope, paid operation or more adapters.