@weftlet/toolkit 0.4.0 → 0.6.0

package/docs/ADR-024-implementation-coverage.md

@@ -0,0 +1,51 @@
+# ADR-024: Report evidence coverage independently of display groups
+
+Status: implemented after T07a; validation and publication are recorded separately in
+[validation](VALIDATION.md). This is a query-reporting correction, not T07b document classification.
+
+## Problem
+
+The consumer reports returned code relationships with zero implementation coverage. Public
+reproductions using the actual contract extractor and real SCIP confirm the defect: a file's
+definition or consumption of a Contract is placed in the contracts display group. Coverage used
+the exclusive display-group counts, so these code relationships could not count as implementation.
+The inverse also occurred: unapproved document/model facts in the fallback implementation group
+could suppress an implementation gap. Page-local absence was described as query-wide absence.
+
+## Decision
+
+Keep primary display groups, returned facts, ranking, pagination and authority unchanged. Compute
+implementation coverage from the returned evidence independently of display placement. A production
+code relationship can count toward both contract and implementation coverage without appearing twice
+in the returned facts. The other coverage categories retain their existing classification.
+
+New reports include `coverage.scope: "returned-page"` and `countsAreNonExclusive: true`.
+Both fields are optional in core for compatibility with older Context Packs. Counts are relationship
+counts, not percentages, totals of display sections, product completeness or proof of correct behavior.
+Markdown and HTML explain overlap. Missing-evidence messages refer to the returned page; continuation
+and traversal bounds can leave further evidence outside it. Existing source diagnostics remain intact.
+
+An implementation relationship must have effective `implemented` authority, a non-document,
+non-validation citation, and no unreviewed extraction marker. Current document/model, runtime,
+draft and validation evidence cannot qualify by merely mentioning a code file. Supported document
+extensions and test/spec names use the canonical core file policy. Conventional test/validation
+directories, including `__tests__` and `__mocks__`, are excluded from production coverage.
+
+Legacy deterministic adapters that omitted authority retain the existing authority fallback only
+when a canonical physical Component endpoint matches the cited file. An adapter explicitly marking
+a fact `implemented` may also use logical Component/Provider identities with a production citation.
+Unmarked legacy provider output cannot be distinguished from adapter output when their metadata is
+identical; no new claim of provider verification or execution is made. Saved fact authority is never
+rewritten by this reporting classification.
+
+## Compatibility and validation
+
+No extractor, prompt, semantic artifact, assembly or ranking identity changes. Existing immutable
+snapshots immediately benefit when queried by the updated toolkit; no model run or hydration is
+needed. Historical Context Packs keep their original reports unless queried again. Existing clients
+should inspect the new metadata rather than summing counts as a disjoint total.
+
+Regressions use actual contract extraction, real TypeScript SCIP, strict SHACL and immutable
+round-tripped facts. They cover overlapping counts, page continuation, API/MCP/Markdown/HTML
+consistency, document/model/test negatives and retained source diagnostics. Installed-package smoke
+checks query actual extracted facts rather than constructing coverage values by hand.

package/docs/ADR-025-document-classification.md

