@stsepelin/checktrail 0.1.0-alpha.1

package/dist/src/workspace.js

@@ -0,0 +1,53 @@
+import path from "node:path";
+export function validateWorkspace(workspace, projects) {
+    const nodes = new Set(projects);
+    const seen = new Set();
+    for (const edge of workspace.dependencies) {
+        if (!nodes.has(edge.consumer) || !nodes.has(edge.producer))
+            throw new Error("Workspace dependency names an unconfigured project");
+        if (edge.consumer === edge.producer)
+            throw new Error("Workspace dependency cannot reference itself");
+        const key = JSON.stringify([edge.consumer, edge.producer]);
+        if (seen.has(key))
+            throw new Error("Duplicate workspace dependency");
+        seen.add(key);
+    }
+}
+export function affectedProjects(projects, files, workspace) {
+    const all = [...new Set(projects)].sort();
+    const fallback = (reason) => ({
+        projects: all,
+        reason,
+        affected: false,
+    });
+    if (!workspace?.complete)
+        return fallback("Workspace dependency completeness is not declared.");
+    if (!files.length)
+        return fallback("No changed paths were found; retaining full validation.");
+    const selected = new Set();
+    for (const file of files) {
+        if (path.posix.dirname(file) === "." ||
+            file.split("/").some((part) => part.startsWith(".")))
+            return fallback("Root or hidden configuration changed; impact is global.");
+        const owner = all
+            .filter((project) => project === "." || file.startsWith(`${project}/`))
+            .sort((a, b) => (b === "." ? 0 : b.length) - (a === "." ? 0 : a.length))[0];
+        if (!owner)
+            return fallback("A changed path has no configured project owner.");
+        if (owner === ".")
+            return fallback("A root-project change may affect nested projects.");
+        selected.add(owner);
+    }
+    let previous = -1;
+    while (previous !== selected.size) {
+        previous = selected.size;
+        for (const edge of workspace.dependencies)
+            if (selected.has(edge.producer))
+                selected.add(edge.consumer);
+    }
+    return {
+        projects: [...selected].sort(),
+        reason: "Changed projects and their declared transitive consumers were selected.",
+        affected: true,
+    };
+}

package/docs/ACCEPTANCE.md

