@weftlet/toolkit 0.2.1 → 0.4.0

package/docs/ADR-018-operational-semantic-cache.md

@@ -0,0 +1,100 @@
+# ADR-018: Preserve Codex artifacts across operational configuration changes
+
+Status: accepted and implemented in development source after 0.3.0; release evidence is recorded
+in [validation](VALIDATION.md). This increment does not claim a new npm publication.
+
+## Problem
+
+With `storageScope: "user"`, the storage profile includes the entire configuration and checkout
+path. Increasing a timeout therefore selected a different directory even though the built-in
+Codex artifact key already excluded that timeout. A partially completed run could lose access
+to reusable work without any source or extraction-contract change.
+
+Custom provider modules present a different boundary: they receive the entire semantic
+configuration and may use it to affect their output. Their identities must remain conservative.
+
+## Decision
+
+Keep `resolveStorageRoot`, snapshot profiles, snapshot IDs and full configuration digests unchanged.
+For built-in Codex with user storage, use a separate semantic-artifact partition. Its identity
+includes the resolved checkout and full configuration except these five semantic controls:
+
+| Setting | Why it can share successful Codex artifacts |
+| --- | --- |
+| `timeoutMs` | Bounds execution; it does not change the prompt or model arguments |
+| `retries` | Limits retries of supported transient failures |
+| `concurrency` | Schedules independent source extractions |
+| `maxDocuments` | Bounds the selected workload |
+| `maxSourceBytes` | Bounds each source; it never truncates its contents |
+
+Document and byte limits still apply before hydration, including when every artifact is cached.
+Changing a limit does not waive it. Model/reasoning settings, prompt/schema/extractor/adapter/
+ontology identities, confidence/unresolved policy, authentication descriptors, source identity
+and bytes continue to invalidate reuse through their existing artifact keys and/or partition.
+Unknown configuration fields remain identity inputs. Credential environment values are not read
+or added to the cache partition.
+
+The new user-cache layout is `~/.cache/context-graph/semantic-artifacts-v1/<partition>/artifacts/semantic/`.
+The partition uses a full SHA-256 digest. Different checkouts, repository IDs, namespaces and
+non-operational configurations remain separate. Workspace storage retains its existing paths
+and behavior; it already allowed built-in Codex reuse after these operational changes. Modules
+retain their full semantic-config identity and their existing storage profiles. Sharing a custom
+workspace storage directory remains an explicit operator choice, not a new global cache feature.
+
+Artifact keys and output digests retain the 0.2.1/0.3.0 contract, including the repository-document
+identity policy introduced in 0.2.1. No incompatible 0.2.0 artifact is reinterpreted as current.
+Source approval and assertion review remain distinct; this change never approves an assertion.
+
+## Legacy recovery without model work
+
+The planner and hydrator use the same store factory. It may read the exact legacy user profile
+derived from the current full configuration after checking the new primary store. A corrupt or
+unreadable primary entry stops reuse; a valid legacy entry does not mask it. Planning remains
+read-only. Hydration can atomically retain a validated legacy artifact in the new partition, then
+revalidate the retained entry to handle concurrent winners. Original files, artifact identities,
+source provenance and raw provider output remain intact.
+
+Legacy profile directories contain no reliable checkout/configuration ownership manifest, and an
+interrupted run may have no snapshot. Consequently, the toolkit never scans sibling profiles for
+a matching key. If settings were already changed, the old location cannot safely be inferred.
+
+The explicit `cache adopt --from-config <previous.json>` command handles that case without
+providers, authentication probes, indexing, ontology compilation, adapters or snapshot writes.
+Both configurations must resolve to the same checkout and have the same non-operational
+partition identity. Keep the exact old configuration in its original configuration directory.
+Relocation is safe only when its original, unchanged `repositoryRoot` still resolves to the same
+checkout (for example, an absolute root). Do not edit that field to compensate for relocation:
+it is part of the old profile identity. Preserve the original field values and omissions.
+
+Adoption resolves a committed ref and uses the same configured/agent selection as the hydration
+preview. It looks up only expected keys in the exact old profile, checks the complete artifact
+contract and output digest, and copies valid candidates atomically. `--dry-run` performs no writes.
+Reports identify reused/adopted/planned/missing/corrupt/unavailable/conflicting entries, configured
+budgets and scope omissions. They omit source bodies, raw provider output and configuration values.
+
+Recovery is per artifact: valid copies can complete even if another entry is corrupt or conflicts.
+The report records partial progress and exits unsuccessfully for problems or incomplete scope.
+Missing artifacts are ordinary future extraction work. Corrupt complete artifacts are retained
+for diagnosis; they require an explicit forced refresh or operator repair, not automatic overwrite.
+Incomplete temporary files are not published artifacts and do not satisfy a cache lookup.
+
+Concurrent writers use immutable publication. Different outputs under one key are reported as
+conflicts; a matching `outputDigest` field alone is insufficient to accept malformed metadata.
+Explicit forced extraction still creates a separate revision and preserves existing artifacts.
+
+## Freshness and limits
+
+Semantic reuse does not reuse a snapshot's validation result, skip SCIP or SHACL, or let old
+configuration evidence satisfy current validation. A timeout change still changes the snapshot's
+full configuration digest and user storage profile. Saved evidence remains available under its
+original configuration; this increment does not consolidate historical snapshot directories.
+
+The current module-provider contract does not promise operational independence. Supporting that
+requires a separate tested contract, not silently dropping fields from a provider's identity.
+Credential rotation under an unchanged environment-variable name is not detected by this cache;
+credentials are neither cache contents nor cache-identity inputs. Existing filesystem access
+controls and the configured storage location remain the security boundary.
+
+Validation uses public fixtures, deterministic Codex runners and installed TypeScript indexing.
+Live semantic quality and private consumer acceptance remain separate. See the
+[1.0 plan](RELEASE-1.0-PLAN.md) for timeout diagnostics and document coverage follow-ups.