@@ -0,0 +1,78 @@
+# ADR-025: Document roles, ownership and deterministic evidence
+
+Status: T07b merged in PR 42; local and hosted checks and independent review passed.
+No npm publication or consumer acceptance is claimed. See [validation](VALIDATION.md) for
+completed checks and the [1.0 plan](RELEASE-1.0-PLAN.md) for the remaining boundary.
+
+## Decision
+
+Classify document sources separately from source approval, assertion review and canonical node
+identity. The public classifier accepts explicit role/owner mappings; the standalone deterministic
+extractor retains document presence and canonical references without semantic artifacts. T07b does
+not register that extractor with hydration or overlays. T07c will connect selection, classification,
+validation-document separation and artifact reuse to execution.
+
+`documents plan --document-policy <json-file>` accepts an optional operation-time JSON sidecar,
+resolved from the current working directory and bounded to 65,536 bytes. It is not a hydration
+configuration field. The API equivalent is `DocumentCoverageOptions.documentPolicy`. Documents
+come from the chosen commit; policy and existing configuration are current operation inputs.
+The report records their digests and makes no model/provider request or graph write.
+
+## Roles and owner mappings
+
+Source roles are `intent`, `plan`, `validation`, `reference` and `unclassified`. Explicit role
+mappings override configured defaults. Without a matching role mapping, evidence roots imply
+`validation`, approved intent sources imply `intent`, and other sources remain `unclassified`.
+Different matching explicit roles produce an ambiguity; rule order never chooses a winner.
+Approval still comes only from `approvedIntentSources`, independently of the selected role.
+
+Ownership requires an explicit mapping to a canonical document path. One available, approved
+owner with an unambiguous `intent` role resolves ownership. Multiple distinct owners are
+`ambiguous`; an unread or outside-coverage owner is `unavailable`; an unapproved owner is
+`unapproved`; an approved owner with another or ambiguous role is `ineligible`. With no mapping,
+ownership is `missing` for intent/plan/unclassified sources and `not-required` for validation/reference.
+Approval does not imply self-ownership; a self-owner must also be mapped explicitly.
+
+An owner mapping never approves its child document or an extracted assertion, and produces no
+inferred owner edge. Missing/ambiguous roles and ownership are source-level evidence gaps, not
+proven business-rule violations. The normalized policy digest includes role/owner mappings and
+the approval/evidence-root policy; it does not depend on rule order or document availability.
+
+## Evidence records and querying
+
+Optional per-fact `sourceRole`, `sourceOwnership` and `sourcePolicyDigest` preserve classification
+without attaching conflicting roles to a shared canonical Document node. RDF exposes the role,
+ownership status, owner paths, mapping IDs and policy digest while retaining exact record projection.
+Metadata-targeted SHACL constraints validate new fields; historical facts without them retain
+their existing behavior. Document IDs/kinds and the existing assembly/cache identities stay intact.
+
+`extractDocumentEvidence` uses the committed traversal and classifier. For each successfully read
+document it emits a Project `contains` Document fact, including empty documents and documents
+without outgoing links. It emits `references` facts only for resolved canonical file/document
+links, retaining exact declaration/use citations, source digests and commit SHA. Unresolved links
+and incomplete traversal remain explicit reports/diagnostics; no missing relationship is invented.
+The new `document-evidence-extractor:1.0.0` identity and classification metadata enter fact IDs.
+
+These structural facts have inferred authority and deterministic extraction review. Their source
+approval remains separate. Presence, a reference or a validation role does not claim that a test
+ran/passed or a product rule was approved. Explicit validation roles use validation coverage;
+plan/reference/unclassified roles cannot establish product intent. Query and viewer details expose
+the same role/ownership metadata; existing facts without roles retain legacy interpretation.
+
+## Readiness and delivery boundary
+
+The prospective plan's top-level `ready` remains traversal completeness plus budget readiness.
+`classification.complete` independently describes role/ownership gaps and must be inspected
+separately. Neither flag proves complete product coverage, approved assertions or hydration
+readiness. A resolved owner can remain outside a future extraction selection; T07c must enforce
+the execution contract rather than infer it from a preview.
+
+Current direct-source hydration, `hydrate --plan`, configuration/cache identity and saved snapshots
+remain unchanged. In particular, existing hydration still semantically extracts selected validation
+documents. T07b supplies the separate evidence path needed before T07c can exclude those documents
+from product-intent extraction without dropping their presence or citations.
+
+Validation covers role conflicts and defaults, owner eligibility and non-transfer of authority,
+actual committed presence/references, exact RDF/SHACL projection, query/viewer agreement and
+legacy behavior. Exact gate and review outcomes are in the validation record; neither those
+checks nor this decision claim npm publication or that traversal already drives hydration.