@@ -0,0 +1,56 @@
+# Milestone acceptance audit
+
+This audit maps the original plan to implemented profiles and their recorded
+verification. It does not replace the plan or promote an unverified capability.
+Local implementation, local native evidence, hosted CI and publication are
+separate states. Follow the linked evidence for tested versions and limits.
+
+| Milestone                         | Implemented scope and evidence                                                                                                                                                                                                                                                                                                                                                                                                          | Open acceptance work                                                                                                                                                                                                                                                |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| M0: public contracts              | Original public fixtures, MIT license, security/contribution guidance, schemas, explicit package allowlist, dependency notices and CI definitions. `STATUS.md`, `SECURITY.md`, `RELEASE.md`.                                                                                                                                                                                                                                            | Public source is published and all hosted jobs passed at `52ba415`. The preview candidate still requires its own release commit, CI and publication verification.                                                                                                   |
+| M1: executable foundation         | Shared CLI/library/MCP engine, bounded inventory/runner, startup trust, native Node/Python/Go/PHP profiles, protocol and lifecycle regressions. `ARCHITECTURE.md`, `STATUS.md`, `MCP-COMPATIBILITY.md`. Fresh installed application-client profiles now have evidence in `CLIENTS.md`.                                                                                                                                                  | Application-client coverage beyond the named profiles. PHP remains unavailable when the consumer has no prepared runtime.                                                                                                                                           |
+| M2: practical language validation | Explicit JS/TS, Python, Go and PHP native tool profiles, structured diagnostics/test evidence, versions, environments, workspace selection, scope accounting, SARIF/JUnit and finding ratchets. `LANGUAGES.md`, adapter documents, `WORKSPACES.md`, `FINDING-POLICY.md`, `NATIVE-CI.md`.                                                                                                                                                | Hosted toolchain profiles passed at `52ba415`. Wider tool versions/framework configurations must be promoted separately; detection is not execution support.                                                                                                        |
+| M3: framework/contracts           | Native Laravel, Vue Router/Nuxt, Django/FastAPI assembly projections; imported runtime comparison, explicit architecture boundaries, producer/consumer schemas and a built package consumer. `RUNTIME-INVENTORY.md`, framework documents, `CONTRACTS.md`, `ARCHITECTURE-POLICY.md`, `examples/package-contract/README.md`.                                                                                                              | Broader native semantics/import collection and live service integration are not implemented. Synthetic evidence does not establish equivalent results in a private application; private integration feedback must remain private.                                   |
+| M4: ecosystem/distribution        | Bounded Rust, Java, C#, Ruby, Swift, Clang and actionlint profiles; trusted external adapters, pinned data-only pack distribution, fresh offline package checks, production notice audit, measured performance and unpublished registry metadata. `LANGUAGES.md`, `EXTERNAL-ADAPTERS.md`, `PACK-DISTRIBUTION.md`, `PERFORMANCE.md`, `RELEASE.md`.                                                                                       | Concrete preview release authorization and verification. Windows execution and the unimplemented subsequent integrations in `LANGUAGES.md` remain unsupported. Runtime/container/development dependency provenance is broader than the production npm notice audit. |
+| M5: measured assistance           | Advisory guidance, bounded Node mutation experiments, explicit-graph impact measurements, optional local/model review exchange, durable library task storage/worker, development evaluation and externally authored ESLint and Ruff integration cohorts. `GUIDANCE.md`, `MUTATIONS.md`, `IMPACT-MEASUREMENT.md`, `REVIEW-EXCHANGE.md`, `VALIDATION-TASKS.md`, `EVALUATION.md`, `EXTERNAL-EVALUATION.md`, `EXTERNAL-RUFF-EVALUATION.md`. | Standard MCP Tasks wire integration; wider held-out rule-family/review evidence, prior-workflow comparison and representative cost/latency measurement. No general equal-or-better review-quality claim is supported.                                               |
+
+## Remaining work that can proceed locally
+
+1. Extend independently authored evaluation cohorts to additional implemented
+   language/rule families, preserving the verifier freeze and recording exact
+   selection, exclusions, native baselines and interpretation limits. New fixtures
+   authored after inspecting the implementation remain development tests.
+2. Run the comparison prepared in `PRIOR-WORKFLOW-EVALUATION.md` after resolving
+   the actual baseline, independently labeled public cases and reviewer/adjudicator. A native-tool comparison alone is not this baseline.
+   Model-assisted comparisons need declared model/version and actual inference
+   cost; review exchange by itself supplies neither effectiveness nor cost evidence.
+3. Continue the requirement-specific validation of any newly promoted profile.
+   Optional breadth is not a reason to mark already measured profiles unsupported,
+   and a measured profile is not permission to claim its whole ecosystem.
+
+The recorded client schema warning is corrected and the current Claude Code
+check requires no startup/schema warnings. Published schemas compile under strict
+standard validation; URL/path boundary cases and actual Codex guidance retrieval
+are verified in `CLIENTS.md`. The original frozen ESLint runtime and harness were
+archived before that correction and replayed against the original observations
+on both platforms; see `EXTERNAL-EVALUATION.md`. Later engine revisions must not
+be silently substituted into that frozen holdout.
+
+## External gates
+
+The pinned MCP server SDK routing probe still rejects `tasks/get` and `tasks/cancel` before their extension handlers
+run. The local worker/store are available independently; standard Tasks must stay
+unadvertised until routing and the integrated wire/lifecycle suite pass. See
+`MCP-COMPATIBILITY.md` for the reproduction and upstream issue.
+
+The public repository and initial commit `60131d6` are available on `main`.
+All 13 hosted jobs passed at `52ba415`, recorded in `NATIVE-CI.md`.
+That result identifies the source baseline, not an unpublished preview package. Package publishing, GitHub releases and registry
+registration have not been performed. The repository's explicit-action
+requirements still apply. `RELEASE.md` defines the concrete
+candidate checks and the authorization sequence; a local green run does not
+replace external acceptance.
+
+This audit uses the existing execution ledger and recorded native observations.
+It is not a fresh security review of every source file, an independent review of
+the evaluation labels, or proof that the entire M0–M5 plan is complete.

package/docs/ACTIONLINT.md