package/docs/ADR-019-semantic-failure-diagnostics.md

@@ -0,0 +1,82 @@
+# ADR-019: Safe semantic failure diagnostics and settled progress
+
+Status: implemented in development source after 0.3.0; validation and publication are recorded
+separately in [validation](VALIDATION.md). This decision does not change extraction identity.
+
+## Problem
+
+A generic timeout does not identify which source failed, how much work survived, or how to
+resume. Concurrent workers can also cancel each other: reporting the last error can hide the
+initiating timeout, and reporting before active writes finish can undercount retained artifacts.
+Arbitrary provider exceptions and abort reasons may contain private input.
+
+## Decision
+
+Keep semantic-run scheduling and reporting in `application/semantic-run.ts`, separate from graph
+assembly. Record the first source failure before aborting siblings, stop scheduling queued sources,
+and wait for active workers to settle before constructing `SemanticHydrationError.report`.
+The report has a versioned kind, safe code/category, phase, committed SHA, configuration digest,
+elapsed time and scope, effective timeout and its scope, final counts, and recovery guidance.
+
+Completion means a validated artifact was retained or successfully reused. A write already in
+progress can finish after cancellation and remains a completion. A provider result returned after
+abort is rejected before validation/publication. Late storage failures remain failures, not sibling
+cancellations. Cancellation between sources has phase `semantic-scheduling`, no failing source ID,
+and run elapsed time; it does not relabel successfully retained artifacts as cancelled.
+
+Counts have these meanings:
+
+- `completed = extracted + reused`.
+- `total = completed + failed + cancelled + notStarted` after active workers settle.
+- `remaining = total - completed`; this includes failures, cancellations and queued work. It is
+  not a promise about the number of model calls required by a future run.
+
+Known provider timeouts, cancellations, unavailable infrastructure, process exits and invalid
+output remain distinct. Configured unresolved-mapping and confidence rejections retain separate
+`unresolved` and `low-confidence` codes and remain extraction gaps. Their acceptance criteria are
+unchanged. Unknown extraction exceptions become `provider-failure`, without an
+invented diagnosis. Cache read/write failures have a separate code; invalid extraction validation
+is an extraction gap. Module loading/export/identity problems are unavailable infrastructure.
+No raw exception, cause, provider output, prompt, credential or source path is copied into the
+report. These diagnostics are not approved intent or evidence that a product rule was violated.
+
+The CLI prints safe errors and progress on stderr, leaving stdout for successful results.
+`hydrate --json --quiet` produces a JSON semantic failure report on stderr. The JSON contract
+covers the semantic-source run; configuration, repository, indexing and graph validation errors
+retain their existing interfaces. SIGINT listeners are removed on both success and failure.
+The saved-evidence MCP interface still performs no hydration and writes only protocol messages
+to stdout. Trusted module code must itself avoid logging private inputs; this is not a sandbox.
+
+## Source correlation and timeout meaning
+
+A domain-separated SHA-256 of repository ID and stable semantic ID gives each source an opaque
+`sourceId`. `hydrate --plan` explicitly maps that ID to its local path. The ID is stable across
+retries and source edits when the stable semantic ID stays the same; renames without a declared
+stable ID may change it. It is a correlation aid, not anonymization, encryption or an access
+boundary. Do not publish the local preview without reviewing its paths and other metadata.
+This ID never enters artifact keys, prompts, facts or snapshot configuration digests.
+
+For source failures, elapsed time includes cache checks, authentication, provider attempts and
+retries through failure. Codex's configured limit is per attempt; authentication has a separate
+bounded status check. Module execution has one deadline covering import, factory and extraction.
+The report distinguishes these scopes rather than presenting the limit as an end-to-end deadline.
+No timeout default, retry policy, extraction contract or cache version changes here.
+
+## Recovery and limits
+
+Failures do not reach graph publication. Prior snapshots and completed artifacts remain intact.
+Use the same configuration, committed ref and scope in the no-model preview to inspect current
+reuse before retrying without `--force-semantic`. T03 preserves compatible built-in Codex artifacts
+across supported operational changes; legacy recovery requires the exact previous configuration.
+Custom modules retain conservative full-configuration identity. Completed forced revisions are
+retained but are not automatically adopted by an ordinary rerun or a new forced revision.
+
+The toolkit waits for built-in subprocess termination or the module wrapper's bounded promise.
+It cannot forcibly terminate arbitrary trusted in-process module code. Cancellation before source
+selection and outside semantic processing uses the existing safe cancellation error without
+per-source counts. Phase boundaries remain the progress signal; no synchronous SHACL heartbeat,
+incremental validator or invented percentage is introduced by this milestone.
+
+Public deterministic tests cover failures, cancellation races, durable-write completion, counts,
+privacy, reuse, unchanged snapshot heads, source mapping and installed CLI behavior. They do not
+claim private consumer acceptance or live-provider semantic quality.

