@weftlet/toolkit 0.3.0 → 0.4.0

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,12 @@
 # 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.
+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 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
+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.
@@ -34,20 +36,40 @@ integration. Consumer acceptance is reported separately from upstream determinis
 
 | ID | Task | Priority/status | Dependencies and release boundary |
 | --- | --- | --- | --- |
+| **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 | 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 |
+| **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 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.
+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
 
@@ -87,13 +109,14 @@ Upstream completion evidence:
   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.
+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
 
-Implemented in development source: `hydrate --plan` renders a human summary and `--json` returns
+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.
@@ -120,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
@@ -136,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
@@ -162,11 +211,11 @@ entire assembled graph, including when semantic artifacts were reused. There is
 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
+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. Ship the focused performance release once its correctness and
-improvement are demonstrated, ahead of the remaining 1.0 tasks.
+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

package/docs/RELEASING.md

@@ -1,7 +1,9 @@
 # Weftlet npm releases
 
-`@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
+`@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

package/docs/ROADMAP.md

@@ -1,7 +1,7 @@
 # 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.
+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).
@@ -9,18 +9,19 @@ Project: `jchewitt/weftlet`. Extraction provenance is recorded in the
 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
+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 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.
+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.
 
-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.
+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
@@ -29,10 +30,28 @@ still checks the complete in-memory N3 graph on each hydration; saved queries do
 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.
+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 |
 | --- | --- | --- |
 | 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 |
@@ -119,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.1 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).