package/docs/ADR-026-traversal-hydration.md

@@ -0,0 +1,94 @@
+# ADR 026: Explicit traversal hydration with separate source and assertion authority
+
+Status: accepted and merged in PR 44 after local/hosted validation. Publication and consumer
+acceptance remain separate; exact commits and checks are recorded in [validation](VALIDATION.md).
+
+## Context
+
+T07a follows canonical committed Markdown links; T07b classifies source roles/owners and extracts
+cited document presence/references. Neither changed hydration. Consumers need one reviewed scope
+for preview, extraction, cache recovery and saved queries, including validation evidence that is
+unsuitable for product-intent extraction. A broad source list or a capped agent search must not
+silently replace that scope.
+
+## Decision
+
+An optional `documentTraversal` object in `context-graph.config.json` activates traversal hydration.
+It accepts exact `entryPoints`, optional document `roots`, bounded `maxReadDocuments`, `maxReadBytes`
+and `maxDocumentBytes`, and an inline T07b `policy`. Unknown controls are rejected. It replaces the
+legacy `semanticSources` list for this mode. Existing direct configurations keep their behavior and
+identity. Combining traversal with `agentContext`, or a programmatic `semanticSources` override,
+is rejected rather than silently narrowing or broadening scope. Requests may still filter saved
+impact queries; they do not change the traversal hydration selection.
+
+`selectHydrationInputs` is shared by hydration, `hydrate --plan`, explicit cache adoption and draft
+selection. Committed Git objects provide the closure despite working changes. Every discovered
+source is reported; canonical cycles/shared targets extract once. Missing/unsupported/ambiguous
+links, unread coverage, ambiguous source roles and semantic budget errors stop new model work
+before ontology readiness, indexing or extraction. Existing completed artifacts and snapshot heads
+remain intact. The no-model plan retains the full report on failure. Ordinary hydration points to
+that local report without printing document paths/content in its new selection error.
+
+Validation roles default from `evidenceRoots`, with explicit role mappings taking precedence. They
+receive deterministic presence/reference evidence, including empty reports, and no model calls.
+Semantic budgets count the remaining eligible sources; separate traversal read limits bound all
+read sources. The nested traversal report's comparison ceilings are the maximum supported read
+values, not a paid-work estimate; the plan's top-level `budgets` describes actual extraction limits.
+An explicit non-validation override is a maintainer policy choice, never model inference.
+
+Intent, plan, reference and unclassified sources may be extracted. Unresolved/ambiguous owner
+mappings remain visible diagnostics, not newly invented hard CI rules. A valid owner must itself
+be reached, approved and unambiguously intent. Being linked to an owner never approves a child,
+and source approval never approves a model assertion. Policy role describes source context, not
+a guarantee that every sentence is a business requirement. Model assertions stay inferred and
+unreviewed; structural facts stay deterministic and inferred. Neither a written “PASS” nor the
+presence of a test link asserts test execution.
+
+The canonical document extractor owns Markdown references in this mode. The legacy linker still
+emits assertion containment and supported bare/inline-code references. Assembly attaches role,
+source authority, ownership and policy digest without modifying immutable provider artifacts.
+Strict identity checks and SHACL remain required; assertions and contradictory evidence are not
+silently removed to pass validation.
+
+## Identity, reuse and overlays
+
+Snapshots bind the full configuration, closure/classification digest and `document-selection-v1`
+plus `document-evidence-extractor:1.0.0`. Core adds an optional `DocumentSelectionRecord`; saved
+JSON, Markdown and HTML expose coverage separately from ownership and assertion approval. Older
+snapshots remain queryable and cannot satisfy current-config/extractor/commit checks.
+
+The unchanged built-in Codex adapter receives one source without traversal/owner metadata.
+Its source/provider/prompt/version/confidence key remains intact. Its user-cache partition ignores
+only the validated `documentTraversal` field in addition to the five existing operational semantic
+controls. Enabling traversal or changing role/owner/read limits can reuse unchanged artifacts;
+source selection changes and source/model/version/approval changes retain existing conservative
+identity behavior. Snapshot profiles always retain the entire configuration. Explicit legacy
+cache adoption keeps conflict checks and never scans unrelated profiles.
+
+Custom modules are trusted code with an explicit versioned provider contract. Traversal modules
+get a separate full-config `document-semantic-v1` artifact namespace even in workspace storage.
+Direct-mode artifacts and changed configurations cannot be silently reused there. Identical
+configuration and unchanged source identities reuse; providers with additional mutable inputs
+must version their declared contract or force extraction. No arbitrary context-dependent module
+is promised automatic dependency discovery.
+
+Draft overlays recompute the closure from the isolated base plus captured bytes. They rebuild
+presence/references with draft authority, invalidate changed/deleted/unreachable sources and
+assertions whose owner changed, and retain only matching source/policy/ownership evidence. An
+incomplete closure invalidates all retained document assertions and is labeled incomplete; it can
+still be queried as a draft. No model runs. Temporary Git timestamps are excluded from draft
+selection identity; the base SHA and capture digest bind it instead. Committed heads are unchanged.
+
+## Validation and limits
+
+Public fixtures compose actual committed traversal, unchanged Codex schema/citation handling with
+an offline prose parser, real SCIP and strict RDF/SHACL. They cover the six-stage asynchronous
+pipeline, warm reuse, configuration/cache isolation, source authority, rename/delete/reachability,
+owner edits, draft gaps and saved-history freshness. CLI preview uses unavailable infrastructure
+sentinels; installed consumer smoke uses the versioned module contract and real indexing.
+These tests do not claim live model quality, browser interaction or TradePilot acceptance.
+
+`documents plan --document-policy` remains a separate prospective operation, including its own
+all-document budget comparison. Use `hydrate --plan` with the execution configuration to predict
+actual extraction and reuse. No documentation generation/backfill, ownership inference, approval
+UI, remote source adapter or model orchestration integration is added by this decision.