package/docs/ADR-020-canonical-physical-file-producers.md

@@ -0,0 +1,97 @@
+# ADR-020: One physical-file policy for deterministic producers and adapters
+
+Status: implemented in development source after 0.3.0; release/consumer acceptance is recorded
+separately in [validation](VALIDATION.md).
+
+## Reported defect and ownership
+
+The consumer's bounded replay of installed 0.3.0 extractors reported 120 conflicting file IDs:
+34 from the neutral contract extractor alone, 57 from its local framework adapter alone, and
+29 from both. Actual file/SCIP extraction classified spec/test files as `Evidence`; contract
+consumers and local framework nodes could classify those same physical IDs as `Component`.
+The consumer isolated a neutral file-plus-contract pair that failed strict SHACL single-kind
+validation. This is an extraction identity defect, not conflicting product intent.
+
+Upstream owns the neutral policy and producers. The consumer owns its framework call sites and
+their tests. This work uses public fixtures; it does not reproduce all private IDs, modify the
+consumer repository, patch installed packages or claim successful consumer hydration.
+
+## Public contract
+
+Move the existing pure `repositoryFileNode(path)` implementation into `@weftlet/core` and export
+it publicly. Its module imports only the `GraphNode` type; core gains no runtime package
+dependencies. Keep the toolkit's internal re-export for compatibility, but adapters should use:
+
+```ts
+import { repositoryFileNode } from '@weftlet/core';
+
+const file = {
+  ...repositoryFileNode(path),
+  attributes: { /* adapter-specific evidence metadata */ },
+};
+```
+
+The caller supplies a repository-relative path in its canonical spelling. Existing mappings stay
+unchanged: `.md`, `.mdx` and `.txt` use `document:<path>`/`Document`; `.spec.<extension>` and
+`.test.<extension>` use `component:file:<path>`/`Evidence`; other physical files use that file
+prefix and `Component`. Matching ignores extension case but preserves path spelling. This is not
+filesystem resolution, universal test detection, proof of existence or approved intent. Do not
+rewrite business concepts, contract identities or architectural modules into physical-file IDs.
+
+The producer audit is explicit:
+
+| Producer | Change |
+| --- | --- |
+| Neutral file extractor | Replace duplicated kind logic; preserve source/index attributes |
+| SCIP symbols | Replace duplicated kind logic; preserve symbols, sites and citations |
+| Contract consumers | Replace hard-coded Component; retain conceptual contract and evidence IDs |
+| Document linker | Import the public factory; existing owner/reference behavior stays intact |
+| Routing | Replace duplicated mapping; document endpoints now join document identities |
+| Governance | Use the factory for dependency and membership files and query lookup; retain module/layer concepts |
+| Semantic normalization | Use the shared factory for its existing document-only normalization; see the boundary below |
+
+Facts are retained, including test files with mocked client calls, DI and decorators. We do not
+suppress test evidence, rename conflicting IDs, weaken kind cardinality or change source/assertion
+authority. Graphs and all working overlays require strict SHACL before publication; overlay
+validation no longer depends on routing being configured.
+
+## Identity, saved evidence and artifacts
+
+Contract extraction advances from 1.1.0 to 1.2.0; routing and SCIP fact extraction from 1.0.0 to
+1.1.0; governance analyzer from 2 to 3. The SCIP indexer/tool version is unchanged. Committed
+assembly becomes `standalone-graph-v7`, with `graph-v7`, contract and SCIP fact identity included
+in snapshot IDs. Overlay IDs/metadata also bind assembly, contract and SCIP fact identity,
+so rebuilding identical captured bytes cannot replace an older overlay. Governance records its
+analyzer identity in both snapshot digest inputs and metadata.
+
+Current validation requires matching assembly, contract and SCIP fact versions, plus routing version when
+configured. Missing metadata is not a pass. Final checks reject old versions without initiating
+hydration. Historical saved queries still return the original facts, with extraction compatibility
+reported separately from commit/configuration/working-overlay freshness in JSON, Markdown and
+the viewer. Saved queries remain ineligible to validate a current diff.
+
+The physical policy itself was already correct. Its semantic cache identity stays at version 1;
+provider/prompt/artifact keys and original artifact bytes remain unchanged. The original snapshot
+and any compatible semantic artifacts remain available. A fresh graph must still be assembled,
+indexed and validated. Reuse does not imply that an old graph passes current validation.
+
+## Semantic and consumer boundary
+
+The reported 120 conflicts were reproduced entirely by deterministic producers. This fix does
+not rewrite semantic caches or force paid re-extraction to hide that defect. Existing semantic
+normalization continues correcting repository document IDs/kinds only. Non-document model kinds
+remain asserted, inferred and unreviewed; an incompatible model assertion still fails strict
+SHACL. A broader interpretation migration would need separate provenance/OML parity tests and
+an explicit cache/assembly decision. It is not silently bundled into this deterministic fix.
+
+After upgrading both packages to the reviewed public release, the consumer must change every
+physical-file node emitted by its framework adapter to the public factory and version that
+adapter's extractor deliberately. Add actual adapter regressions for Prisma/DI/decorator-bearing
+spec/test files composed with neutral file facts. Do not change semantic provider/prompt policy
+versions merely to perform this deterministic adapter migration. Preview compatible artifact reuse,
+then run full hydration and repeat acceptance against the committed adapter update.
+
+Public upstream tests compose actual committed-source extractors, real TypeScript indexing,
+document and routing links and a public adapter-shaped fixture. They assert strict SHACL,
+provenance, confidence, authority, stable conceptual identities, saved-byte preservation and
+version guards. They do not establish the private adapter's acceptance or semantic quality.

