@weftlet/toolkit 0.5.0 → 0.6.0

package/dist/visualization/visualization.js

@@ -1,7 +1,10 @@
 // Modified for standalone extraction; see docs/extraction-manifest.json.
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, extname, resolve } from 'node:path';
+import { repositoryFileNode } from '@weftlet/core';
 import { contextPackEvidenceAuthority, contextPackLaneForFact } from "../graph/query.js";
+import { coverageDescription } from '../graph/coverage.js';
+import { documentSelectionDescription, sourceDocumentDescription } from '../graph/document-role-description.js';
 import { viewerScript } from "./viewer-interaction.js";
 import { diagnosticSummary } from "../graph/diagnostics.js";
 export const MAX_VISUALIZATION_FACTS = 200;
@@ -67,7 +70,7 @@ function visualColumn(kind, selectedLanes) {
     }
     return 'implementation';
 }
-function addNode(nodes, node, selectedLanes) {
+function addNode(nodes, node, selectedLanes, ownValidationSource = false) {
     if (nodes.has(node.id))
         return;
     nodes.set(node.id, {
@@ -75,7 +78,7 @@ function addNode(nodes, node, selectedLanes) {
         label: node.label,
         kind: node.kind,
         cluster: String(node.attributes?.module ?? node.attributes?.layer ?? node.kind),
-        column: visualColumn(node.kind, selectedLanes),
+        column: ownValidationSource && node.kind === 'Document' ? 'evidence' : visualColumn(node.kind, selectedLanes),
     });
 }
 function assertVisualizationBounds(pack) {
@@ -104,8 +107,16 @@ function visualModel(pack, sourceUrlTemplate) {
     assertVisualizationBounds(pack);
     const nodes = new Map();
     const selectedLanes = new Map();
+    const validationDocuments = new Set();
     const edges = [];
     for (const fact of pack.facts) {
+        if (fact.sourceRole === 'validation') {
+            const citedDocument = repositoryFileNode(fact.provenance.path);
+            if (citedDocument.kind === 'Document' &&
+                [fact.subject, fact.object].some(node => node.kind === 'Document' && node.id === citedDocument.id)) {
+                validationDocuments.add(citedDocument.id);
+            }
+        }
         const lane = contextPackLaneForFact(fact);
         if (!lane)
             continue;
@@ -116,8 +127,9 @@ function visualModel(pack, sourceUrlTemplate) {
         }
     }
     for (const fact of pack.facts) {
-        addNode(nodes, fact.subject, selectedLanes.get(fact.subject.id));
-        addNode(nodes, fact.object, selectedLanes.get(fact.object.id));
+        addNode(nodes, fact.subject, selectedLanes.get(fact.subject.id), validationDocuments.has(fact.subject.id));
+        addNode(nodes, fact.object, selectedLanes.get(fact.object.id), validationDocuments.has(fact.object.id));
+        const sourceDescription = sourceDocumentDescription(fact);
         edges.push({
             id: fact.id,
             from: fact.subject.id,
@@ -125,7 +137,8 @@ function visualModel(pack, sourceUrlTemplate) {
             label: fact.predicate,
             authority: contextPackEvidenceAuthority(fact),
             provenance: `${fact.provenance.path}:${fact.provenance.startLine}`,
-            detail: `confidence ${fact.confidence}; ${fact.extractor.id}@${fact.extractor.version}; source ${fact.sourceAuthority ?? 'see citation'}; extraction ${fact.extractionReview ?? 'unspecified'}`,
+            detail: `confidence ${fact.confidence}; ${fact.extractor.id}@${fact.extractor.version}; source ${fact.sourceAuthority ?? 'see citation'}; extraction ${fact.extractionReview ?? 'unspecified'}` +
+                (sourceDescription ? `; ${sourceDescription}` : ''),
             source: fact.provenance,
             sourceUrl: sourceLink(fact.provenance, sourceUrlTemplate),
         });
@@ -398,6 +411,7 @@ export function renderContextPackHtml(pack, sourceUrlTemplate) {
     Excluded working paths: ${pack.evidenceState?.excludedWorkingChanges.length ?? 'unknown'}.
     ${pack.snapshot.overlayDigest ? `Overlay freshness: ${escapeXml(pack.evidenceState?.overlayFreshness ?? 'unknown')}.` : ''}
     This view does not validate the current diff.</p>
+    <p>${escapeXml(documentSelectionDescription(pack.snapshot.documentSelection))}</p>
     <p>${pack.exploration ? `${pack.exploration.returned}/${pack.exploration.reachableFacts} reachable facts on this page; max depth ${pack.exploration.maxDepth}; ${pack.exploration.truncated ? 'TRUNCATED' : 'not truncated within this scope'}${pack.exploration.depthLimitReached ? '; depth limit reached — rerun with greater --max-depth' : ''}` : 'Query completeness metadata unavailable.'}</p>
     ${pack.exploration?.continuation ? `<details><summary>Continue agent/CLI query with this token</summary><code>${escapeXml(pack.exploration.continuation)}</code></details>` : ''}
     ${pack.evidenceState?.excludedWorkingChanges.length ? `<details><summary>Excluded working changes</summary>${detailList(pack.evidenceState.excludedWorkingChanges, '')}</details>` : ''}
@@ -410,10 +424,11 @@ export function renderContextPackHtml(pack, sourceUrlTemplate) {
       <section class="panel"><h2>Runtime references</h2>${detailList(pack.runtimeEvidence.map(reference => `${reference.serviceName}: ${reference.operation ?? 'observation'} · ${reference.sourcePath} · ${reference.observedAt ?? 'time unknown'}`), 'None in this page.')}<p>Edges are only the facts returned by the agent query. References do not create extra relationships.</p></section>
       <section class="panel">
         <h2>Coverage</h2>
+        <p>${escapeXml(coverageDescription(pack.coverage))}</p>
         ${Object.entries(pack.coverage.counts)
         .map(([lane, count]) => `<span class="metric">${escapeXml(lane)}: ${count}</span>`)
         .join('')}
-        ${detailList(pack.coverage.gaps, 'No Context Pack lane gaps detected.')}
+        ${detailList(pack.coverage.gaps, 'No coverage gaps detected on this returned page.')}
       </section>
       <section class="panel">
         <h2>Governing invariants</h2>

package/docs/ADR-017-shacl-validation-union.md

@@ -3,6 +3,10 @@
 Status: accepted and implemented in the focused 0.3.0 release; absent from 0.2.1.
 See [validation](VALIDATION.md) for checks and recorded publication evidence.
 
+Follow-up: [ADR 027](ADR-027-validation-closeout.md) records the completed T05 engineering
+evaluation and retains full direct validation. The measurements and remaining-work section below
+describe the original focused release; private consumer acceptance remains separate.
+
 ## Problem and measured mechanism
 
 The canonical RDF dataset has one named relationship graph per assertion, with assertion records,

package/docs/ADR-021-identity-preflight-and-validation-timing.md

@@ -1,7 +1,10 @@
 # ADR-021: Early identity conflicts and honest validation phase timing
 
-Status: implemented in development source after 0.4.0. Publication and consumer acceptance
-are separate checkpoints in [validation](VALIDATION.md). This is the bounded T05a increment.
+Status: shipped in 0.5.0 after local/hosted checks and independent archive review; release evidence
+is in [validation](VALIDATION.md). Consumer acceptance remains a separate checkpoint.
+This is the bounded T05a increment. Follow-up [ADR 027](ADR-027-validation-closeout.md) records
+the broader T05 engineering evaluation; the remaining-work section below describes this original
+increment. Private consumer performance acceptance remains separate.
 
 ## Decision
 

package/docs/ADR-022-release-documentation.md

@@ -0,0 +1,44 @@
+# ADR-022: Versioned installation documentation checked against release archives
+
+Status: implemented for T06 after 0.5.0; validation is recorded separately in
+[validation](VALIDATION.md). This changes release tooling and packaged documentation, not graph semantics.
+
+## Decision
+
+The two package manifests own the version of the current checkout/archive. Marked sections in
+the toolkit README, core README and release guide are generated from those manifests. They do
+not claim a version is already published: a Changesets version PR can precede registry availability.
+Publication evidence remains in the validation record and package-specific releases.
+
+`scripts/release-documentation.mjs` uses Node built-ins. It is usable by the publish job, which
+installs no project dependencies. Versioning regenerates the marked sections after Changesets
+updates the manifests and before the extraction inventory is refreshed. Missing, duplicate or
+malformed markers fail rather than causing unrelated prose to be overwritten.
+
+Source checks compare the complete generated sections and check explicit package pins and
+Weftlet archive names in active installation examples. The maintained scope is the two READMEs,
+`docs/RELEASING.md`, `docs/MIGRATING-TO-WEFTLET.md` and `docs/CONSUMER-TRIAL.md`.
+Feature introductions, earlier release records and historical inspection commands remain intact.
+Historical installation fences require an explicit `weftlet-history` classification; this is a
+reviewed documentation exception, not an automatic exemption based on an old version number.
+
+Packed checks read the actual two tarballs. Package names, versions, archive filenames and the
+toolkit's core dependency must match the release group. Required operational documents must be
+present and match the reviewed source, allowing equivalent LF/CRLF checkout representations.
+The same documentation checks run on those packed documents. Both archives are checked before
+any publish operation, including when publication resumes from prepared artifacts.
+
+The fresh-consumer smoke uses constrained argument arrays obtained from the checked current
+examples. It installs the documented archive pair and runs the documented pinned setup and
+configuration-validation commands against a disposable registry serving those archives. It
+never evaluates arbitrary Markdown as shell code and makes no model requests.
+
+## Boundaries
+
+This is a release-documentation check, not a natural-language verifier or general shell parser.
+New current version statements belong in the generated sections. New installation guides must
+be added to the explicit operational-document scope to receive the same checks. Historical
+validation records, changelogs, feature-introduction versions and private consumer documentation
+are not automatically rewritten. Existing immutable npm archives are unchanged.
+
+T07 document selection/authority and broader T05 validation progress/reuse remain separate.

package/docs/ADR-023-document-coverage-preview.md

@@ -0,0 +1,64 @@
+# ADR-023: Prospective committed document coverage
+
+Status: implemented as T07a after T06; source validation and publication are separate in
+[validation](VALIDATION.md). T07b classification/evidence and T07c hydration integration remain planned.
+
+## Decision
+
+`weftlet documents plan` and `planDocumentCoverage()` inspect the committed Markdown-link closure
+from explicit entry points. The report is `document-coverage-plan`, with `mode: prospective` and
+`changesHydrationSelection: false`. It is separate from `hydrate --plan`, whose inputs and cache
+estimates continue to describe actual hydration. No provider, adapter, indexer, cache, snapshot,
+runtime source or ontology compiler is initialized or written by the new operation.
+
+Entry points, exact scope roots and read limits are operation arguments. This increment adds no
+hydration configuration fields and changes no cache partitions, extractor versions or graph
+assembly identities. Existing config supplies repository identity, explicit approval/evidence-root
+labels and semantic budgets for comparison. This avoids making an unused traversal setting
+invalidate current snapshots or cached artifacts.
+
+The new NUL-delimited Git tree reader preserves exact committed paths and records type, mode,
+object ID and byte size, including directories, symlinks and gitlinks. It scopes correctly to a
+nested repository root. Existing Git listing/extraction APIs are unchanged. Invalid UTF-8 tree
+paths or malformed metadata fail closed instead of silently disappearing from the index.
+
+A separate canonical-link parser follows direct Markdown links and used reference definitions.
+It retains source lines, definition/use positions and conflicting definitions. It does not change
+the graph linker's existing treatment of bare and inline-code paths. Images, code examples, HTML
+and unused definitions do not become traversal edges. CommonMark-compatible links in Markdown,
+MDX and text files are supported; this is not a complete MDX/HTML parser.
+
+Relative paths resolve against their source document, leading `/` means repository root, and
+percent encoding and fragment/query removal are explicit. No basename/README guessing or remote
+fetch occurs. Malformed/escaping targets, scope exclusions, missing files, directories, symlinks,
+submodules and ambiguous references are reported distinctly. Scope roots bound document traversal;
+existing regular code/non-document targets outside those roots can still be classified without
+reading their contents. Resolved code links, external URLs
+and same-document fragments remain visible without being traversed. Visited-path deduplication
+terminates cycles while retaining every reaching-link occurrence.
+
+## Coverage and limits
+
+Traversal computes reachable supported documents before comparing extraction budgets. The
+existing `semantic.maxDocuments`/`maxSourceBytes` values apply only to that comparison; they never
+trim the traversal. Candidates include validation documents at this stage, so totals are not a
+promise of future model work. Missing links and unread descendants make coverage incomplete.
+`ready` requires complete supported local coverage and a passing budget comparison; it does not
+establish approved requirements, semantic quality, complete product coverage or hydration readiness.
+
+Separate read-safety limits default to 1,000 documents, 16 MiB total and 1 MiB per document,
+with ceilings of 10,000 documents, 64 MiB and 4 MiB respectively. Committed blob sizes are checked
+before reads; failed attempts count toward read limits. Discovered unread paths remain in the
+frontier and their descendants are explicitly unknown. Git metadata output is bounded to 64 MiB.
+The current string reader conservatively rejects NUL, byte-size mismatches and U+FFFD, including
+a literal replacement character, because it cannot prove lossless decoding in that case.
+
+Reports include commit, current configuration digest, coverage digest, paths, sizes, content
+digests, citations, issues and excluded working changes, but no document bodies. They are local
+diagnostic reports and may contain private paths/link destinations. Source approval matches
+remain explicit and do not propagate through links; prospective assertion review stays unreviewed.
+Evidence-root labels do not infer rule ownership or approve source assertions.
+
+Before traversal can drive extraction, T07b must preserve validation documents through a separate
+deterministic evidence path. T07c must connect the same selection to hydration, cache recovery and
+freshness checks, with real cross-source positive/negative fixtures and rename/delete behavior.

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 |