package/docs/ADR-027-validation-closeout.md

@@ -0,0 +1,155 @@
+# ADR 027: Retain full validation after bounded lifecycle and native evaluation
+
+Status: accepted engineering decision for the 1.0 candidate, 2026-10-28. Private consumer
+performance acceptance and official 1.0 remain separate gates. This increment changes development
+benchmarks, tests and documentation; it does not change the runtime validator or publish a release.
+
+## Decision
+
+Keep complete, direct `rdf-validate-shacl` validation over the full SPO union, with the unchanged
+shapes and supplemental citation-order check. Preserve the canonical named graph, provenance,
+authority and prior published snapshots. Saved-snapshot queries remain independent of rebuilding.
+
+Do not add a mandatory worker, validation receipt cache, incremental validator, Rust binary or
+graph database for 1.0. The evaluations below support this choice; these capabilities are not
+delivered or silently assumed. Reconsider when a measured consumer workload demonstrates a need.
+Memory remains a material limitation, and these results do not establish a maximum supported
+repository size or diagnose the private consumer's earlier 30-minute generation timeout.
+
+The cold-path change in [ADR 017](ADR-017-shacl-validation-union.md) and identity/phase diagnostics
+in [ADR 021](ADR-021-identity-preflight-and-validation-timing.md) remain the production improvements.
+This decision closes their remaining engineering evaluation items without changing those
+historical measurements. It does not waive genuine consumer hydration/repeat acceptance.
+
+## Measurements and reproducibility
+
+Raw, public, metrics-only records are in [the benchmark directory](benchmarks/validation-2026-10-28/README.md).
+They contain versions, source/harness hashes, fixture/fact/node/quad counts, complete case results,
+diagnostic hashes, timings and resource observations. There are no private graphs, model prompts,
+credentials or live provider calls. Runtime code is unchanged from `174f2ae`.
+
+Linux x64, Node 24.19.0, pnpm 10.18.2, N3 2.7.2 and rdf-validate-shacl 0.6.5 were used in a
+32 GiB cloud container. Every fixture/mode/sample used a fresh bounded child, three samples per
+case; garbage collection before cases was outside measurement. Repeated cases share their
+session's imports/JIT state. The pipeline uses actual committed prose, the real Codex adapter
+with a deterministic offline runner, real SCIP, cross-source linkage, SHACL and snapshot storage.
+Its six eligible prose artifacts were reused on repeat; this does not test a live model.
+
+Cold full-validation medians (union construction plus SHACL and the supplemental check):
+
+| Input | Facts / nodes / canonical quads | Direct | Worker | Largest direct process RSS |
+| --- | --- | ---: | ---: | ---: |
+| Extracted six-stage pipeline | 241 / 97 / 4,929 | 167 ms | 159 ms | 308 MiB |
+| Shared identities | 2,000 / 50 / 40,203 | 530 ms | 596 ms | 519 MiB |
+| Unique identities | 2,000 / 4,000 / 56,003 | 620 ms | 696 ms | 554 MiB |
+| Dense source metadata | 2,000 / 50 / 48,203 | 1,445 ms | 1,441 ms | 900 MiB |
+| Unique identities | 10,000 / 20,000 / 280,003 | 2,860 ms | 2,830 ms | 1,676 MiB |
+| Dense source metadata | 10,000 / 50 / 240,203 | 5,668 ms | 5,929 ms | 1,758 MiB |
+
+RSS is the largest sampled process high-water mark across the reported lifecycle, not SHACL's
+isolated allocation. It includes imports, fixture, canonical graph, serialization and union;
+worker RSS includes its parent. The largest dense 10,000-fact worker case reached 3,058 MiB.
+Dense fixtures attach source role/policy/ownership metadata to every fact, exercising the new
+ownership disjunction. They are stress fixtures, not a claim about consumer metadata density.
+The large cases are cold-only; the smaller fixtures include repeat and edits. There are 258
+completed direct/worker cases and 18 paired sample groups with exact verdict/data equality.
+
+Same-object repeat and rebuilt-identical graphs still execute full validation. Direct medians
+for repeat/rebuild were 110/113 ms (pipeline), 471/481 ms (shared), 602/636 ms (unique), and
+1,336/1,246 ms (dense). Insert, update, delete, rename, negative confidence, shared-identity
+conflict and repair-by-deletion all use complete candidate graphs, retain canonical serialization,
+and produce the expected verdict. This is correctness/performance evidence for full validation,
+not an incremental algorithm. No timing thresholds are CI gates.
+
+## Worker evaluation
+
+The development worker uses the identical validator, shapes, input and full validation call.
+All compared verdicts and serialized input hashes match direct execution, including failures.
+The parent timer remains responsive: around 21 ms in 10,000-fact cases versus 5.4–8.2 seconds
+for the direct harness operation (construction, serialization and validation combined). This
+timer measures responsiveness, not percentage complete. Worker startup was approximately 0.8
+seconds, structured cloning has a cost, and throughput/memory advantages were not consistent.
+
+A bounded prototype terminates the worker after its actual SHACL-started boundary. In the
+recorded runs termination took about 19–22 ms; no verdict was returned or accepted, and there is
+no storage/publication call in this probe. This does not establish production cancellation or
+failure recovery across a new worker boundary. Current runtime progress remains truthful phase
+boundaries; in-phase heartbeat, interruption and worker memory limits would need separate API,
+packaging, cancellation and head-preservation integration. There is no measured need to introduce
+that complexity into this candidate.
+
+## Exact successful-result reuse
+
+The study computes an experimental key over complete named RDF serialization plus validator,
+shape, authority/progress code hashes, workspace dependency lock and Node version. It never reads
+a cached verdict: every case validates. Identical/rebuilt/repaired input yields the same key;
+edits and a manifest-only timestamp change yield different keys even when conformance is unchanged.
+Serialization plus hashing alone costs roughly 23 ms for the cold pipeline, 137 ms for 2,000
+shared facts, 157 ms for 2,000 unique facts and 125 ms for 2,000 dense facts. Graph construction
+is still required. A manifest timestamp therefore prevents reuse across otherwise equivalent
+hydrations under this conservative key.
+
+Do not ship this prototype as a cache. A production receipt needs a reviewed validation dependency
+key, actual resolved engine/dependency identities, complete supplemental-rule inputs, coherent
+immutable input, atomically written and checked successful receipts, and invalidation for every
+shape/policy/semantic change. Excluding manifest fields is a separate correctness decision, not
+an arbitrary optimization. A failed/missing/corrupt receipt must trigger full validation; no
+receipt may satisfy current commit/scope/working-diff freshness requirements on historical data.
+The measured seconds saved do not yet justify that state and trust surface for 1.0.
+
+## Dependency-aware incremental evaluation
+
+The regression demonstrates a concrete counterexample: validating a changed assertion alone
+passes, while joining it with the unchanged producer of the same node fails `kind` maxCount.
+Revalidating all producers of that identity reproduces the full verdict. Removing the conflicting
+old producer repairs the graph without adding a fact. Renames require both old and new identities;
+source-role/ownership checks also depend on all contributing assertions at a fact identity.
+
+A safe implementation would need an index of every shape target and dependency, old/new affected
+subjects and property values, removed targets, identities and incoming/outgoing relationships,
+plus invalidation of prior violations. Shape/validator/policy changes and unbounded/global rules
+require full fallback. There is no such reviewed dependency index in the toolkit. Retain full
+validation for insertions, updates, deletions and renames; do not call a changed-facts pass a valid
+whole-graph verdict. No previous violation is baselined away by this decision.
+
+## Native candidate
+
+Material memory use justified a bounded evaluation of **Rudof 0.3.35**, an Apache-2.0 Rust CLI.
+The official Linux GNU asset was downloaded outside the repository and verified against its
+release SHA-256. No binary, dependency or license requirement is added to the product.
+
+The probe exports every SPO triple, passes the exact current shapes, and applies the same JS
+citation-order supplement (which is not itself a SHACL shape). All 29 public cases agree on
+conformance and diagnostic locations. Exact diagnostic multiplicity agrees on 27: for non-integer
+start/end lines Rudof emits two results at the failing property where the current validator emits
+one. Neither validator accepts those inputs. The raw report retains both diagnostics; no shape,
+failure or assertion is suppressed. The probe exits 1 to make this exact-parity difference visible.
+
+Each timing sample starts a fresh native process, with a 30-second whole-process-group deadline:
+
+| Input | Native parse/startup/validation median | Node export preparation, measured once | Largest native-only RSS |
+| --- | ---: | ---: | ---: |
+| 2,000 unique facts | 1,049 ms | 711 ms | 488 MiB |
+| 10,000 unique facts | 4,631 ms | 4,377 ms | 2,264 MiB |
+| 2,000 dense facts | 968 ms | 833 ms | 552 MiB |
+| 10,000 dense facts | 5,217 ms | 3,318 ms | 2,534 MiB |
+
+Native time includes the Python measurement wrapper, process startup and RDF parsing, unlike the
+JS validation-only column. Its RSS excludes the Node graph/export process; these columns are not
+engine-only apples-to-apples comparisons. Native dense SHACL invocation is competitive, but this
+file-transfer integration provides no demonstrated overall latency or memory win. An embedded
+binding might behave differently; this experiment does not measure one or generalize to all Rust
+engines. Native Windows/macOS installation, release asset delivery, supply-chain verification,
+schema evolution and diagnostic compatibility would also need support. Do not make it mandatory
+or add an optional backend that cannot yet be maintained and validated across supported installs.
+No graph database was benchmarked: there is no demonstrated persistent-service need, and adding
+one would change the toolkit's installation and operational boundary.
+
+## Acceptance still required
+
+Retain full upstream positive/negative/provenance/packaged-installation gates. Publish the reviewed
+minor candidate before the consumer trial. Record genuine cold and repeated hydration, successful
+full SHACL and snapshot publication, semantic reuse, observed resource/phase timing, saved querying
+and the approved ten-minute provider retry in TradePilot. These public measurements cannot supply
+that acceptance. Browser/live-auth work remains separately tentative as previously agreed; official
+1.0 requires the consumer result and release review.