package/docs/PROVIDERS.md

@@ -83,7 +83,7 @@ continue using their ChatGPT login; this change does not provision or copy accou
 ## Limits and reuse
 
 Defaults are at most 8 documents per hydration, 64 KiB per source, a 120-second timeout per
-request, no retries, and the configured concurrency (validated at 1–4). Source budgets are checked
+Codex attempt (or module execution), no retries, and the configured concurrency (validated at 1–4). Source budgets are checked
 before any model call. `maxDocuments`, `maxSourceBytes`, `timeoutMs`, and `retries` may be configured
 within validated limits. Review scope and cost before raising them; these byte/document limits
 are not dollar or token estimates. Ask the operator before substantial paid runs.
@@ -96,6 +96,56 @@ digest/stable ID, extractor/adapter/ontology versions, confidence threshold and
 Unchanged artifacts are reused; forced revisions are separate. Failures never replace a valid
 snapshot. Progress shows phase and counts on stderr, with no document text or paths.
 
+Starting with 0.4.0, T04 adds opaque source IDs, source elapsed times and structured semantic
+failure reports. With that version or newer installed, retain the same committed ref and any
+agent scope options as the failed run:
+
+```sh
+pnpm exec weftlet hydrate --config /path/to/project/context-graph.config.json --ref <commit> --plan --json
+pnpm exec weftlet hydrate --config /path/to/project/context-graph.config.json --ref <commit> --json --quiet
+```
+
+The first command makes no model calls and maps each `sourceId` to its local document path. Review
+that preview before sharing it. The second performs hydration: semantic failures exit nonzero,
+leave stdout empty and emit JSON on stderr. Omit `--quiet` for progress; omit `--json` for a safe
+human failure summary. Successful hydration still prints its result on stdout. JSON failure
+reporting covers semantic processing, not every configuration/indexing/validation failure.
+
+Reports distinguish timeout, cancellation, unavailable infrastructure, provider failure, invalid
+output, unresolved mappings, low confidence and cache problems. Completed/extracted/reused counts include active writes that finished
+before workers settled. `remaining` includes failed, cancelled and not-started sources; consult
+preview for future extraction estimates. Cancellation between sources has no failed `sourceId`.
+Source elapsed time includes cache checks and retries and may exceed the per-attempt limit;
+module timeout includes import/factory/extraction. No defaults or retry rules change.
+
+For a timeout, review `semantic.timeoutMs` and preview again before retrying without
+`--force-semantic`. Completed forced revisions remain stored but are not automatically reused by
+an ordinary rerun or a new forced run. Custom provider configuration changes remain conservative.
+See [ADR 019](ADR-019-semantic-failure-diagnostics.md) for reporting and privacy boundaries.
+
+Starting with 0.4.0, built-in Codex semantic artifacts are separate from user
+snapshot profiles. Changing `timeoutMs`, `retries`, `concurrency`, `maxDocuments` or
+`maxSourceBytes` can reuse completed artifacts; selection budgets are still enforced. Snapshot
+configuration digests remain complete and saved snapshots are not accepted as current merely
+because their artifacts were reused. Workspace cache paths and custom-provider identities remain
+unchanged. See [ADR 018](ADR-018-operational-semantic-cache.md) for exact isolation and recovery rules.
+
+If an older user-cache run was interrupted and its configuration has already changed, retain an
+exact copy of the previous configuration in its original directory. Its original `repositoryRoot`
+must still resolve to the same checkout; editing that field changes the old profile identity.
+With 0.4.0 or newer installed:
+
+```sh
+pnpm exec weftlet cache adopt --config /path/to/project/context-graph.config.json --from-config /path/to/project/previous-context-graph.config.json --ref HEAD --dry-run
+pnpm exec weftlet cache adopt --config /path/to/project/context-graph.config.json --from-config /path/to/project/previous-context-graph.config.json --ref HEAD
+```
+
+For an agent-scoped run, supply the same `--owner-doc`, `--task` or `--capability` selection used
+for hydration. The JSON report shows what was retained and what still needs extraction. Adoption
+makes no model calls and changes no snapshots or source files. Incompatible configurations are
+refused; unrelated cache profiles are never scanned. Corrupt/conflicting artifacts are reported
+and retained. This command is not present in published 0.3.0.
+
 For a trusted local provider module, set `provider: "module"`, `providerModule` to a local path
 (relative to the repository root) or installed package, and `providerIdentity` to its exact
 declared version. Packages resolve from the consumer repository using ESM import conditions.

