@weftlet/toolkit 0.5.0 → 0.6.1

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/ADR-028-bounded-artifact-paths.md

@@ -0,0 +1,58 @@
+# ADR 028: bounded physical artifact names
+
+Status: implemented; release status is recorded in [validation](VALIDATION.md).
+
+The consumer reported that long physical artifact/temp names block the traversal → unchanged
+repeat → clean-comparison sequence on Windows. A public regression using traversal, routing and
+an empty runtime-evidence revision reproduces `ENAMETOOLONG` in real SCIP during clean comparison
+on Linux too. Appending `.scip.<UUID>.tmp` to the complete logical identity exceeds the common
+255-byte filename-component limit. RDF and optional OML work directories also embedded the entire
+identity. This is a physical storage defect, not a graph identity, business-rule or SHACL defect.
+
+## Physical names and compatibility
+
+Keep portable literal artifact keys of at most 128 ASCII characters. Longer/nonportable keys
+use `~` followed by the full SHA-256 of the logical key. The `~` namespace is excluded from
+literal logical storage identifiers, preventing a hash from aliasing a user-supplied short key.
+Windows device names are also hashed. Existing logical identifier validation and its 256-character
+limit remain intact; no snapshot, fact, provenance, extractor or cache identity is shortened.
+
+Snapshot JSON, heads, semantic cache storage and SCIP output use this mapping. Generated semantic
+cache keys are already 64-character digests and retain their names. Snapshot reads fall back to
+the old literal filename if the bounded path is absent. Semantic reads retain explicit legacy
+root handling. Skip legacy components that cannot exist within the filename limit (and Windows
+device names on Windows), but propagate other I/O and corrupt-JSON errors.
+
+Existing legacy immutable snapshots/artifacts are checked before publication and retained byte
+for byte. A different content/output digest for the same identity remains an error. Updating a
+long legacy head writes the new bounded head and gives it precedence without modifying history.
+No bulk cache migration, forced extraction or automatic deletion is required. Older toolkit
+versions cannot necessarily read newly hashed long-name entries; use supported store/CLI queries
+with the full logical ID rather than constructing a filename from it.
+
+Staging names are independent UUIDs in the destination directory, preserving same-filesystem
+atomic link/rename publication. Cross-process immutable winner and head replacement semantics
+remain unchanged. SCIP staging files are cleaned after success or failure. RDF/optional OML work
+directories need only a backend prefix and UUID; RDF output digests do not depend on their names.
+The optional OML generated document filenames remain their existing semantic digest keys.
+
+This bounds toolkit-generated components; it does not promise that arbitrary storage-root lengths
+or user source filenames work with every external program's total-path restrictions. The original
+working checkout is not moved or cleaned. Full logical IDs remain in snapshots, head records,
+facts and query responses, and saved evidence remains queryable without providers.
+
+## Validation boundary
+
+The public sequence uses the unchanged Codex adapter with its offline grammar runner, real SCIP,
+RDF/SHACL, document traversal, configured routing and an injected empty runtime provider. First
+hydration extracts six semantic documents; repeat and clean comparison reuse all six. The clean
+identity retains traversal/clean/runtime suffixes and exceeds 215 characters. Content digests and
+all facts/provenance except the containing snapshot ID agree; the original head stays unchanged.
+Generated components are bounded and no staging files remain. The exact sequence is part of the
+existing native Windows traversal suite as well as the Linux suite.
+
+Storage regressions cover 256-character snapshot/artifact/head keys, concurrent immutable writes,
+concurrent head replacement, legacy reads without rewriting bytes, legacy cache roots, collisions
+and unsafe input rejection. Existing cross-process publication tests remain required. Live provider
+calls, private TradePilot acceptance and live openCAESAR compilation are separate; this patch does
+not claim them or change validation constraints, graph semantics or evidence authority.

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).
@@ -134,10 +134,12 @@ does not establish what the agent saw. Also retain a short account of what the a
 in its implementation or test plan because of these results, and the actual test outcomes.
 
 Retain the selected immutable snapshot, not just the mutable head pointer. With workspace
