@stsepelin/checktrail 0.1.0-alpha.1

package/docs/TASK-STORAGE.md

@@ -0,0 +1,141 @@
+# Local validation task storage
+
+`openTaskStore` is an optional library component for retaining validation results
+on one local macOS or Linux machine. It is not connected to the CLI or MCP server.
+The store itself does not advertise the MCP Tasks extension, execute jobs,
+resume jobs, stop workers or act as a validation cache. The separate library
+[validation worker](VALIDATION-TASKS.md) now connects it to native execution. See [MCP compatibility](MCP-COMPATIBILITY.md)
+for the remaining wire and executor integration gates.
+
+The implementation uses Node's built-in SQLite module, imported only when the
+store is opened. Native tests cover Node 26.8.1 on macOS and Node 22.23.2 on Linux;
+the latter reports SQLite as experimental. Earlier Node releases, Windows and
+network filesystems are not verified storage profiles. Core imports do not load
+SQLite, and no new npm runtime dependency is required.
+
+## Use from the library
+
+Choose a dedicated storage directory with an existing canonical parent, outside
+the project's inventoried source. An existing store directory must belong to the
+current user with mode `0700`; database files must be singly linked regular files
+with mode `0600`. New directories and files use these modes. Symbolic links,
+unexpected directory entries and unrelated nonempty databases are rejected.
+
+```js
+import { createPlan, validate, openTaskStore } from "@stsepelin/checktrail";
+
+const store = await openTaskStore({
+  root: projectRoot,
+  directory: privateStoreDirectory,
+  detailed: false,
+});
+try {
+  const { plan } = await createPlan(projectRoot);
+  const task = store.create(plan.sourceFingerprint);
+  const report = await validate(projectRoot, { trusted: true });
+  const transition = store.complete(task.taskId, report);
+  if (transition !== "updated")
+    throw new Error("Task did not accept this result");
+  const retained = store.get(task.taskId);
+  // Consume retained.result.structuredContent as a report summary.
+} finally {
+  store.close();
+}
+```
+
+Execution trust still comes from the caller. The caller must use the configured
+root when validating; a source fingerprint is not proof of a particular root,
+policy or environment. `complete` rejects a report whose initial source
+fingerprint differs from the one recorded at creation. Full report shape is
+validated, then the existing report projection is applied before serialization.
+Summary databases never receive detailed report paths, commands or logs through
+this API. Summary metadata can still reveal validation activity and check IDs.
+
+Each database records a hash binding it to its canonical root and disclosure mode.
+Reopening with a different root or mode fails, including an attempt to open a
+detailed store as summary. Returned objects are detached snapshots. Stored
+results remain historical evidence: reading them does not establish freshness
+against current source, ignored dependencies or a changed toolchain.
+
+## State and ownership
+
+Creation commits before returning an opaque UUID. Result completion and
+cancellation transitions use SQLite transactions. A completed result retains the
+original validation outcome, including failed or incomplete outcomes; task
+completion never means that checks passed.
+
+Only one store handle may own a directory at a time, including within one process.
+A separate SQLite database holds an exclusive lock for the handle's lifetime.
+The operating system releases this lock when the owning process exits, including
+SIGKILL. Contending opens fail immediately; they do not recover or replace a live
+owner's tasks. There are no PID-reuse guesses or time-based ownership leases.
+
+On reopening, retained terminal results remain unchanged. Unfinished tasks become
+`completed` with a fixed `isError: true` tool result describing interruption, and
+no structured validation report. This matches the distinction between tool errors
+and JSON-RPC errors in the [Tasks specification](https://tasks.extensions.modelcontextprotocol.io/specification/2026-07-28/tasks).
+Interrupted work is never resumed or reported as passing. This store does not
+establish that child processes from a crashed executor have stopped; that requires
+executor lifecycle integration before exposing a durable MCP handle.
+
+Cancellation has two stages:
+
+1. `requestCancellation(id)` reserves cancellation while status remains `working`.
+   Subsequent completion returns `cancellation-requested` and cannot store a result.
+2. After the executor confirms workers have stopped, call `finishCancellation(id)`.
+   It changes status to `cancelled` without a report. Calling it without requesting
+   cancellation throws.
+
+`interrupt(id)` records the fixed tool error for an execution that cannot produce
+a retained report; it also respects terminal states and cancellation reservations.
+All terminal states are immutable through the API. A late transition returns
+`terminal`; missing or expired IDs throw. Repeated cancellation requests return
+`cancellation-requested`. A restart during cancellation produces an interruption
+error, not an unverified claim that worker termination succeeded. This profile
+has no interactive input or JSON-RPC error state.
+
+## Bounds and failure behavior
+
+- At most 32 retained tasks per directory. Capacity exhaustion rejects creation;
+  unexpired tasks are never silently evicted.
+- TTL defaults to 24 hours, measured from creation, and accepts integer milliseconds
+  from 1 through seven days. Wall-clock changes affect expiration. Expired IDs are
+  inaccessible; rows are pruned on creation or reopening.
+- Each serialized tool result is limited to 256 KiB of UTF-8, including both text
+  and structured representations. Oversized completion throws and leaves the
+  task working. Retained payloads therefore total at most 8 MiB.
+- SQLite uses 4 KiB pages with a 16 MiB database limit, DELETE journaling and FULL
+  synchronous commits. A rollback journal temporarily consumes additional bounded
+  space. The ownership database and accepted journal sizes have separate limits.
+- Short synchronous database operations run on the caller's thread. The store
+  rejects malformed state, mismatched result representations and corrupt databases;
+  it does not erase an unreadable store and claim successful recovery.
+
+File permissions and path checks assume trusted local ownership. They are not
+protection against another process with the same user's privileges replacing or
+modifying store files. Do not manipulate SQLite files while a handle is open.
+SQLite secure deletion is enabled, but expiry is not a secure-erasure promise for
+backups, filesystem snapshots or storage devices. Tests demonstrate process-crash
+recovery, not arbitrary hardware or power-loss durability.
+
+## Reproduce
+
+```sh
+npm run build
+node --test dist/test/task-store.test.js
+node scripts/verify-task-store-container.mjs
+```
+
+Native regressions cover real validation and reopening, same-process and
+cross-process contention, SIGKILL recovery, rollback of an uncommitted deletion,
+completion/cancellation ordering, capacity and TTL, UTF-8 byte limits, disclosure
+binding, private modes, links, foreign databases and malformed stored results.
+The container helper additionally verifies a fresh offline production-only package
+installation, native validation and reopening with networking disabled and the
+installed package mounted read-only. Hosted CI remains a separate release gate.
+
+Guard-removal experiments made the named cancellation and root-binding tests fail
+for their intended conditions: a late completion was accepted after cancellation
+reservation, and another project root could open the same store. Restoring each
+guard restored the tests. The rollback fixture forces dirty pages to spill to disk
+before killing its writer; it does not rely on an unflushed in-memory edit.

package/docs/TOOL-IDENTITY.md

@@ -0,0 +1,30 @@
+# Tool identity evidence
+
+Detailed plans include how selected tool identities will be obtained. Planning
+does not execute a version command or import project code. Validation captures
+identities only after operator trust, before running checks. Detailed reports
+retain the version, evidence method, native probe result or package metadata path.
+Summaries omit this information along with other tool/environment details.
+
+Native probes use the same bounded process runner, environment filtering,
+cancellation signal, overall deadline and output budget as validation commands.
+Each probe has an 8 KiB output limit. Identical probes under the same declared environment fingerprint are reused within one run;
+there is no persistent version cache. Missing, nonzero, truncated, cancelled or
+unrecognized version output is not identified. A successful check with an
+unidentified required tool becomes incomplete; an actual check failure stays a
+failure.
+
+Node uses the running engine's version because JavaScript child commands use that
+same executable path. Installed JavaScript tools use their package metadata,
+resolved within the configured root; both package name and version are checked.
+Python, Go, PHP and Ruff use version commands. Pytest and mypy use Python's installed
+distribution metadata through the same selected `python3` runtime.
+
+These methods identify the engine runtime and primary tools. Go's recorded version
+identifies the `go` command, not an independently replaced `gofmt` binary. JavaScript
+transitive tools, language plugins, compilers loaded behind another wrapper,
+dependency trees, executable hashes and service versions are not fully fingerprinted.
+Package metadata can be changed independently of code and is labeled accordingly.
+This is not binary attestation, hermetic reproducibility, or proof that any version
+is compatible. Native fixture results and the support matrix remain the evidence
+for compatibility.

package/docs/TYPESCRIPT-BUILD.md

@@ -0,0 +1,55 @@
+# TypeScript project-reference validation
+
+Select `javascript.typescript-build` on a solution root with `tsconfig.json` and
+an installed TypeScript compiler inside the configured repository. Unlike the
+single-project `javascript.typescript` check, this check inventories TypeScript
+source throughout the solution directory, including nested package boundaries.
+Every inventoried source must appear in a native compiler program. Unrelated or
+excluded source beneath that directory therefore makes the check incomplete.
+
+The adapter uses TypeScript's solution-builder API to follow references in native
+dependency order. It forces a fresh build, enables checking even when `noCheck`
+is configured, and supplies an in-memory output filesystem. Declarations flow
+from producers to consumers without writing JavaScript, declarations or build
+state to disk. `noEmit` is overridden for this virtual build; emission happens
+only in memory. Existing build state is not read, and virtual outputs shadow
+existing declarations. Other type-checking options remain project policy.
+
+Compiler/configuration diagnostics fail and retain native TS rule IDs and source
+locations where available. Missing runtime integration, unsupported compiler
+version, malformed evidence or omitted source is incomplete. Cyclic references
+produce the native compiler diagnostic. Empty solutions cannot pass.
+
+The integration is verified and version-gated to TypeScript 6.0.3. It uses the
+compiler API rather than replacing TypeScript semantics. It does not run custom
+build scripts, verify emitted bundles, install dependencies or validate Vue SFCs.
+Those require their corresponding separate checks. Installed compiler code runs
+only with operator trust and is not sandboxed.
+
+Compiler reads are constrained to the configured root, including canonical
+symlink targets. Missing/outside referenced configuration is rejected. Virtual
+outputs must stay within that root and are bounded to 64 MiB and 20,000 entries.
+References can cross the selected solution directory while staying inside the
+configured repository; source outside the selected directory is not thereby
+claimed as completely inventoried or validated. Select its own project or a
+common solution root when that coverage is required.
+
+## Evidence
+
+Synthetic native tests cover nested package boundaries, producer errors, changed
+producer types breaking consumers, the corrected consumer, excluded source,
+stale on-disk declarations/build state, cyclic references, escaped configuration
+and output destinations, and planning without compiler execution. Preservation
+assertions check original bytes and absent output paths. Parser tests cover
+missing programs, duplicate/outside paths and partial evidence.
+
+```sh
+npm run build
+node --test dist/test/typescript-build.test.js
+```
+
+Current native evidence is TypeScript 6.0.3 on macOS. Hosted platform runs remain
+separate verification gates.
+
+References: [project references](https://www.typescriptlang.org/docs/handbook/project-references.html),
+[compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API).

package/docs/VALIDATION-TASKS.md

@@ -0,0 +1,119 @@
+# Durable local validation worker
+
+`openValidationTasks` connects the shared validation engine to the bounded local
+[task store](TASK-STORAGE.md). This is a library API, not a daemon or an MCP
+extension. The CLI and MCP server still use their existing execution paths.
+Standard MCP Tasks remains unadvertised until its wire contracts and SDK routing
+work; see [MCP compatibility](MCP-COMPATIBILITY.md).
+
+## Use
+
+```js
+import { setTimeout as delay } from "node:timers/promises";
+import { openValidationTasks } from "@stsepelin/checktrail";
+
+const tasks = await openValidationTasks({
+  root: projectRoot,
+  directory: privateStoreDirectory,
+  allowExecution: true,
+  detailed: false,
+  timeoutMs: 30000,
+});
+try {
+  let task = await tasks.start();
+  while (task.status === "working") {
+    await delay(250);
+    task = await tasks.get(task.taskId);
+  }
+  console.log(task);
+} finally {
+  await tasks.close();
+}
+```
+
+The store directory must satisfy the canonical-parent, private-permission and
+local-filesystem requirements in `TASK-STORAGE.md`. Keep it outside inventoried
+source, or inside an excluded directory. Native lifecycle tests cover macOS with
+Node 26.8.1 and Linux with Node 22.23.2. Node 22's built-in SQLite is experimental.
+The worker calls the same engine and adapter registry; the new worker-specific
+native fixtures exercise Node validation, rather than claiming another full
+native-toolchain compatibility matrix.
+
+Execution permission, output mode, timeout, Git base, policy overlay, explicit
+environment values and external adapter registrations are startup settings.
+`start()` takes no arguments that can change them. Opening with
+`allowExecution: false` permits reading retained results but rejects execution.
+Starting a worker does not evaluate project source. The helper uses the current
+Node executable, empty Node startup arguments and a narrow inherited environment;
+parent `NODE_OPTIONS` preloads are not forwarded. Project execution still has the
+user's privileges and is not sandboxed.
+
+## Operations and results
+
+- `start()` performs execution-free planning, durably creates a task, then starts
+  validation. It returns the working task with an opaque ID. One validation or
+  pending start is allowed at a time; overlap is rejected, not silently queued.
+- `get(id)` returns a detached snapshot while validation continues. Completed
+  reports retain their native `passed`, `failed` or `incomplete` outcome. A task
+  with status `completed` does not by itself indicate that checks passed.
+- `cancel(id)` reserves cancellation, aborts the shared engine, waits for process
+  cleanup and then returns the terminal task. Completed tasks stay unchanged.
+- `close()` rejects new work, stops active validation, waits for cleanup and
+  releases the store. It is idempotent. Always await it during normal shutdown.
+
+The client wrapper bounds pending requests at 32. The store bounds retained tasks,
+result bytes and disk pages separately. Task TTL is the store default of 24 hours;
+this worker API does not accept per-call TTL overrides. Validation uses the
+engine's timeout contract, defaulting to 30 seconds and accepting at most 120.
+Timeouts retain native incomplete evidence when it fits the configured result
+projection. Invalid, missing and expired IDs fail without exposing filesystem
+paths or raw exceptions.
+
+If validation throws, source identity no longer matches the task, or the selected
+result projection exceeds the store limit, the task retains an explicit
+`isError: true` interruption result with no structured validation report. A large
+detailed report can exceed the limit even when its summary fits. A persistence
+failure that also prevents recording interruption shuts down the worker; it is
+not converted into a passing result. Historical results are not revalidated or
+used as a cache on retrieval.
+
+## Ownership and parent loss
+
+A child Node process owns both the SQLite handle and the active engine call. The
+parent communicates through a local IPC channel; raw tool output is not forwarded
+to the parent's stdout or stderr. The worker keeps the store's exclusive lock
+until cleanup finishes, preventing a new owner from taking over live work.
+
+When the parent disconnects or is killed, the worker detects the lost IPC channel,
+reserves cancellation, aborts validation and closes the store after cleanup. Native
+tests confirm that the running test and its ordinary descendant stop before the
+worker's normal shutdown completes. SIGTERM and SIGINT to the worker use the same
+cleanup path. The caller waits for process exit; it does not depend exclusively
+on Node emitting `close` after simultaneous IPC disconnects.
+
+This behavior covers loss of the parent while its worker survives to clean up.
+It is not proof of cleanup if the worker itself is forcibly killed, native code
+escapes its process group, or the operating system fails. After an abrupt store
+owner death, the existing store recovery records unfinished work as an
+interruption error and never resumes it. Broader orphan-process supervision is a
+separate capability; no stronger guarantee is advertised here.
+
+## Reproduce
+
+```sh
+npm run build
+node --test --test-timeout=15000 dist/test/validation-tasks.test.js
+node scripts/verify-task-store-container.mjs
+```
+
+The native regressions exercise passing/failing/empty validation, retained results,
+read-only reopening, trust and preload boundaries, responsive polling, overlap,
+explicit cancellation, shutdown, parent SIGKILL, native descendants, timeout,
+oversized output and close during planning. The container helper additionally
+checks this API from a fresh offline production-only installation, with networking
+disabled and the installed package mounted read-only. The corresponding hosted
+Linux Node 22 step passed at `52ba415`; see `NATIVE-CI.md`.
+
+Removing the worker's parent-disconnect handler made the named SIGKILL regression
+fail because native descendants remained alive. Restoring the handler restored
+the native suite. This experiment checks cleanup behavior, not just stored status.

package/docs/VITEST.md

@@ -0,0 +1,36 @@
+# Vitest validation
+
+Select `javascript.vitest` explicitly in the root policy. The adapter resolves an
+installed Vitest within the configured root, including hoisted installations.
+Planning reads paths only. Execution requires operator trust because configuration,
+test code, plugins and setup/teardown hooks can run arbitrary code.
+
+Scope is the project's inventoried `.test` and `.spec` files with JavaScript or
+TypeScript extensions, including module/CommonJS and JSX/TSX variants. Each planned
+file must appear exactly once in the native report. Configuration exclusions and
+filters that omit a file produce incomplete evidence. A file executed repeatedly
+through multiple Vitest projects is currently ambiguous and also incomplete.
+
+The child invokes the public Vitest API in run mode with a JSON reporter explicitly
+directed to stdout. It overrides configured report output files, watch mode,
+snapshot updating, focused-test allowance, result caches and unhandled-error
+bypasses. Automatic installation through Vitest's package installer is disabled;
+missing dependencies must be prepared by the operator. User code can still write
+files or access networks. This is not an execution sandbox.
+
+Evidence reconciles native totals with per-assertion statuses and checks file
+identity and suite counters. Empty, all-skipped, unfinished, malformed and
+truncated reports cannot pass. Successful assertions cannot hide a failing suite,
+unhandled error or nonzero process exit. Test logs that corrupt the JSON output
+produce incomplete evidence rather than being guessed around. Detailed reports
+retain native diagnostics; summaries omit them.
+
+The integration suite exercises Vitest 5.0.1 with Vite 8.3.0, using original
+synthetic tests. It covers passing/failing assertions, skips/todos, excluded files,
+focused tests, snapshot protection, unhandled rejections and missing environment
+packages. Other versions, browser mode, custom pools and workspace multi-project
+duplication need separate verification. This check does not establish coverage
+quality or type-checking support.
+
+References: [Vitest reporters](https://vitest.dev/guide/reporters),
+[Vitest API](https://vitest.dev/advanced/api/).

package/docs/VUE-ROUTER.md

@@ -0,0 +1,130 @@
+# Vue Router testing assembly profile
+
+`javascript.vue-router` creates a native memory router, awaits an explicitly
+selected registration function, captures its final route records and checks
+declared URL probes using native resolution. A pass means every native record
+participated in a probe and all expected matched chains agreed. It does not prove
+that the selected testing assembly matches the application's production assembly.
+Reuse application registration code instead of maintaining a second route table.
+
+The verified versions are Vue Router 5.3.1 and Vue 3.5.43, with Node 26.8.1 on
+macOS arm64 and Node 22.23.2 on Linux arm64. Other framework versions are unavailable
+until verified. Framework dependencies must already exist inside the operator
+root; the engine never installs them. Fixture dependencies are locked separately
+in `scripts/vue-router-tools/package-lock.json` and are not distributed as runtime
+dependencies of Checktrail.
+
+## Configuration
+
+Select `javascript.vue-router` in `checktrail.json`, or use the pinned
+`packs/vue-router.json` profile. Add `checktrail.vue-router.json` in that project:
+
+```json
+{
+  "schemaVersion": 1,
+  "module": "routes.mjs",
+  "attribute": "configure",
+  "assembly": "example.catalog",
+  "environment": "test",
+  "strict": false,
+  "sensitive": false,
+  "probes": [
+    {
+      "path": "/catalog",
+      "matched": [{ "path": "/catalog", "name": "catalog" }]
+    }
+  ]
+}
+```
+
+The inventoried Node-compatible module exports the named function:
+
+```js
+export async function configure(router) {
+  router.addRoute({
+    path: "/catalog",
+    name: "catalog",
+    component: { render: () => null },
+  });
+}
+```
+
+Use `name: null` for unnamed records. Each probe contains the complete ordered
+matched chain, including parents and default children. Aliases are separate native
+records and require participation too. A negative probe uses `matched: []`;
+at least one probe must expect a match. Removed or replaced declarations that
+are absent from the final router are not counted. Shadowed records that cannot
+participate in any selected probe prevent a complete result.
+
+Planning reads configuration without importing the module. Execution requires
+the normal operator trust setting. The collector protects `NODE_ENV=test` and
+clears `NODE_OPTIONS`; permitted environment inputs remain available to startup.
+Startup and imports execute trusted code with the process user's privileges.
+They can perform I/O or invoke other router methods themselves. This is not a
+sandbox. Node must be able to load the module and its dependencies; the collector
+does not build TypeScript/SFC files or install a loader.
+
+## Evidence and limits
+
+The runtime inventory preserves native record order and multiplicity. Each entry
+records path/name, alias identity, named view keys, canonical JSON metadata/static
+redirect data, per-record guard function names, child count and the configured
+global strict/sensitive options. Per-record matcher overrides are exercised by
+probes but are not separately serialized. Component bodies, guard bodies, closure
+captures, props, global navigation hooks and scroll behavior are not captured.
+Changing a function body without changing the projected fields can leave the
+inventory unchanged. Use runtime comparison to review changes in this projection.
+
+The collector calls `resolve`, not navigation: it does not follow redirects, run
+navigation guards, load lazy views, render components or initialize a browser.
+Static redirect targets are recorded without proving they exist. Dynamic redirects,
+symbol route names and unsupported metadata make capture incomplete. Metadata
+supports bounded finite JSON values in plain objects and dense arrays; functions,
+custom prototypes, symbol keys, computed properties, hidden object properties and
+extra array properties are unsupported. Metadata and redirects are limited to
+eight levels, 1,024 visited values, 64 members per object/array and 4,096 serialized
+characters. The whole run retains shared process time/output limits.
+
+Profiles have at most 256 unique probe paths, 32 records per expected chain and
+64 KiB of encoded configuration. Native capture permits 2,048 route records.
+Empty routers, uncovered records, unsupported projections and malformed accounting
+cannot pass. A known probe mismatch is a failed finding even if other evidence is
+incomplete; `findingsComplete` records that distinction. Native resolution only
+establishes behavior for the supplied URLs, not every path/parameter combination.
+
+Detailed reports include route metadata and configured probe paths. Summary
+CLI/MCP output omits them, and MCP arguments cannot enable detailed output.
+The profile does not infer authorization, server endpoints, Nuxt page generation,
+Nuxt plugins/middleware or application integration. Those need separate profiles
+and native evidence.
+
+## Reproduce native evidence
+
+From the checkout, prepare the development fixture tools explicitly:
+
+```sh
+mkdir -p .checktrail/vue-router-tools
+cp scripts/vue-router-tools/package.json scripts/vue-router-tools/package-lock.json .checktrail/vue-router-tools/
+npm ci --prefix .checktrail/vue-router-tools --ignore-scripts --no-audit --no-fund
+npm run build
+node --test dist/test/vue-router.test.js
+node scripts/verify-vue-router-container.mjs
+```
+
+The container helper requires its pinned Node image to be available. Validation
+uses disabled container networking and read-only source mounts. It runs native
+fixtures, installs a freshly packed package offline, and exercises the public
+`examples/vue-router` fixture through installed library, CLI and MCP entry points.
+An intentionally changed route name must fail before the fixture is restored.
+The source tests cover async registration, nested default children, aliases,
+removed records, metadata changes, unprobed and shadowed records, unsupported
+data, evidence tampering, version gates, trust, protected environment and output
+privacy. Hosted CI is configured separately and has not been run remotely.
+
+A manual mutation removed the requirement that every record participate in a
+probe. The native uncovered-record regression then failed specifically because
+the result changed from incomplete to passed. Restoring the guard restored the
+passing native suite; container and package verification ran afterward.
+
+Reference: [Vue Router API](https://router.vuejs.org/api/). Compatibility claims
+above come from the pinned installed runtime and native tests.

package/docs/VUE-TSC.md

@@ -0,0 +1,26 @@
+# Vue type checking
+
+Select `javascript.vue-tsc` explicitly. A project-local `tsconfig.json` and an
+installed `vue-tsc` with TypeScript are required. Installations may be hoisted
+within the configured root; escaping symlinks are rejected. Planning does not
+load compiler code or execute configuration. Execution requires operator trust.
+
+The adapter calls the installed Vue compiler with no emit, no incremental state,
+`noCheck` disabled and a compiler file list. Every inventoried `.vue`, `.ts`,
+`.tsx`, `.mts` and `.cts` file must appear in that list. A zero exit with excluded
+source is incomplete. Compilation errors fail the check. Vue compiler options
+are resolved through the installed language core, including inherited options;
+`skipTemplateCodegen` is rejected. Other strictness and suppression choices follow
+project configuration and are not a guarantee of complete semantic coverage.
+
+Verified native versions: vue-tsc 3.3.11, Vue 3.5.43 and TypeScript 6.0.3. Fixtures
+exercise script and template type errors, a valid SFC, excluded source, inherited
+template disabling, filenames with spaces, and no emitted or incremental output.
+Project references/composite builds, Nuxt-generated configuration, custom Vue
+language plugins, custom file extensions and alternate loaders require separate
+verification. A library check does not start Nuxt or generate its application
+types. Missing generated configuration remains a compiler failure.
+
+The installed compiler and project plugins run with the user's privileges.
+See the official [Vue TypeScript guide](https://vuejs.org/guide/typescript/overview.html)
+for the distinction between transpilation and SFC type checking.

package/docs/WORKSPACES.md

@@ -0,0 +1,81 @@
+# Workspace and Git selection
+
+Checks still cover whole configured projects. Optional `--base REVISION` selects
+changed projects and their declared transitive consumers:
+
+```json
+{
+  "schemaVersion": 1,
+  "projects": [
+    { "path": "library", "checks": ["javascript.node-test"] },
+    { "path": "web", "checks": ["javascript.node-test"] }
+  ],
+  "workspace": {
+    "complete": true,
+    "dependencies": [{ "consumer": "web", "producer": "library" }]
+  }
+}
+```
+
+`complete` asserts that the maintainer has listed every relevant dependency
+between configured projects. The engine does not infer imports or prove the
+graph complete. Edges must name configured projects; duplicate and self edges
+are rejected. Cycles terminate and include every reachable consumer.
+
+```sh
+node dist/src/cli.js plan --root /path/to/worktree --base main --detailed
+node dist/src/cli.js run --root /path/to/worktree --base main --trust-project
+```
+
+The library accepts `base` in plan/validation options. For MCP, configure
+`serve --base REVISION` at startup; tool calls cannot override it. Without a
+base, the complete configured plan runs regardless of workspace declarations.
+
+## Comparison and fallback
+
+The reader resolves base and HEAD to immutable commit IDs, reads committed trees
+and NUL-delimited index entries, and hashes inventoried working files directly.
+This covers committed changes, staged changes, dirty or deleted files, untracked
+inventoried files and executable modes. Renames include both old and new owners.
+The longest configured project directory owns a changed file.
+
+The full configured plan is retained for missing Git/history/base, an incomplete
+graph, no changed paths, a root or hidden configuration change, an unowned path,
+a root-project change, unsupported index entries, unresolved merges, submodules,
+tracked excluded content, inspection limits or inconsistent Git metadata. The
+configured root must be the worktree root. Fallback is a broader validation run,
+not a passing empty selection. It does not add unconfigured checks.
+
+Git inspection uses a host executable outside the project and bounded read-only
+commands. It disables filesystem monitors, hooks, lazy fetch and replacement
+objects, and does not invoke working-tree diff, clean or text conversion filters.
+Raw content comparison can select additional files when Git attributes transform
+content; it cannot establish a normalized checkout identity. `.gitignore` is not
+interpreted. The inventory's fixed exclusions still apply.
+
+Each Git inspection has a five-second/four-MiB process-output budget, separate
+from native validation execution. Entries and working-file reads use the same
+20,000-entry, eight-MiB-file and 64-MiB-total limits as inventory. Post-run Git
+identity checks run in addition to the source snapshot. Changed HEAD/index or
+unreadable metadata prevents an aggregate pass, even if source bytes stayed equal.
+
+Detailed plans/reports record changed paths, selected projects, resolved commits,
+Git version, an index fingerprint and a digest identifying the canonical worktree
+root. Linked worktrees have distinct identities. Summaries retain selection mode,
+reason and counts only. Neither identity is a hermetic build or dependency hash.
+
+## Evidence
+
+Native synthetic tests exercise committed/index/working changes, newline paths,
+renames, modes, linked worktrees, unresolved merges, tracked exclusions and
+project-configured filter commands that must never run. A changed library selects
+its consumer and exposes a real assertion failure. CLI/MCP scope and strict MCP
+startup ownership are covered. Current host evidence is macOS with Git 2.54.0;
+the paired [impact measurement](IMPACT-MEASUREMENT.md) additionally exercises
+its documented corpus on Linux arm64 with Git 2.52.0. That narrower corpus does
+not establish the full Git edge-case matrix on Linux. Other Git/OS combinations
+need their own integration runs.
+
+References: [tree entries](https://git-scm.com/docs/git-ls-tree),
+[index entries](https://git-scm.com/docs/git-ls-files),
+[revision resolution](https://git-scm.com/docs/git-rev-parse).

package/docs/licenses/nodable-entities-3.0.0.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nodable
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.