package/docs/RELEASE-1.0-PLAN.md

@@ -1,10 +1,15 @@
 # Consumer hardening and the 1.0 release plan
 
-Status: maintainer-directed work, recorded on 2026-10-26 from a consumer integration report.
-The starting release is `@weftlet/toolkit@0.2.0`. **Ship a patch for T01 first.** The remaining
-items improve setup, reuse, diagnostics and document coverage; they do not block that patch
-or justify 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.
+Status: maintainer-directed work; release checkpoint on 2026-10-26 after verified 0.3.0 publication.
+**New adoption blocker: T08, deterministic physical-file kind conflicts.** This takes release
+priority over the remaining planned increments; T04 was completed first as requested.
+The report concerned `@weftlet/toolkit@0.2.0`. **T01's upstream patch shipped in 0.2.1**;
+genuine consumer acceptance remains pending. T02 and T05's focused cold-validation optimization
+shipped in 0.3.0. T03 and T04 are implemented in development source after that release. Broader T05
+follow-ups and 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
@@ -31,17 +36,40 @@ integration. Consumer acceptance is reported separately from upstream determinis
 
 | ID | Task | Priority/status | Dependencies and release boundary |
 | --- | --- | --- | --- |
-| **T01** | Coherent repository-document identity and kind | **Adoption blocker; patch work in progress** | First isolated patch; preserve SHACL and all assertions |
-| **T02** | No-model hydration/setup preview | Planned usability work | Shares selection/cache identity with hydration; extend it 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 | Planned correctness/observability work | Build on T01; profile latency independently before selecting optimizations |
-| **T06** | Packaged release-documentation consistency | Planned release tooling work | Check the actual release archives; does not require a runtime architecture change |
+| **T08** | Canonical physical-file kinds and public adapter factory | **Merged; local and hosted Ubuntu/Windows checks passed; release pending** | Neutral contract consumers conflict with test Evidence; consumer framework migration remains separately required |
+| **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 | Shipped in 0.3.0 | Shared selection/cache inspection, human/JSON plans; extend with T07 traversal coverage |
+| **T03** | Artifact reuse across operational configuration changes | Merged; local and hosted Ubuntu/Windows checks passed; unreleased | Built-in Codex user artifacts share five operational changes; custom providers remain conservative; exact legacy recovery without model calls |
+| **T04** | Actionable, privacy-safe timeout diagnostics | Merged; local and hosted Ubuntu/Windows checks passed; unreleased | Safe source IDs, settled counts, failure classification and T02/T03 recovery; no extraction/cache identity change |
+| **T05** | Early identity checks and validation progress/profiling | **Cold-validation fix shipped in 0.3.0; consumer acceptance pending** | Full validation preserved; 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–T07 can ship in independently useful increments after the blocker patch. Do not combine
-all seven into one diff or delay T01 for the optional platform work. Normal required release
-checks still apply to every shipped increment.
+T02 and the focused T05 fix passed local publication checks and hosted Ubuntu/Windows checks,
+then shipped in [0.3.0](https://github.com/jchewitt/weftlet/releases/tag/%40weftlet/toolkit%400.3.0).
+Registry archives match the independently reviewed export; source commit, provenance and release
+tags are recorded in [validation](VALIDATION.md). T03, T04, T06 and T07 remain independently
+useful increments, separate from the optional platform work. A genuine consumer hydration and
+repeat against the current release remain required; upstream fixtures do not establish that result.
+
+## T08 — Resolve deterministic physical-file kind conflicts
+
+The consumer reports 120 IDs reproduced by actual 0.3.0 deterministic producers: 34 neutral
+contract-only, 57 local-framework-only and 29 overlapping. This is separate from T01's repository
+document identity defect and does not diagnose semantic-cache corruption or business-rule drift.
+
+[ADR 020](ADR-020-canonical-physical-file-producers.md) records the public core factory, producer
+audit, deterministic version changes and preserved semantic-cache boundary. The upstream fix
+routes physical-file producers through one policy, preserves strict SHACL/provenance/authority,
+and distinguishes historical graph versions from current validation. Public tests include real
+SCIP and actual extractor composition, plus negative overlay validation without routing.
+
+Release requires local publication checks, hosted Ubuntu/Windows checks, reviewed archives and
+fresh installed-package verification. Consumer acceptance then requires the published packages
+plus its own framework adapter migration and composed Prisma/DI/decorator spec/test regressions,
+followed by full hydration and repeat reuse. Neither an upstream-only release nor a local-only
+adapter patch closes both ownership boundaries. Do not rewrite semantic caches or force model
+work to work around the proven deterministic defect.
 
 ## T01 — Resolve repository-document identity conflicts
 
@@ -66,16 +94,41 @@ Acceptance:
   the patch, then request a genuine consumer re-run against the recorded inputs; do not infer
   consumer acceptance from the upstream fixture.
 
-Completion evidence will link the implementation PR, tested source commit, validation record,
-published patch and subsequent consumer result. No patch publication or consumer pass is claimed
-by this task list yet.
+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 with the identity
+patch. Use the current 0.3.0 release, which also includes the cold-validation improvement.
+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
 
-Add a no-model preview command, tentatively `hydrate --plan`; the CLI spelling is not implemented
-by this plan. Use the same source-selection and identity logic as hydration to avoid preview drift.
-Report selected sources and sizes, inclusion reasons, role/approval classification, expected
-artifact hits/misses and extraction count, plus document/byte limits and any violations.
+Shipped in 0.3.0: `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:
 
@@ -90,6 +143,20 @@ Acceptance:
 
 ## T03 — Reuse valid artifacts after operational changes
 
+Merged in [PR 22](https://github.com/jchewitt/weftlet/pull/22) after 0.3.0, with local publication
+and hosted Ubuntu/Windows checks passing. This source checkpoint does not claim npm publication.
+[ADR 018](ADR-018-operational-semantic-cache.md) separates built-in Codex user artifacts from
+full snapshot profiles. Timeout, retry, concurrency and document/byte limits can change without
+hiding completed artifacts. Model/policy/authentication descriptors and unknown fields remain
+identity inputs; custom providers retain their full configuration contract. Workspace cache
+paths and existing 0.2.1/0.3.0 artifact identities remain unchanged.
+
+Planning reads the exact compatible legacy profile without writing. Hydration can retain a
+validated copy atomically. Explicit `cache adopt --from-config` and its read-only `--dry-run`
+recover expected committed-source keys after settings were already changed; no unrelated profiles
+are scanned and no providers or snapshots are initialized. Agent scope and budget/coverage
+reporting match the hydration preview. Current-diff checks still reject old-configuration snapshots.
+
 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
@@ -106,10 +173,22 @@ Acceptance:
 - 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.
+  missing/incomplete artifacts are extracted, and source provenance remains correct. Corrupt
+  complete artifacts stay intact and require explicit forced refresh or operator repair;
+  they are not silently overwritten or treated as misses.
 
 ## T04 — Explain timeouts and recovery
 
+Merged in [PR 25](https://github.com/jchewitt/weftlet/pull/25) after 0.3.0, with local publication
+and hosted Ubuntu/Windows checks passing. This development checkpoint does not claim npm publication.
+[ADR 019](ADR-019-semantic-failure-diagnostics.md) records opaque source IDs and explicit local
+preview mapping, final counts after active workers settle, safe typed errors and recovery.
+Concurrent sibling cancellation preserves the initiating failure. Completed writes stay counted
+as completed; cancellation between sources reports no failing source. The CLI supports semantic
+failure JSON on stderr with `hydrate --json --quiet`, leaving protocol/success stdout untouched.
+Provider loading problems and unknown provider errors are distinct. Timeout defaults, extraction
+identities, cache formulas, saved queries and full graph validation remain unchanged.
+
 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
@@ -126,19 +205,56 @@ Acceptance:
 
 ## T05 — Detect inexpensive conflicts early and explain validation work
 
-Add inexpensive graph-assembly checks for incompatible identities before expensive validation.
-Keep the full conformance requirement. Separately instrument and profile large RDF/SHACL
-validation to determine where time is spent before choosing optimizations.
+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. That report made
+cold validation a release priority ahead of the remaining 1.0 work. 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. The focused cold-validation fix shipped in 0.3.0, ahead of the
+remaining 1.0 tasks. Consumer acceptance remains pending; broader T05 items stay open.
+
+[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 phase/heartbeat progress for long validation. Do not display a
-  fabricated completion percentage when the validator exposes no meaningful denominator.
+- 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. Separate measured bottlenecks from hypotheses.
+  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.
@@ -146,9 +262,9 @@ Acceptance:
 ## 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. Source documentation has since been updated, but immutable published archives retain
-their original text. Add a repeatable release-documentation check rather than relying on a
-post-publication source edit.
+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:
 
@@ -194,7 +310,7 @@ Acceptance:
 
 ## Official 1.0 acceptance
 
-After T01's patch is available, work through T02–T07 in bounded increments and record implementation
+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