-storage, it is `<repositoryRoot>/<storagePath>/snapshots/<snapshotId>.json`; the default
-`storagePath` is `.context-graph`. `storageScope: "user"` instead uses a configuration/checkout
-hash directory under `~/.cache/context-graph`. Preserve the original store and exact
-configuration if its resolved path is uncertain. Semantic artifacts under `artifacts/semantic/`
+storage, snapshots are under `<repositoryRoot>/<storagePath>/snapshots/`; the default
+`storagePath` is `.context-graph`. Long physical filenames are hashed: identify the selected
+record by its full `manifest.snapshotId`, not by constructing a filename from that ID.
+`storageScope: "user"` instead uses a configuration/checkout hash directory under
+`~/.cache/context-graph`. Preserve the original store and exact configuration if its resolved
+path is uncertain. Semantic artifacts under `artifacts/semantic/`
 contain model output; keep them locally if extraction debugging is needed. They are not
 required to query an existing snapshot. Do not copy credentials or whole account directories.
 

package/docs/GRAPHIFY-EVALUATION.md

@@ -0,0 +1,70 @@
+# Graphify evaluation for the pre-1.0 baseline
+
+Status: preliminary source/document review on 2026-10-28. **No comparative execution or
+replacement decision yet.** This is B2 of the [baseline plan](PRE-1.0-BASELINE.md).
+No Graphify dependency, code, binary, skill or service was installed into Weftlet. Public source
+was read at a pinned revision outside the repository; no private consumer material was used.
+
+## Reviewed candidate
+
+- Repository: [Graphify-Labs/graphify](https://github.com/Graphify-Labs/graphify).
+- Reviewed commit: `0a8cd4e1e342235fe53e881fb5d591bf0460071f` on its `v8` branch.
+- That commit's [package manifest](https://github.com/Graphify-Labs/graphify/blob/0a8cd4e1e342235fe53e881fb5d591bf0460071f/pyproject.toml)
+  identifies distribution `graphifyy`, version `0.9.97`, Python >=3.10 and Apache-2.0 licensing.
+  This is source metadata, not verification that a particular registry archive matches it.
+
+The [README](https://github.com/Graphify-Labs/graphify/blob/0a8cd4e1e342235fe53e881fb5d591bf0460071f/README.md)
+describes local tree-sitter extraction, broader language coverage, document/rationale extraction,
+paths and agent integration. Marketing/benchmark claims are not adopted as Weftlet measurements.
+The code inspected below supports evaluating it as a richer code-evidence producer; it does not
+establish that it is more accurate than compiler-backed TypeScript indexing on our tasks.
+
+## Findings from source inspection
+
+| Area | Observed at the pinned revision | Implication for an experiment |
+| --- | --- | --- |
+| Code granularity | [Extractor models](https://github.com/Graphify-Labs/graphify/blob/0a8cd4e1e342235fe53e881fb5d591bf0460071f/graphify/extractors/models.py) represent function/call syntax, declarations, imports, aliases, exports and symbol uses. The [engine](https://github.com/Graphify-Labs/graphify/blob/0a8cd4e1e342235fe53e881fb5d591bf0460071f/graphify/extractors/engine.py) emits code relationships and source locations. | Evaluate function/method/call relationships that our current file/shared-symbol projection does not expose. AST structure alone does not establish complete dynamic calls or data flow. |
+| Workspace resolution | [Resolution code](https://github.com/Graphify-Labs/graphify/blob/0a8cd4e1e342235fe53e881fb5d591bf0460071f/graphify/extractors/resolution.py) handles TypeScript aliases, project references, workspace/import/export origins and ambiguous barrel candidates. Its comments explicitly describe skipped npm-package tsconfig extensions. | Exercise our actual alias/barrel/same-name/TSX cases rather than assuming all pnpm projects resolve. Preserve unresolved and ambiguous outcomes. |
+| Identity | [Base identity helpers](https://github.com/Graphify-Labs/graphify/blob/0a8cd4e1e342235fe53e881fb5d591bf0460071f/graphify/extractors/base.py) derive file/symbol prefixes from paths; comments describe a later repository-relative remap. | Test roots, collisions, repeated names, rename/delete and clean/dirty isolation. Map imported entities into Weftlet's canonical identity and snapshot provenance instead of adopting labels as join keys. |
+| Evidence semantics | Extracted edges carry source file/location and `EXTRACTED` or `INFERRED` tags. | These tags do not mean owner-approved intent, observed runtime behavior or successful test execution. Measure citation precision and retain derivation when transforming facts into RDF. |
+| Deployment | The manifest depends on Python, NetworkX and multiple tree-sitter grammars; its optional services/providers are separate features. | Account for installation, platform support, artifact sizes, process boundaries, licensing and maintenance. Do not introduce hosted services or paid inference to compare static code extraction. |
+
+Graphify already covers documents and rationale too. The comparison initially isolates code
+extraction so that changing document inputs/providers cannot explain an apparent code improvement.
+Its [published benchmark](https://github.com/Graphify-Labs/graphify/blob/0a8cd4e1e342235fe53e881fb5d591bf0460071f/BENCHMARKS.md)
+reports an ERPNext six-question evaluation and a small FastAPI inferred-edge audit, including
+noisier same-name test helpers. Those are upstream-reported results, not a TypeScript comparison
+against Weftlet or SCIP and not evidence for complete asynchronous or business-rule linkage.
+
+## Fixed comparison protocol
+
+1. Freeze public source commits, expected relationships, negative cases, query/page budgets,
+   platform, versions and resource ceilings before measurement. Reuse the A1–A3 fixtures and
+   the existing dispatch negative case; add function-level examples without changing old labels.
+2. Compare **the current Weftlet SCIP projection**, **a bounded richer projection of raw SCIP**,
+   and **pinned Graphify static extraction**. Record raw index coverage separately from what
+   each adapter exposes. Do not attribute information discarded by our projection to SCIP itself.
+3. Include exact symbols, local/private functions, aliases, barrel exports, overloads, duplicate
+   names in separate domains, test mocks, TSX and service packages. Include a declared queue
+   boundary, a stored-data handoff and an undeclared boundary. The expected result for an
+   unsupported boundary is an explicit gap, not a guessed edge based only on a matching string.
+4. Hold business documents and their approved source classifications fixed. Check that the same
+   business-to-code links survive, then evaluate any finer function bindings separately. Keep
+   inferred mappings, source approval and reviewed assertions distinct.
+5. Measure precision/recall against predeclared edges, correct task-level consumers, false joins,
+   unresolved targets, citation validity, identity stability, cold/repeat/edit time and peak memory.
+   Compare same-process and subprocess measurements honestly. Count install/transfer overhead.
+6. Exercise deletion/rename, repeated clean runs, isolated committed materialization and dirty
+   queries. Retain old snapshots. Prove RDF/SPARQL/traversal equivalence for imported facts;
+   reject incompatible identities rather than weakening SHACL or dropping contradictory evidence.
+7. Run in a disposable tool environment with model calls disabled. Record reproducible commands
+   and sanitized outputs. Any live semantic experiment needs a separate bounded budget and
+   authorization before substantial paid usage. No private application checkout is modified.
+8. Produce an ADR choosing to keep SCIP, improve its projection, add an optional supported
+   producer, or replace the default. Replacement is a valid outcome if evidence supports it;
+   two permanently required indexers are not a prerequisite. If a change is selected, implement
+   compatibility/versioning and fresh-install tests as a separate milestone before publication.
+
+Graphify does not become a second authority for product intent merely by importing its graph.
+Neither tool can establish an undocumented business mapping from graph density alone. B3/B4
+must address those evidence and meaning questions independently of the code backend decision.

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/PRE-1.0-BASELINE.md

@@ -0,0 +1,94 @@
+# Business-context baseline before 1.0
+
+Status: added at the maintainer's request on 2026-10-28 after publication of the 0.6.0
+candidate. This extends the original T01–T10 task list; its completion did not establish
+automatic rule-to-function discovery or complete agent exploration. The candidate remains
+available for TradePilot acceptance while the work below is assessed. No new release is
+announced by this plan.
+
+The product goal is to let an agent starting with a task or code change retrieve the relevant
+product obligations, understand their connections across domains and asynchronous service
+boundaries, and inspect the implementations, contracts and evidence behind those connections.
+The agent must be able to investigate further without confusing a bounded response with
+complete coverage. A functioning extraction/publication pipeline is necessary but insufficient.
+
+## What we checked now
+
+Runtime source baseline: `9b4acffe1c4d35f9fd2f91132c576f8934658677`, the documentation follow-up
+to release source `b4c808b9221c5c82f9f7326a310e966d1fee2888`. Both package versions are 0.6.0.
+New acceptance tests use that unchanged runtime. Results and commands are recorded in
+[the assessment](assessments/pre-1.0-2026-10-28.json) and [validation](VALIDATION.md).
+
+| Acceptance case | Current result | What remains unproven or missing |
+| --- | --- | --- |
+| **A1 — Business context across an asynchronous or stored-data boundary** | **Bounded mechanism PASS.** An upstream file has no code/symbol connection to the downstream service in the control. Adding a cited workflow handoff makes execution, notifications, mobile and a test reachable. Both producer and consumer freshness obligations survive with their citations and unreviewed assertion authority. An unrelated domain with the same rule label stays excluded. | This is extraction from a deterministic public prose grammar. No live semantic comprehension, actual database/BullMQ delivery, automatic business compatibility verdict or private consumer acceptance is established. |
+| **A2 — Progressive agent exploration** | **Existing operations PASS; requested experience PARTIAL.** Small pages through the actual MCP facade exhaust to exactly the larger scan without duplicates. A focused follow-up retrieves the downstream rule. Depth exhaustion is explicit; changing the query rejects an old continuation. | No dedicated exact-node neighbor/path MCP operation with relation/direction filters or explicit unexplored neighbor inventory. Scripted facade requests are not an autonomous-agent usefulness study or a new transport test. |
+| **A3 — Multiple services and client packages in one monorepo** | **Configured public fixture PASS.** Real SCIP resolves a re-exported workspace contract used by API and TSX client code. Document relationships connect separately located API, execution and notification services and the client. Repeat hydration reuses all five documents with unchanged snapshot identity/content. | A synthetic pnpm workspace uses explicit source includes/aliases in one indexing program. This is not a full pnpm installation, multiple service builds, Expo validation, automatic workspace discovery or a run against TradePilot. Per-service coverage and real package resolution still need consumer evidence. |
+
+The [three new tests](../tests/business-context-acceptance.test.ts) hydrate an independent Git
+repository through the real application, semantic-provider contract, SCIP, document linker,
+RDF/SHACL, saved storage and query path. The fixture provider parses only its documented small
+grammar; it makes no model request and does not inspect implementation bodies. The control
+already includes both sides' documents. The only added source evidence is the collection-to-
+execution handoff. It re-extracts one document and reuses four; the next unchanged hydration
+extracts zero and reuses five. Prior snapshots remain intact. No facts are manually spliced into
+the assembled graph to obtain the positive result.
+
+The two freshness limits (600 seconds at collection, 60 seconds at execution) are deliberately
+different. They can be compatible when the consumer checks freshness. The test asserts retrieval
+of both obligations and **does not assert a conflict or compliance verdict**. Runtime evidence
+and evaluated business invariants are empty. Source approval never approves the model assertion.
+
+Existing routing, query, RDF and workspace-indexing tests were also rerun: **24 passed**, followed
+by **3 new acceptance tests passed**. Existing routing negatives reject false same-channel joins
+and ambiguous/missing endpoints. Existing indexing checks cover dirty inputs, renames and deletes.
+These results supplement, and do not replace, the published release's validation record.
+
+Reproduce the focused assessment from a configured development checkout:
+
+```sh
+pnpm exec vitest run tests/business-context-acceptance.test.ts tests/rdf.test.ts tests/routing.test.ts src/extraction/routing.test.ts src/extraction/scip-project.test.ts src/graph/query.test.ts
+```
+
+## Subsequent task list
+
+These are bounded pre-1.0 investigations and implementation tasks, not a claim that the features
+are delivered. Record decisions and exact acceptance evidence per task. Any deferral must be
+explicitly reviewed with the maintainer; do not convert missing evidence into a pass. TradePilot
+blockers take priority when its report arrives. Do not modify or audit its application here.
+
+| ID | Task / next action | Acceptance boundary |
+| --- | --- | --- |
+| **B1** | **Exact graph exploration.** Specify and add bounded node lookup/neighbor expansion and dependency-path exploration through MCP and the shared query layer. | An agent can start from a returned stable node ID, select relation/direction and inspect another business area. Return citations, authority, snapshot identity, incomplete scope, pagination and remaining frontier. Test branches, cycles, ambiguous labels, deleted nodes and stale/mismatched continuations. Keep CLI/MCP/viewer on the same facts; preserve existing `impact.scan`. |
+| **B2** | **Evaluate Graphify and current SCIP representation.** Run the fixed public comparison in [the research note](GRAPHIFY-EVALUATION.md) before choosing a code extraction backend or symbol schema. | Compare the current projection, richer use of raw SCIP and pinned Graphify on identical committed inputs. Measure correct/missing/false links, provenance, identity stability, costs and packaging. Produce a keep/improve/replace decision with evidence. Parallel use during evaluation does not mandate shipping two indexers. |
+| **B3** | **Resolve business-to-implementation links at symbol/function level.** After B2, define canonical scoped code identities and resolve explicit document paths/symbol references to exact code entities. Evaluate a separate bounded inference pass only where explicit evidence is insufficient. | Named functions, methods, aliases, overloads, same-name symbols and renamed/deleted targets resolve correctly or remain unresolved. Separate a cited declared mapping, a proposed inferred mapping and evidence of actual behavior. Record both document and code revisions/spans for derived links. A reviewer can follow a rule to its implementation and back. Code inference never supplies approval; full automatic documentation generation remains 2.0. |
+| **B4** | **Cross-boundary obligations.** Represent and retrieve producer guarantees and consumer requirements through explicit data/event contracts, including applicable stage, domain, units, freshness and version where sources provide them. | Public cases cover a queue handoff, a write/read handoff, compatible differing limits with revalidation, a real documented incompatibility, missing links and same-name unrelated domains. Retrieve both sides and the implementation evidence. Potential model findings remain uncertain; hard failures require explicit approved deterministic rules. A graph link or SHACL pass is not a compatibility verdict. General reconciliation/approval UI remains 2.0. |
+| **B5** | **Monorepo selection and coverage.** Assess diagnostics for selected services, client, shared packages, source aliases and excluded/unresolved code; improve the gaps found. | A configured multi-package TypeScript/TSX fixture and the consumer report identify which projects were selected, indexed and actually connected. Test barrel exports, independent service code, external unresolved dependencies and omitted projects. Missing resolution cannot be reported as zero impact or complete coverage. Cross-repository federation is a separate scope decision. |
+| **B6** | **End-to-end product acceptance and release decision.** Combine the public evidence, B1–B5 decisions and TradePilot's actual 0.6.0 report; ship bounded candidate changes as needed. | Predeclare tasks, correct downstream business obligations/implementations, known unrelated matches and query budgets before measuring. Retain actual requests, follow-up decisions and citations. Assess helpfulness and misses separately from hydration success. Complete full hydration/repeat and supported release checks; review any remaining limitations before a versioned 1.0 publication. |
+
+Order: retain this A1–A3 baseline; triage incoming consumer blockers; specify B1 and run the
+bounded B2 comparison; use that decision for B3; implement B4/B5 in independently testable
+increments; close B6. Each implementation can ship in a minor candidate before 1.0. Changes to
+retrieval semantics, extraction/cache identity or snapshot compatibility need explicit decisions
+and regression evidence; no silent migration or history rewrite.
+
+## Consumer report to reconcile when available
+
+Retain the private configuration, documents, snapshots and transcripts with TradePilot. Share
+only a sanitized report identifying package versions, source/adapter SHA, indexing/document
+scope, phase timings, full validation/publication, unchanged reuse and query coverage.
+
+For A1, choose one actual upstream-to-downstream queue or stored-data change and record how the
+graph witnesses the handoff, each side's obligations and the associated implementations. Note
+whether a relationship came from prose, an explicit mapping, code or an observed trace. For A2,
+retain the initial request, follow-up choices and all truncation/continuation states. For A3,
+record the expected service/client projects and which were indexed, reached or missing. Have a
+human assess business usefulness; an automated pass here is not a replacement.
+
+## Boundary with 2.0
+
+The [2.0 plan](WEFTLET-2.0-PLAN.md) still owns bulk code-derived documentation, durable approval
+workflows, cross-source reconciliation management, source-document backfill, the companion
+website, hosted AI/billing and unrelated source adapters. This baseline concerns connecting and
+exploring local evidence accurately. No service, provider billing, new dependency, source adapter,
+automatic write-back, package publication or product-policy change is introduced by this assessment.

package/docs/PROVIDERS.md

@@ -135,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`
@@ -204,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).