@@ -0,0 +1,112 @@
+# GitHub Actions workflow validation
+
+`infrastructure.actionlint` statically checks inventoried
+`.github/workflows/*.yml` and `*.yaml` files using the official actionlint 1.7.12
+release executable. Planning reads files only. Execution requires operator trust
+and an already prepared tool on `PATH`; the engine never downloads one.
+
+Each workflow directory identifies its repository root, including nested roots.
+Workflow dependencies use the full inventory below that root even when a local
+action also contains a separate package manifest. Default planning retains an
+unsupported result for Terraform, Helm and Kustomize markers beside workflows.
+Selecting this check explicitly covers workflows only.
+
+## Configuration
+
+Place `checktrail.actionlint.json` at the repository root:
+
+```json
+{
+  "schemaVersion": 1,
+  "runnerLabels": [],
+  "variables": []
+}
+```
+
+`runnerLabels` lists additional self-hosted runner labels. Only literal ASCII
+letters, digits, underscores and hyphens are accepted; glob patterns are rejected.
+`variables` lists configuration-variable identifiers available to `vars` expressions.
+An empty list declares none. Case-insensitive duplicates and unknown keys are
+rejected. These declarations describe the expected environment; they do not query
+GitHub or prove that a runner or variable exists. The generated schema is
+`schemas/actionlint-config.schema.json`; runtime validation also checks duplicates.
+
+To select the profile explicitly, use `infrastructure.actionlint` in the
+repository policy. `packs/actionlint.json` is the corresponding data-only public
+pack. Neither the profile nor a pack grants execution permission.
+
+## Execution and evidence
+
+The wrapper makes a fresh bounded copy of inventoried project files. It omits
+Git metadata and repository actionlint configuration, including case variants,
+creates its own empty Git marker, and supplies its own explicit native config.
+Consequently repository `paths.*.ignore` settings cannot suppress findings.
+This intentionally differs from running actionlint with repository defaults.
+
+Before running actionlint, the wrapper checks local `uses` references in workflows
+and local action metadata. A local action needs exactly one inventoried
+`action.yml` or `action.yaml`; referenced runtime files and local reusable
+workflows must also be inventoried. Missing, excluded, symbolic-link or escaping
+inputs cannot pass. Main/pre/post scripts, Dockerfiles and entrypoint files are
+copied as data. They are never executed by this profile. Composite metadata
+dependencies are inspected, but this does not establish semantic validation of
+every composite step.
+
+YAML parser errors produce `yaml/*` findings and incomplete analysis. YAML aliases,
+merge keys, unsupported tags/warnings and dependency-inspection failures produce
+incomplete results. These are explicit profile limits, not claims that GitHub
+rejects those constructs.
+
+The wrapper invokes one actionlint process per workflow with JSON diagnostics,
+verbose tracing, ShellCheck disabled and Pyflakes disabled. The parser reconciles
+the planned files, native project selection, parse/total counts, disabled optional
+integrations and exit status. Missing, duplicate, unexpected or contradictory
+evidence cannot pass. Errors retain their `actionlint/*` identifiers and source
+locations; failed analysis does not establish complete findings. Successful
+analysis provides no test-execution evidence.
+
+Source fingerprints are checked before copying and after validation, alongside
+the shared engine's source checks. Limits include 128 workflows, 512 YAML files in
+the local dependency closure, the shared inventory's 8 MiB/file and 64 MiB total,
+100 KiB invocation arguments, 2,000 parsed diagnostics per native result and the
+shared time/output limits. A source change or exceeded limit prevents success.
+Native tool identity is version evidence, not an attestation of every executable
+byte; the preparation recipe separately verifies the release archive digest.
+
+## What this does not validate
+
+No jobs, shell/Python bodies, actions, JavaScript payloads, containers, remote
+checkouts or services are executed. Remote actions are not downloaded; analysis
+uses actionlint's static knowledge. There is no claim of complete GitHub runtime
+compatibility, action supply-chain auditing, least-privilege authorization,
+secret safety, deployment safety or successful CI execution. This is not an OS
+sandbox. Terraform, Helm, Kustomize and arbitrary YAML need separate profiles.
+
+## Reproduction
+
+With the pinned official release prepared on `PATH`:
+
+```sh
+npm run build
+node --test dist/test/actionlint.test.js
+node dist/src/cli.js run --root examples/actionlint --trust-project --detailed
+```
+
+The Linux fixture image downloads and verifies a fixed release during its explicit
+preparation step. Validation and packaged library/CLI/MCP smoke tests then run
+with networking disabled and read-only source/consumer mounts:
+
+```sh
+docker build --file scripts/actionlint-tools.Dockerfile --tag checktrail-actionlint-test:1.7.12 scripts
+node scripts/verify-actionlint-container.mjs
+```
+
+The native tests cover broken/fixed expressions, YAML failures, literal runner and
+variable settings, reusable workflow inputs, local metadata and runtime assets,
+repository suppression bypass, missing dependencies, and evidence tampering.
+The CI job is configured separately; a local container run is not hosted CI.
+
+Upstream references: [release and assets](https://github.com/rhysd/actionlint/releases/tag/v1.7.12),
+[CLI usage](https://github.com/rhysd/actionlint/blob/v1.7.12/docs/usage.md),
+[configuration](https://github.com/rhysd/actionlint/blob/v1.7.12/docs/config.md),
+[checks](https://github.com/rhysd/actionlint/blob/v1.7.12/docs/checks.md).

package/docs/ARCHITECTURE-POLICY.md

@@ -0,0 +1,82 @@
+# Explicit architecture boundaries
+
+`check-architecture` evaluates a captured project dependency graph against a
+closed project/layer policy. It is language-agnostic: native tooling can supply
+graphs from different languages using the same artifact contract. This feature
+does not itself scan imports, run a build system, or attest graph completeness.
+
+```sh
+checktrail check-architecture --root /path/to/workspace \
+  --input dependency-graph.json --policy architecture.json
+```
+
+The library exports `checkArchitecture(graph, policy)`. MCP exposes the read-only
+`architecture_validation` tool with relative `input` and `policy` paths. Operator
+root and output settings remain fixed at server startup. These artifact checks
+need no project execution permission. Their outcome is separate from any native
+validation report.
+
+## Policy
+
+Every project has an exact ID and exactly one declared layer. An allowed
+dependency names a **consumer layer** and a **producer layer**. Edges not in that
+allowlist are forbidden, including edges within the same layer unless explicitly
+allowed. IDs are case-sensitive literal strings: prefixes, suffixes, `*` and
+regular-expression characters have no matching semantics. Duplicate IDs, duplicate
+edges and undeclared layers are errors.
+
+```json
+{
+  "schemaVersion": 1,
+  "format": "architecture-policy",
+  "layers": ["domain", "application"],
+  "projects": [
+    { "id": "catalog-model", "layer": "domain" },
+    { "id": "catalog-api", "layer": "application" }
+  ],
+  "allowedDependencies": [{ "consumer": "application", "producer": "domain" }],
+  "requireAcyclic": true
+}
+```
+
+With `requireAcyclic`, observed cycles fail even when every individual edge is
+allowed. The report lists strongly connected components, including self-loops;
+member order is for deterministic presentation, not a traversal path. Converging
+paths and diamonds do not count as cycles. Detection uses bounded iterative graph
+traversal rather than recursive calls.
+
+## Evidence
+
+The graph records its collector/version, capture timestamp, a global completeness
+flag, project IDs, language labels, recorded source fingerprints, per-project
+completeness, and exact consumer/producer edges. An edge referencing an absent
+graph node is invalid. A project missing from either graph or policy makes coverage
+incomplete. Known forbidden edges or cycles still fail when other evidence is
+incomplete; the report does not discard a known violation.
+
+Results carry `imported-dependency-graph` provenance and separate artifact/policy
+fingerprints. The recorded graph can describe imports, build references or package
+manifest dependencies; the collector must document which. A complete manifest
+graph does not establish complete source import coverage. Recorded fingerprints
+and completeness flags are declarations by that collector, not independent proof
+of origin, current source state or absence of undeclared dependencies.
+
+Project statuses mean `verified` (configured layer and declared complete capture),
+`missing`, `unconfigured` or `incomplete`. Edge statuses are `allowed`, `forbidden`
+or `unverified`. Their categories sum to the corresponding project/edge totals.
+`captureComplete` preserves the graph-wide declaration separately. A one-project
+graph with no dependencies can pass if complete and fully configured. It does not
+claim that any tests ran.
+
+Inputs are bounded to 8 MiB each, 1,000 projects, 20,000 observed dependencies,
+128 layers and 16,384 allowed layer pairs. JSON schemas reject unknown fields.
+Summaries omit project IDs, edges, layer names and cycle members; detailed output
+is operator-selected. Exit codes are 0 passed, 1 policy violations, and 2 incomplete
+or invalid evidence. No network, model or external project code is invoked.
+
+The public `examples/package-contract/architecture.json` applies the same boundary
+policy to a built producer and installed consumer. Its native integration test
+derives the workspace package edge from the consumer's installed dependency
+declaration, validates the packaged artifact through type and runtime checks, and
+tests a synthetic reverse-edge violation separately. It is not a general native
+import-graph collector. Additional language-specific graph collectors remain work.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,122 @@
+# Architecture
+
+```mermaid
+flowchart TD
+  CLI[CLI / CI] --> Engine
+  MCP[MCP stdio server] --> Engine
+  Policy[Validated declarative policy] --> Engine
+  Engine --> Inventory[Bounded file inventory]
+  Engine --> Adapters[Registered language/tool adapters]
+  Adapters --> Runner[Trusted process runner]
+  Runner --> Evidence[Evidence parsers]
+  Evidence --> Report[Versioned report]
+  Report --> Output[Operator-selected output projection]
+```
+
+The engine owns discovery, planning, execution accounting and report construction.
+Adapters describe checks and parse results; they do not write protocol messages.
+CLI and MCP call the same functions. stdout belongs exclusively to JSON or MCP;
+diagnostics go to stderr. The engine does not call an LLM.
+
+## Discovery and scope
+
+The root is configured by the operator, canonicalized once, and never supplied by
+an MCP tool call. Inventory is deterministic, bounded, excludes dependency/build
+directories and sensitive local files, and does not follow symlinks. Read errors
+are errors, not silently empty inventories. Scope exclusions accompany results.
+
+Checks validate whole discovered project units. Optional operator-selected Git
+base comparison narrows projects through an explicitly declared complete dependency
+graph, with full-plan fallback whenever impact is uncertain. See `WORKSPACES.md`.
+Persistent caching is not implemented. An inventory fingerprint
+identifies included file contents; it is not a claim about ignored dependencies,
+outside files, runtime services or hermetic reproducibility.
+
+## Configuration
+
+`checktrail.json` is optional and uses `schemaVersion: 1`. It can select known
+checks for detected project roots. Unknown keys, IDs and project roots fail before
+any process starts. A missing config uses conservative registered defaults. Pinned JSON packs add
+registered checks, and an operator-selected private overlay adds requirements to
+an explicit base policy. See `POLICY-PACKS.md`.
+Local operator trust and output settings cannot be enabled by this file. Projects
+can require named environment variables, but values are supplied only through
+operator CLI/library/MCP startup permissions. Values are not recorded in commands;
+detailed reports retain names and a fingerprint. See `ENVIRONMENTS.md`.
+
+## Execution and results
+
+Commands are executable/argument arrays with no shell interpolation. A required
+check gets one terminal result. Aggregate status is failed if any check fails,
+incomplete if any required check lacks a conclusive result, otherwise passed.
+An empty plan is incomplete. The report retains both failures and incomplete work.
+
+Test results need evidence of at least one executed non-skipped test. Missing or
+unparseable evidence is inconclusive even if the process exits zero. Successful
+format checks need no diagnostics. A process failure cannot be converted into a
+pass by a parser. Source changes during execution invalidate a green result.
+
+Use bounded process output and timeouts, terminate the process group on supported
+POSIX hosts, and propagate cancellation. No automatic dependency installation,
+source rewriting, infrastructure startup, deployment or repository mutation.
+Executed project code still has the process user's privileges; this is not a
+sandbox. Tests may modify files or access networks and must be trusted accordingly.
+
+## MCP boundary
+
+Expose `project_context`, `validation_plan`, `validation_run`, `validation_report`,
+`finding_comparison`, `runtime_comparison`, `contract_validation`,
+`architecture_validation`, `review_guidance`, `review_context`, `review_receipt`,
+and `mutation_experiment`.
+Tool schemas are validated. Execution is disabled unless enabled when starting
+the server. Keep a bounded in-memory report store; report IDs are opaque and a
+restart clears them. The optional library-only [task store](TASK-STORAGE.md)
+retains projected reports in bounded, exclusively owned SQLite databases. It is
+not connected to these tools. The separate [library worker](VALIDATION-TASKS.md)
+owns the store while executing through the shared engine and cancels on parent
+disconnection. MCP Tasks integration remains pending.
+Request cancellation is matched by exact ID, including numeric zero. Connection
+closure and process signals terminate active validation workers. The
+[compatibility record](MCP-COMPATIBILITY.md) describes the SDK constraints and
+standard Tasks acceptance gates.
+
+Default summary output contains aggregate counts, adapter/check IDs and statuses;
+it omits source excerpts, paths, commands and raw logs. Detailed output requires a
+startup flag and is intended for trusted clients. Both can reveal project activity;
+neither is a guarantee against the MCP client's own data handling.
+
+## Extension boundaries
+
+Public rule packs, private overlays and tool adapters share stable schemas.
+Built-in checks and operator-registered external checks execute through the shared
+runner. Local data-only packs use pinned content integrity and bounded reads; public
+profiles are included in the package. External executable bundles require a manifest
+digest and per-file digests; verified bytes are copied into an owned temporary
+directory. Their JSON protocol accounts for every planned file and labels delegated
+tool identities as adapter-reported. See `EXTERNAL-ADAPTERS.md`. An explicit CLI/library HTTPS fetch operation installs
+pinned data-only packs without activating them; planning, validation and MCP remain
+offline with respect to pack loading. See `PACK-DISTRIBUTION.md`. Remote executable
+bundle distribution, sandboxing and dependency resolution remain separate work. Advisory guidance is never serialized as a passed
+automated check.
+
+Native framework capture is opt-in and uses version-gated collectors. The Vue Router
+profile constructs a selected testing router, awaits registration and verifies native
+URL resolution with complete route-record participation. Its assembly projection
+and limits are documented in `VUE-ROUTER.md`. The separate Nuxt profile builds
+a fresh SSR testing assembly and captures its native router after in-process
+requests complete, without a listening socket; see `NUXT.md`.
+
+## Advisory assistance
+
+Guidance selects built-in public questions by exact check/topic triggers without
+executing code. Mutation experiments use the shared validator in bounded fresh
+copies, preserving baseline and changed-test evidence. Both have separate advisory
+schemas and cannot rewrite deterministic outcomes. The initial mutation profile
+is limited to dependency-free Node projects with flat tests; see `GUIDANCE.md` and
+`MUTATIONS.md`. No model call or source upload is required.
+
+Optional review exchange captures explicitly selected source and receives external
+assessments without invoking a model. Source and review prose require a separate
+operator disclosure setting. Context identity, freshness, quotations and declared
+file accounting are checked, while defect claims remain unverified and separate
+from validation. See `REVIEW-EXCHANGE.md`.

package/docs/CLANG.md

@@ -0,0 +1,113 @@
+# C and C++ compilation checks
+
+`cpp.clang-check` runs Clang's front end using a prepared project-root
+`compile_commands.json`. Detection recognizes that file, `CMakeLists.txt` and
+`meson.build`. Discovery and planning never execute a build system. Missing or
+unsupported configuration is unavailable rather than a successful compilation.
+
+```sh
+node dist/src/cli.js run --root examples/cpp --trust-project --detailed
+```
+
+The public example contains separate C17 and C++20 translation units and shared
+headers. Its portable database is authored explicitly. A consumer can prepare a
+database using its own build system, then place it in the inventoried project
+root. A database left only under excluded `build/` is not used automatically.
+
+## Supported database profile
+
+The [Clang compilation database specification](https://clang.llvm.org/docs/JSONCompilationDatabase.html)
+defines argument arrays separately from shell command strings. This profile
+requires `arguments`; it never tokenizes or executes `command`. When both fields
+exist, the argument array is used. Directory and input paths must resolve within
+the operator root, and each entry must name exactly one inventoried C/C++ source.
+Relative directories are interpreted from the project root; other relative paths
+are interpreted from the entry's directory.
+
+The compiler must be `clang` or `clang++`, or an absolute path resolving to the
+same executable selected by PATH. Wrappers, response files and arbitrary compiler
+paths are unsupported. The selected PATH is protected for execution. Multiple
+distinct configurations of a source file are checked; duplicate normalized entries
+are rejected.
+
+The closed flag set supports:
+
+- C and C++ language-standard flags explicitly enumerated in `src/clang.ts`.
+- Object-like `-D` definitions and `-U` undefinitions, preserving literal values.
+- Root-contained `-I`, `-iquote` and `-isystem` directories.
+- `-O0` through `-O3`, `-Os`, `-Og`, `-Oz`, PIC/PIE, pthread,
+  no-exceptions and no-rtti settings.
+- `-Wall`, `-Wextra`, `-Werror`, `-Wpedantic`, `-Wconversion`,
+  `-Wsign-conversion`, `-Wshadow`, `-Wunused`, `-Wunused-parameter` and
+  `-Wno-unused-parameter`.
+
+Compile/output/dependency arguments (`-c`, separate `-o`, `-MF`, `-MT`, `-MQ`,
+`-MD`, `-MMD`, `-MP`) are replaced with engine-owned front-end/dependency output.
+`-g` and `-g0` are omitted. Source and include path spellings are preserved because
+rewriting relative paths can change `__FILE__`. All other flags are unavailable;
+the adapter does not silently drop unknown target, language, plugin or ABI options.
+Cross-compilation, modules, precompiled headers and compiler plugins need separate
+profiles. Default Clang configuration loading and implicit modules are disabled.
+Compiler override/include environment variables are protected; they cannot be
+injected through project environment requirements.
+
+## Evidence and limits
+
+The engine requires native SARIF diagnostics for each database entry and a fresh
+compiler dependency file. It reconciles entry identity, process status, diagnostic
+severity and compiler version. Native compiler errors fail the check; malformed
+or partial evidence cannot pass. Warnings are retained and follow the configured
+native warning policy, including `-Werror`; this is not an all-warnings lint policy.
+Source-level pragmas and the selected preprocessor definitions remain part of
+native compiler semantics.
+
+Every inventoried C/C++ translation unit and header must appear in at least one
+observed dependency list. Uncompiled sources, unused headers, generated project
+headers under excluded directories, and symlinked project inputs make the result
+incomplete. Nested projects retain separate inventory boundaries. The recognized
+extensions are listed in `src/clang.ts`; Objective-C, CUDA and assembly are not
+covered. C++ module extensions `.ixx` and `.cppm` are explicitly unavailable.
+
+System/toolchain headers outside the root are counted separately in the detailed
+process evidence. They are not included in the source fingerprint; host SDKs,
+standard libraries and compiler binaries are not hermetic inputs. The evidence
+does not cover inactive preprocessor branches, every target configuration, linking,
+code generation, ABI compatibility, static-analysis rules or executed tests.
+No object files or configured build outputs are written by this profile. Native
+tools run with operator trust and are not sandboxed.
+
+The database is bounded to 64 entries and 256 arguments per entry; the prepared
+invocation must fit 100 KiB. Each native process has bounded captured output and
+the wrapper limits aggregate native output to 4 MiB. Dependency files are capped
+at 8 MiB each and 16 MiB total. The shared engine also enforces its total timeout,
+output, source-freshness and cancellation limits. Dependency outputs use a fresh
+temporary directory, removed on normal completion/error. Forced process or machine
+termination can leave that directory. Newline, backslash, dollar, hash and colon
+in source paths are unsupported; native literal-space dependencies are tested.
+
+## Verified toolchains
+
+- Apple Clang 21.0.0, build `clang-2100.3.34.2`, arm64 macOS.
+- Alpine Clang 22.1.3, arm64 Linux, with Node 22.23.2 in a prepared container.
+
+Other versions are unavailable until their native evidence has been verified.
+Apple's SARIF includes an invocation result and a full version banner; the tested
+Alpine build omits the invocation record and uses a numeric version. The parser
+checks each verified form rather than assuming the outputs are identical.
+
+Prepare the development fixture explicitly, then run it without networking:
+
+```sh
+docker build --file scripts/clang-tools.Dockerfile --tag checktrail-clang-test:22.1.3 scripts
+node scripts/verify-clang-container.mjs
+```
+
+The base image digest and Clang/LLVM package versions are pinned. Auxiliary Alpine
+toolchain dependencies are resolved during preparation, so this is not a completely
+locked container supply chain. Verification records the resulting image digest,
+mounts the repository read-only and creates synthetic fixtures inside the container.
+
+Tests cover the actual public example, native C/C++ errors and repair, header
+coverage, ignored build configuration, relative `__FILE__` spelling, working
+directories, space-containing includes, standard-library headers, multiple
+configurations, warnings, missing compilers and malformed evidence.