@weftlet/toolkit 0.2.0 → 0.3.0

package/docs/RELEASE-1.0-PLAN.md

@@ -0,0 +1,288 @@
+# Consumer hardening and the 1.0 release plan
+
+Status: maintainer-directed work; source checkpoint on 2026-10-26 before the planned 0.3.0 release.
+The report concerned `@weftlet/toolkit@0.2.0`. **T01's upstream patch shipped in 0.2.1**;
+genuine consumer acceptance remains pending. T02 is merged and awaits release. T05's focused
+cold-validation optimization is implemented in development source, with validation/release pending;
+its broader follow-ups and T03, T04, T06 and T07 remain open. These tasks improve setup, reuse, diagnostics and document coverage
+without expanding the consumer's migration. An official 1.0
+follows this work and genuine consumer acceptance, with its exact release scope reviewed when
+the evidence is available.
+
+This is the near-term release task list. The [Weftlet 2.0 product plan](WEFTLET-2.0-PLAN.md)
+remains a separate future direction for generation, approvals, a companion website and hosted
+AI. None of those platform features is a dependency of the fixes here.
+
+## Reported evidence and boundaries
+
+The consumer reported a cold extraction in which two source documents referred to the same
+repository Markdown document. Semantic assertions gave that one repository-path identity
+different node kinds, `Component` and `Document`. An isolated, unchanged two-fact graph failed
+the public RDF validator's single-kind constraint. The references describe the same document;
+this is an extraction identity conflict, not evidence of conflicting product intent.
+
+The consumer stopped its larger hydration after independently proving that failure. No full-run
+SHACL result or published snapshot is claimed. Several minutes spent in the larger validation
+phase is a separate observation; the two-fact reproduction does not diagnose its latency.
+Fresh-install checks and the package/adapter boundary were reported as successful.
+
+Private source paths, assertions, artifacts and application data remain with the consumer.
+Upstream work uses public-safe reproductions and preserves the original application's existing
+integration. Consumer acceptance is reported separately from upstream deterministic tests.
+
+## Task list and order
+
+| ID | Task | Priority/status | Dependencies and release boundary |
+| --- | --- | --- | --- |
+| **T01** | Coherent repository-document identity and kind | **Upstream patch shipped in 0.2.1; consumer acceptance pending** | SHACL and assertions preserved; genuine consumer re-run is still required |
+| **T02** | No-model hydration/setup preview | Merged in PR #18; not published in 0.2.1 | Shared selection/cache inspection, human/JSON plans; extend with T07 traversal coverage |
+| **T03** | Artifact reuse across operational configuration changes | Planned efficiency work | Preserve T01's semantic identity separation; keep snapshot/config identity distinct from reusable artifact identity |
+| **T04** | Actionable, privacy-safe timeout diagnostics | Planned diagnostics work | Use stable source identifiers and run progress; document recovery with T02/T03 |
+| **T05** | Early identity checks and validation progress/profiling | **Adoption blocker; cold-validation fix in source** | Validate and release union-projection optimization now; early checks, detailed progress and validation reuse remain open |
+| **T06** | Packaged release-documentation consistency | Open; README version pins removed in 0.2.1 | Automated archive/version consistency check remains to be implemented |
+| **T07** | Coverage-aware traversal from SOT/roadmap entry points | Planned bounded feature work | Use canonical identity from T01, preview from T02 and incremental reuse from T03; split selection/classification/extraction changes |
+
+T02 passed the local publication checks and hosted Ubuntu/Windows checks before
+[PR #18](https://github.com/jchewitt/weftlet/pull/18) merged. Prioritize the focused T05 performance
+release following the maintainer's reported timeout; do not wait for the remaining 1.0 features.
+T03, T04, T06 and T07 remain independently useful increments. Keep them
+separate from the optional platform work. Publication follows the normal release process; no new
+npm release is claimed for T02. Normal release checks apply to every shipped increment.
+
+## T01 — Resolve repository-document identity conflicts
+
+Define and enforce a coherent ID/kind policy for repository document references across semantic
+and deterministic extraction. A prompt instruction alone is insufficient when separately valid
+model outputs can conflict after assembly. Preserve both source assertions and their citations,
+source authority and assertion-review state. Retain single-kind SHACL validation; do not discard
+an assertion or relax the shape to conceal the conflict.
+
+Acceptance:
+
+- A public regression has two committed documents referring to the same Markdown document,
+  with one provider assertion labeling it `Component` and the other `Document` under the same
+  repository-path identity. Both assertions survive under the coherent policy and align with
+  deterministic document links; the assembled graph passes RDF/SHACL validation.
+- Verify subject and object references, preserved provenance and unreviewed/inferred assertion
+  authority. Other incompatible identities remain diagnosable rather than silently merged away.
+- Version the relevant extractor/prompt/cache identity so incompatible old artifacts cannot
+  satisfy a fresh extraction. Test a fresh build, subsequent artifact reuse and unchanged
+  snapshot identity/content on repeat input. Keep historical saved snapshots readable and unchanged.
+- Run the normal deterministic/publication gate and a fresh installed-package smoke. Publish
+  the patch, then request a genuine consumer re-run against the recorded inputs; do not infer
+  consumer acceptance from the upstream fixture.
+
+Upstream completion evidence:
+
+- [Fix PR #15](https://github.com/jchewitt/weftlet/pull/15) implements the policy in
+  [ADR 015](ADR-015-repository-document-identity.md), with public cross-document regressions and
+  fresh/cache-reuse coverage. [Release PR #16](https://github.com/jchewitt/weftlet/pull/16)
+  advances the fixed core/toolkit group to 0.2.1.
+- [Release run 40382864083](https://github.com/jchewitt/weftlet/actions/runs/40382864083)
+  completed preparation, publication and release records on its first attempt at commit
+  `5d1db91bf19ed493a20849b2d0f92d3aeac35dfe`. Required checks included 227 deterministic tests,
+  12 advisory architecture findings, fresh packed-consumer checks and hosted Ubuntu/Windows CI.
+- Registry archives, provenance and tags match the reviewed release. A fresh public-registry
+  consumer passes the two-document regression, real SCIP, RDF/SHACL, queries and unchanged
+  snapshot identity/content on artifact reuse, without live model calls. See the detailed
+  [validation record](VALIDATION.md) for commits, checks and result boundaries.
+
+The private consumer has not yet supplied a successful full hydration/repeat against 0.2.1.
+Upstream publication and regression success do not close that acceptance gate or diagnose the
+separate full-graph validation latency observation.
+
+## T02 — Preview scope and work without calling a model
+
+Implemented in development source: `hydrate --plan` renders a human summary and `--json` returns
+the structured plan. This feature is not in published 0.2.1. Shared source selection and identity
+logic report selected documents and sizes, inclusion reasons, configured role/source approval,
+unreviewed assertion status, artifact reuse/extraction estimates and document/per-source byte limits.
+See [ADR 016](ADR-016-hydration-preview.md) and [validation](VALIDATION.md).
+
+Missing or unsupported-only selectors and bounded agent omissions remain visible as warnings;
+incomplete plans need review and exit 1. They do not introduce new hydration gates that would
+break deletion of the last document. Budget, duplicate-ID and corrupt/unavailable cache errors
+block planning checks without truncating selected sources. An explicit empty source list selects
+none. Requested refs now govern agent scope; corrected snapshots use graph-v6 while valid 0.2.1
+semantic artifacts remain reusable. T03's operational cache changes and T07's traversal/default
+validation-document separation remain separate work.
+
+Acceptance:
+
+- Preview calls no provider and performs no extraction, indexing, snapshot publication or active
+  checkout mutation. Distinguish unavailable/corrupt cache entries from known reusable artifacts.
+- Identify the commit, configuration and selection assumptions; a later changed input can
+  invalidate the estimate. Report uncertainty explicitly instead of promising a cache hit.
+- Test empty/no-document scope, cold and warm artifacts, missing sources, budget violations and
+  semantic-identity changes. Provide machine-readable output and a concise human summary.
+- With T07, show complete inclusion/exclusion reasons, unresolved links, ownership/classification
+  gaps, coverage and budget effects before any model call. Do not silently trim the selection.
+
+## T03 — Reuse valid artifacts after operational changes
+
+The consumer reported that changing only a timeout selected a different cache profile and made
+completed extractions unavailable for reuse. Investigate both storage-location selection and
+artifact key construction. Separate operational controls from semantic-output identity, while
+retaining complete configuration metadata on snapshots and queries.
+
+Acceptance:
+
+- Changing supported operational settings such as timeout does not hide or invalidate an
+  otherwise reusable extraction. Explicitly classify each setting rather than assuming all
+  non-source changes are harmless; retain provider-specific extension behavior.
+- Changing source bytes/identity, model or relevant model settings, prompt/schema/extractor/
+  ontology identity, or other output-affecting policy invalidates reuse as required. T01's new
+  identity must not accidentally reuse old conflicting artifacts.
+- Preserve force-extraction semantics, concurrent-writer safety, isolation between consumers,
+  credentials and private cache contents. Record reuse and reasons for a miss without secrets.
+- Test interrupted work followed by a changed timeout: valid completed artifacts are reused,
+  incomplete/invalid ones are re-extracted, and source provenance remains correct.
+
+## T04 — Explain timeouts and recovery
+
+Report a privacy-safe source identifier, phase, elapsed time, configured limit and completed/
+remaining counts when extraction times out. Explain which completed artifacts can be retained
+and how to inspect the plan or adjust a bound before retrying. The documented two-minute default
+was insufficient for the reported workload; that observation alone does not select a new default.
+
+Acceptance:
+
+- Use a stable opaque identifier by default, with an explicit local mapping or opt-in detail for
+  identifying the source. Avoid leaking source text, full prompts, credentials or provider stderr.
+- Distinguish extraction timeout, cancellation, provider failure and infrastructure problems.
+  Preserve completed artifacts and the last valid published snapshot.
+- Test timeout/cancellation during a multi-source run, accurate progress counts, safe recovery
+  instructions and secret-free logs. MCP protocol stdout remains clean.
+
+## T05 — Detect inexpensive conflicts early and explain validation work
+
+The implementation uses JavaScript on Node:
+`rdf-validate-shacl` validates an in-memory N3 dataset. Hydration constructs and validates the
+entire assembled graph, including when semantic artifacts were reused. There is no persistent
+GraphDB backend or incremental validation. Querying a saved snapshot does not rerun SHACL.
+
+The maintainer reports that validation pushes the consumer's overall generation beyond its
+30-minute timeout, preventing snapshot publication and making adoption unusable. This is now
+a release blocker, not an optional observability improvement. Upstream has measured a specific
+named-graph lookup cost in public synthetic fixtures, but has not measured that consumer graph or
+diagnosed its complete timeout. Ship the focused performance release once its correctness and
+improvement are demonstrated, ahead of the remaining 1.0 tasks.
+
+[ADR 017](ADR-017-shacl-validation-union.md) records the implemented cold-validation optimization:
+build a temporary union of every SPO triple for the same validator/shapes, while keeping original
+named assertion graphs canonical for queries and serialization. It removes repeated wildcard
+lookups across one graph per fact. In a bounded single-run public 2,000-fact unique-node case,
+the original SHACL path took 31.502 seconds; union construction took 0.153 seconds and SHACL
+took 0.467 seconds. A 10,000-fact unique-node union case used about 1.3 GiB process RSS. These
+are synthetic phase measurements, not a private consumer reproduction or end-to-end guarantee.
+
+The focused change still validates the whole graph each time. It does not add Rust, GraphDB,
+incremental validation or a validation-result cache. Early checks and broader observability/reuse
+remain follow-ups rather than reasons to delay the cold-path fix. Native code or a database does
+not by itself establish faster or correct incremental SHACL.
+
+Acceptance:
+
+- Early errors identify the conflicting identity/kinds and relevant evidence using the configured
+  privacy policy. Preserve all underlying assertions for diagnosis; early checks are not a
+  substitute for RDF/SHACL validation.
+- Report elapsed time and honest progress for long validation. Current phase boundaries remain
+  the supported progress signal: the synchronous validator blocks same-thread timers. Evaluate
+  bounded worker execution before promising an in-phase heartbeat or cancellation; never display
+  a fabricated completion percentage when the validator exposes no meaningful denominator.
+- Record reproducible public-fixture sizes, fact/node counts, runtime versions, wall time and
+  resource observations for construction and validation separately. Separate measured bottlenecks
+  from hypotheses; include repeated identical input and small changed-input cases.
+- Demonstrate improved cold full-graph validation, because reusing a previous validation result
+  cannot unblock a first graph that has never completed. Keep private consumer acceptance and
+  the overall generation timeout separate from synthetic validator-only benchmarks.
+- Evaluate reuse of a successful conformance result only when validated graph content, shapes,
+  validator version and applicable policy/semantics match. This reuse must not make historical
+  evidence satisfy current-diff freshness, scope or provenance requirements.
+- Evaluate dependency-aware incremental validation with insertions, updates, deletions, renames,
+  affected relationships and global constraints. Revalidate the complete affected scope or fall
+  back to full validation when it cannot be bounded safely; changed nodes alone are insufficient.
+- Benchmark a suitable native/Rust-backed validator or optional persistent graph database if
+  measurements justify a candidate. Compare supported SHACL behavior, positive/negative parity,
+  installation, licensing, portability and maintenance cost. T02 adds no backend migration, and
+  this evaluation does not commit the standalone toolkit to a mandatory service.
+- Any optimized validation/projection path has equivalence tests, including negative cases;
+  failure must preserve the prior snapshot. Keep model-independent profiling separate from live
+  extraction performance and from the reported two-fact correctness defect.
+
+## T06 — Keep packaged documentation consistent with the release
+
+The consumer installed 0.2.0 while its packaged README still named 0.1.2 and some archive examples
+used 0.1.1. Release 0.2.1 removes the README version pins; immutable 0.2.0 archives retain their
+original text. The automated release-documentation consistency check remains open. Add that
+repeatable check rather than relying on manual edits alone.
+
+Acceptance:
+
+- Distinguish current setup/version statements and executable installation examples from valid
+  historical release evidence. Do not rewrite historical versions indiscriminately.
+- Validate current instructions against the actual prepared core/toolkit versions and tarball
+  contents before publication. Test both mismatches and intentionally historical references.
+- Define how versioning updates or generates current-release documentation so normal Changesets
+  bumps cannot silently leave it stale. Verify installation examples from fresh packed output.
+
+## T07 — Traverse canonical documents with explicit coverage and authority
+
+Start from configured SOT and master-roadmap entry points and recursively follow supported
+canonical Markdown links to owner/task documents. Resolve against the chosen repository commit,
+with cycle detection, canonical identities and deduplication. Report missing, ambiguous, outside-
+scope or unsupported links instead of inventing targets or automatically fetching external URLs.
+
+Extract requirements, business rules, constraints and cross-feature dependencies while retaining
+source citations and explicit ownership. Reaching a document through a link does not approve it.
+Routine implementation checklists and inferred plans cannot become approved intent through
+traversal. Classify sources/claims explicitly; flag rules without clear SOT ownership and retain
+their inferred/unreviewed state. Validation documents are excluded from product-intent extraction
+by default and retained through a separately classified validation-evidence path.
+
+Acceptance:
+
+- Split delivery into canonical selection/traversal, role/ownership classification and semantic
+  extraction/linkage increments. Keep the existing direct-source configuration usable.
+- The T02 preview exposes entry points, traversed paths, inclusion/exclusion reasons, roles,
+  approval/ownership state, unresolved links and exact budget/coverage limits without model calls.
+- Support cycles, shared targets, relative links/fragments and rename/delete cases without
+  duplicate extraction. Test cross-feature owner/task references and validation documents,
+  including mixed or ambiguous content that needs explicit classification.
+- Compute the necessary selection before scheduling model work. If limits prevent full requested
+  coverage, stop or require an explicit narrower scope/budget decision; never silently truncate
+  dependencies to fit a document count. Persist incomplete coverage and its reason where relevant.
+- Reuse unchanged extraction artifacts incrementally. Recompute reachability/classification when
+  links or configuration change; invalidate affected relationships and preserve removed-source
+  history. Partial failures retain completed artifacts and the last valid snapshot.
+- Prove cross-source linkage using extracted public prose and real code relationships, with
+  missing links, ambiguous ownership, conflicting claims and false cross-domain matches as
+  negative cases. Separate deterministic fixtures from budgeted live-provider evaluation.
+
+## Official 1.0 acceptance
+
+With T01's upstream patch published, work through T02–T07 in bounded increments and record implementation
+PRs and validation evidence here or in the linked validation record. Review the exact 1.0 scope
+against completed evidence; any deferral needs an explicit maintainer decision and must remain
+visible rather than being treated as done. The companion website, hosted AI and broader 2.0
+product plan remain separate.
+
+Before calling the consumer migration accepted or publishing 1.0:
+
+1. Confirm the patched identity policy in a genuine consumer hydration, including completed full
+   graph validation and snapshot publication, querying and an unchanged repeat. Keep provider
+   details, source scope and remaining gaps explicit; the consumer performs its own application work.
+2. Verify no-model scope preview, budget/coverage reporting, operational cache reuse and recovery
+   diagnostics against the implemented task scope. Exercise SOT traversal and authority separation
+   with public fixtures and reviewed consumer evidence.
+3. Pass supported-platform build/tests, fresh packed and public-registry installation, real
+   TypeScript indexing, RDF/SHACL, CLI/MCP, provenance and source-inventory checks. Check packaged
+   release instructions before publishing the exact reviewed archives.
+4. Record independently assessed usefulness and semantic-quality limits. Preserve the distinction
+   between deterministic checks, live-provider tests, browser checks and private consumer results.
+   Existing untested environments or deferred capabilities remain explicitly labeled.
+5. Review the changelog, compatibility/migration guidance and remaining known issues, then use the
+   normal reviewed version PR and trusted-publishing workflow. No 1.0 publication is claimed now.
+
+The patch's upstream pass is necessary but does not replace consumer acceptance. Track follow-up
+results without auditing or refactoring the source application's business logic from this repository.

package/docs/RELEASING.md

@@ -1,8 +1,27 @@
 # Weftlet npm releases
 
-`@weftlet/core@0.1.2` and `@weftlet/toolkit@0.1.2` are published. The first automatic
-release completed in [run 39672652013](https://github.com/jchewitt/weftlet/actions/runs/39672652013),
-including package tags and GitHub Releases at commit `3d8d1f38a9e70b38178921cdabf5e8714c417c1c`. Their first trusted
+`@weftlet/core@0.2.1` and `@weftlet/toolkit@0.2.1` are published through GitHub OIDC.
+[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
+stopped with Sigstore `TLOG_CREATE_ENTRY_ERROR` HTTP 409. Re-running failed jobs on the same
+workflow restored the prepared archives and acceptance receipt; attempt 2 completed without
+changing versions. See [validation](VALIDATION.md) for the verification record.
+
+The first automatic release, 0.1.2, completed in
+[run 39672652013](https://github.com/jchewitt/weftlet/actions/runs/39672652013),
+including package tags and GitHub Releases at commit `3d8d1f38a9e70b38178921cdabf5e8714c417c1c`. The first trusted
 publication passed in [run 39661957651](https://github.com/jchewitt/weftlet/actions/runs/39661957651)
 from commit `720a5f964fe3cb6c438be6d22b4aa8b4ad44de17`, with matching registry archive integrity,
 npm provenance and a fresh public CLI installation. Earlier Weftlet and `@launch-echo` releases
@@ -26,8 +45,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.1.2`
-   and `@weftlet/toolkit@0.1.2`, 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 →
@@ -140,7 +159,7 @@ Package-specific tags identify the exact published source, for example:
 
 ```sh
 git fetch --tags
-git switch --detach '@weftlet/toolkit@0.1.2'
+git switch --detach '@weftlet/toolkit@0.2.1'
 ```
 
 Tags support inspection and reproduction, not mutation of npm history. To roll a consumer back,
@@ -150,8 +169,8 @@ Verify a new public release in a fresh disposable project, substituting its vers
 
 ```sh
 npm init -y
-npx --yes @weftlet/toolkit@0.1.1 init --yes
-npx --yes @weftlet/toolkit@0.1.1 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,8 +1,38 @@
 # Delivery roadmap
 
+Source checkpoint: 2026-10-26, before the planned 0.3.0 release. Publication evidence is
+recorded separately 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 are 0.2.1. 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 is implemented in development source but is not in published 0.2.1. Cache reuse,
+diagnostics and document coverage remain open before official 1.0 acceptance.
+The 2.0 plan distinguishes proposed work from delivered capability.
+
+T05 now blocks adoption: the maintainer reports SHACL pushing generation past a 30-minute
+timeout before graph publication. T02 merged in [PR #18](https://github.com/jchewitt/weftlet/pull/18)
+after local and hosted Ubuntu/Windows checks. The focused T05 cold-validation optimization is
+implemented in development source, awaiting validation/release; the other 1.0 features must not
+delay it. Neither increment is in the published 0.2.1 packages.
+
+[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 at 10,000 unique-node facts. 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.
+
 | Milestone | Delivered and checked | Remaining limits |
 | --- | --- | --- |
 | 1. Standalone | Explicit committed inventory, core/toolkit boundary, public examples, build/tests, packed independent consumer and real TypeScript indexing | GitHub exported; both @launch-echo packages published at 0.1.0 and public installation verified |
@@ -89,8 +119,8 @@ 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.1.2 through GitHub OIDC, with provenance and a fresh public
-installation verified. Changesets now prepares reviewed version PRs for the fixed package group;
+`@weftlet/toolkit` are published at 0.2.1 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).
 Earlier Tently packages remain available and undeprecated.

package/docs/VALIDATION.md

@@ -8,6 +8,208 @@ 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.
 
+## T05 cold SHACL validation improvement, 2026-10-26
+
+Implemented in development source following the T02 preview merge. Published npm packages
+remain 0.2.1 until a separately recorded release succeeds. [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 remain pending at this source checkpoint.
+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
+
+Implemented in development source; published npm packages remain 0.2.1. 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.
+[ADR-015](ADR-015-repository-document-identity.md) records the canonical identity policy,
+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.
+- The new public regression uses two committed source documents and a deterministic
+  module provider that reproduces the conflicting classifications. Both semantic facts
+  retain their citations, confidence and separate source/assertion authority; deterministic
+  document links and SPARQL join the canonical document. Real TypeScript indexing and
+  SHACL pass. Fresh extraction reports 2 extracted/0 reused; repeat reports 0/2 with
+  identical snapshot identity/content digest. Raw provider output is preserved byte for byte.
+- Seeded artifacts using the released 0.2.0 cache-key formula are not reused or overwritten.
+  Historical graph-v4 snapshot bytes remain unchanged and readable. Subject references
+  normalize too; unrelated concept-kind conflicts still fail SHACL. A missing document
+  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. 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
+
+The maintainer authorized publication of both packages. [Release PR 4](https://github.com/jchewitt/weftlet/pull/4)
+committed their `0.2.0` versions to main at `ffe7f1d81f0421b35220bd7ba5b1555246c7a0e1`.
+[Trusted-publishing run 40344526047](https://github.com/jchewitt/weftlet/actions/runs/40344526047)
+completed successfully on attempt 2. Both npm `latest` tags resolve to `0.2.0`.
+
+- Exact release-PR head `a818ee6312f6970015cea66f55cf6bb2cc62e363` passed the
+  [dispatched Ubuntu/Windows checks](https://github.com/jchewitt/weftlet/actions/runs/40042137308).
+  Local `pnpm release:prepare` also passed 222 deterministic tests, one optional OML skip,
+  12 advisory architecture findings, inventory, licenses and fresh packed-consumer checks.
+  The publication workflow repeated preparation at the merged source commit.
+- Independent review checked the generated release plan, versions/changelogs, all 79 original
+  source identities and the actual archives. Core contains 11 entries and toolkit 179;
+  runtime assets, public examples and licenses/notices are present. No credentials, Git history,
+  caches or generated graph snapshots were included. Toolkit's packed core dependency is `^0.2.0`.
+- Both public npm tarballs match the hosted prepared archives byte for byte, and those hashes
+  match the locally reviewed archives. Public SLSA provenance subjects match their SHA-512
+  digests and reference this exact commit, repository and `publish.yml` workflow. This checks
+  provenance content and source identity; it is not a separate cryptographic signature audit.
+- Attempt 1 published and verified core, then toolkit's provenance submission failed with
+  `TLOG_CREATE_ENTRY_ERROR` / HTTP 409 for an equivalent transparency-log entry. The core
+  acceptance receipt and original archives were retained. Registry state was inspected before
+  rerunning only failed jobs in the same run. Attempt 2 completed toolkit publication using the
+  unchanged version/archives; core was already present. No provenance setting was disabled.
+- Package tags `@weftlet/core@0.2.0` and `@weftlet/toolkit@0.2.0`, and their public GitHub
+  Releases, point to `ffe7f1d81f0421b35220bd7ba5b1555246c7a0e1`. The release records contain
+  the verified archive digests. Main's package versions agree with npm.
+- A fresh public-registry consumer on Linux / Node 24.19.0 installed only
+  `@weftlet/toolkit@0.2.0` directly (`npm install --ignore-scripts`); core resolved transitively
+  to `0.2.0`. Both lockfile registry URLs and integrity hashes match the prepared archives.
+  CLI init/configuration and the npm-exec launcher passed. Real TypeScript indexing produced
+  15 SCIP facts within 22 total facts; the impact query returned 22 and SHACL conformed.
+  Repeat hydration preserved snapshot identity/content. Saved queries preserved snapshot bytes
+  and labeled excluded working edits. MCP initialized, discovered `impact.scan`, returned a
+  bounded 20-fact response and reported a missing snapshot as an error. No semantic documents
+  were selected: both hydrations extracted/reused zero artifacts, so this does not establish
+  model extraction or semantic artifact reuse.
+
+Live model/authentication quality, browser interaction and genuine fresh-task cloud restoration
+remain separate. No source application was changed and no live model call was made for release.
+
 ## Development workspace recovery, 2026-10-23
 
 The existing Codex development workspace became executable again at repository commit