package/docs/CONSUMER-TRIAL.md

@@ -6,7 +6,7 @@ development workspace. Saved evidence queries work without a model login. Hydrat
 prose uses the configured provider; an OAuth failure may block new extraction but does not
 remove an already published snapshot.
 
-Use a pinned, reviewed toolkit version and its matching documentation. npm `0.2.0` includes
+Use a pinned, reviewed toolkit version and its matching documentation. Release `0.2.0` introduced
 explicit routing declarations, committed TypeScript source projects, document linkage and
 the improved impact ranking. To evaluate a newer, unreleased commit, use both locally prepared
 package archives from that same reviewed commit; see [release preparation](RELEASING.md).

package/docs/MIGRATING-TO-WEFTLET.md

@@ -1,7 +1,7 @@
 # Migrating from Tently to Weftlet
 
 The project is now Weftlet. LaunchEcho remains the maintainer; the GitHub repository remains
-[jchewitt/weftlet](https://github.com/jchewitt/weftlet). Both new package names are published
+[jchewitt/weftlet](https://github.com/jchewitt/weftlet). Both new package names were first published
 at 0.1.0; see [release status](RELEASING.md) for subsequent releases.
 
 | Previous package / command | Replacement |

package/docs/PROVIDERS.md

@@ -87,6 +87,13 @@ Codex attempt (or module execution), no retries, and the configured concurrency
 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.
+Starting with 0.5.0, `semantic.timeoutMs` accepts integer values from 1 through **600000**
+(ten minutes); 0.4.0 and earlier reject values above 300000. The default remains 120000.
+For the approved ten-minute retry, set `"timeoutMs": 600000` inside the existing `semantic`
+configuration, preview reuse with `hydrate --plan`, then rerun hydration without forcing
+re-extraction. The limit applies to each Codex attempt, or the whole module execution, rather
+than the entire hydration. Codex authentication/discovery checks retain their separate five-second
+bounds. This setting does not raise a CI job's overall timeout or change retry policy.
 Only explicit transient exit status 75 is retryable, at most twice; authentication, invalid
 output, cancellation and ambiguous failures are not retried. Ctrl-C cancels live CLI extraction.
 Indexing cancellation is checked between phases, not inside the indexer process.
@@ -128,7 +135,7 @@ snapshot profiles. Changing `timeoutMs`, `retries`, `concurrency`, `maxDocuments
 `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.
+unchanged in direct mode. 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`
@@ -197,3 +204,12 @@ Deterministic tests install a public synthetic CLI with npm locally and globally
 doctor, login probing and isolated extraction without contacting a model or using real credentials.
 These prove launcher plumbing, not live Codex authentication or semantic quality. Browser and live
 authentication follow-up remain deferred at the maintainer's request.
+
+
+Traversal hydration in the next minor candidate keeps the built-in Codex source/prompt contract
+unchanged. Its validated `documentTraversal` controls are excluded from the Codex artifact pool
+partition; classification is attached during assembly. Validation documents are excluded from
+semantic calls and counted only against traversal read limits. Module providers use a separate
+full-config namespace in traversal mode, including workspace storage. Modules with mutable
+external inputs must version their declared identity or force extraction; unchanged source/config
+reuse does not discover those external dependencies. See [ADR 026](ADR-026-traversal-hydration.md).