Core documentation

MVP Acceptance

The MVP is complete only when every item below has an executable test or repeatable measurement.

§Repository And Delivery

• Public the-open-engine/opcore repository with the previous implementation retained on legacy and its existing release tags. Opcore 0.3 imports the Zero source snapshot; the new npm entry point is @the-open-engine-company/opcore.
• Every pull request and release tag builds the source-generated documentation and checks its local links. Passing main builds publish the checked artifact to https://the-open-engine.github.io/opcore/; the docs include the guides, CLI, public API, provider references, and pinned ASP definition.
• Rust owns evaluators, workflows, and protocol semantics. The dependency-free npm facade verifies installation and launches the binary; shell and documentation scripts handle packaging and development support.
• Release build produces opcore, a binary checksum, and distinct fast, Rust-native, Node-native, and Python-native manifests bound to the exact executable. Each published archive carries install.sh, the binary/checksum, root README and its local visual assets, global skill and Codex descriptor, complete pinned asp/ definition, and its referenced root LICENSE, while leaving path-bound manifest regeneration and skill command binding to installation.
• Installer tests cover archive extraction without Cargo, default hook enrollment, explicit --no-hooks installation, paths with spaces, exact command resolution from the installed skill without inherited PATH, same-path updates, destination and symlink collision refusal, legacy receipt migration, interrupted hook recovery, and byte-owned uninstall. Hook tests require confirmed Sense findings to block, partial Sense coverage to continue with one hint, and unsupported Verify coverage to continue with one path-free warning. Linux and macOS CI run both the installer suite and the extracted-archive user journey.
• The npm facade has no runtime dependencies and advertises only Linux x64 plus macOS arm64. Node tests cover strict semver and target selection, exact release URLs, download bounds, malformed/duplicate/missing checksums, archive mismatch, gzip expansion limits, ustar header checksums, traversal, links, duplicate and unknown members, missing required bundle files and visuals, inner binary mismatch, deterministic agent selection, installer failure, canonical state, launcher argument/status forwarding, tampered executable refusal, digest-bound cleanup, and npm pack contents. Each native CI runner also feeds its produced bundle through the npm extractor.
• A stable vX.Y.Z tag must equal the Cargo and staged npm versions. Publication waits for every existing Rust gate plus the Node 18/24 npm jobs, accepts exactly two archives, writes one exact SHA256SUMS, embeds the same two digests in the npm tarball, refuses an existing GitHub Release, publishes the release assets, exercises install and two-step removal from the packed npm artifact, and then publishes that exact artifact with provenance. The job fails before publication when repository visibility is not public. Initial release also requires administrator confirmation that immutable releases and tag protection are enabled, the npm package has been reserved, and the ci.yml/release trusted publisher permits direct publication; no such external state is inferred from repository files.

§Functional

• Local check supports committed tree, staged, changed, explicit paths, and whole-workspace source views; ASP supplies hypothetical content-addressed overlays. Unsupported Fast source remains an explicit non-blocking coverage warning, while a selection with no source candidates is not_checked and incomplete evaluation still blocks.
• One .opcore.json resolves typed shared and workflow settings for every evaluator. Tests cover stricter overrides, array replacement, exact excluded subpaths, complete-file validation, schema/runtime agreement, staged and immutable configuration views, documentation bindings, and freshness after configuration-only changes.
• Built-in post-edit, pre-commit, and CI workflows compose existing evaluators; full staged/committed Verify and required native checks coexist with introduced Sense. Missing native prerequisites fail, post-edit never invokes native tools, and changed source or configuration invalidates the complete workflow attempt.
• npm skipped lifecycle scripts leave usable help, package-version output, and setup diagnostics without unverified native execution. Explicit setup and CLI-only installation cover absent agent directories, paths with spaces, interrupted downloads, repeated setup, tampered state/binaries, and verified cleanup.
• ASP stdio supports lifecycle, callbacks, cancellation, shutdown, and check/evaluate.
• Optional check/evaluate.configuration carries resolved provider settings; direct and ASP Fast agree on thresholds, omission uses defaults, strict validation rejects invalid settings, and assessment configDigest binds the effective provider configuration.
• The in-package ASP definition snapshot has pinned provenance and byte-level integrity coverage.
• The private local harness runs each bundled profile as a separate process, serves only immutable callback content, validates provider identity/freshness/read evidence, rejects host-owned assessment fields, and owns its local three-way decision. It does not claim ASP Core outer-host conformance or produce adoption receipts.
• check --providers selects any explicit provider subset or all; legacy --native selects fast plus Rust-native, and --comparison introduced|all controls the exact ASP comparison. Worktree and staged views are exact, inapplicable providers are skipped only for convenience sets, never silently when explicitly requested, and every run reports elapsed time.
• check --roots treats each selected non-overlapping subfolder as a focus while preserving exact repository capture/freshness and original-path rendering: fast rebases the focus, Node/Python retain nearest applicable ancestor project configuration, and Rust retains repository context while checking the focused Cargo package.
• Provider-aware Git filtering occurs before native file/byte bounds. Applicable Rust requests retain one fixed repository-wide Cargo build-input envelope so workspace/path dependencies and common sibling resources remain available without admitting unrelated media, archives, datasets, or opaque binaries; a required omitted input yields unavailable/incomplete native coverage.
• Rust-native executes one bounded cargo check --workspace --all-targets --message-format=json root command or cargo check --all-targets --message-format=json focused-package command in provider-private scratch with Cargo offline mode, uses --locked when applicable, binds and revalidates Cargo plus the PATH-selected rustc launcher, collapses repeated target diagnostics, ignores generic rustc failure notes, and reports unavailable/incomplete execution honestly without claiming that offline mode or narrowed environment is isolation.
• Node-native requires a root npm package/lock and exact tsconfig.json/tsconfig.*.json projects, installs the locked graph offline with scripts disabled, binds and revalidates npm, root project-local tsc, and the PATH-selected Node runtime, invokes tsc with no emit/incremental state plus --listFiles, treats the union of configured compiler files as its exact semantic universe, counts unconfigured JavaScript/TypeScript without letting them poison configured-project coverage, removes generated node_modules, and reports missing cache/compiler coverage honestly.
• Python-native prefers host Pyright and falls back to host mypy, deterministically selects an explicit, context-local .venv, active context-local, or ambient interpreter, passes it through the checker’s supported interpreter flag, hashes and revalidates it plus pyvenv.cfg, passes every exact selected .py/.pyi path, validates Pyright filesAnalyzed coverage, uses structured/strictly parsed diagnostics and an ephemeral cache, never provisions or mutates a Python environment, and makes unresolved imports under an ambient interpreter incomplete coverage.
• Native callback files are materialized as regular owner-read/write files because ASP v1.0 carries no executable modes; mode-sensitive builds remain explicitly outside this slice.
• Provider initialization reports the compile-time digest of Rust source, locked build inputs, and bundled ASP definition; installed manifests independently bind exact executable bytes with bounded stable hashing.
• introduced is deterministic ASP set difference by fingerprint, and all returns the full after-set.
• Node fixtures cover every declared extension, extension-selected CJS/ESM, shebangs, JSX/TSX, declaration files, and non-execution of source-shaped config.
• Fast Rust fixtures cover explicit stable editions 2018/2021/2024, adaptive local source parsing, attributes/cfg, opaque macros, build-script non-execution, and direct nightly feature-gate refusal.
• Python fixtures cover UTF-8/BOM/encoding cookies, stubs, packages/namespaces/src layouts, nested layouts, and non-UTF-8 unsupported coverage.
• Go fixtures cover .go/_test.go, current syntax and generics, UTF-8/BOM refusal semantics, target-bound filename and build constraints, functions/methods/literals, metrics, exports, struct/interface shapes, nested-callable omission, cancellation, and non-execution of the Go toolchain or generators.
• Protobuf fixtures cover proto2, proto3, and edition .proto syntax, invalid UTF-8/syntax, bounded parsing, and non-execution of protoc; deeper Sense facts remain explicitly unsupported.
• Fast rules include syntax, file/line limits, function limits, nesting, and cyclomatic complexity for every supported language family.
• Local sense compares one stabilized full HEAD/worktree pair, confirms only unique internal runtime/type/structural dependencies, and keeps type-only plus Rust structural edges out of runtime-cycle findings.
• Sense blocks only introduced runtime dependency cycles, exact nontrivial duplication, explicit module/edge/interface limit growth, and exact documentation obligations for mechanically important modules. Direct-dependency deltas and reverse impact remain bounded observations.
• Node graph fixtures cover static imports/re-exports and distinguish unsupported dynamic imports. Python graph fixtures cover unambiguous explicit-relative imports. Rust fixtures cover reachable conventional module trees, nested mod and use trees, structural reciprocity, interface limits, importance/documentation triggers, and explicit degradation for custom roots, cfg/path overrides, undeclared files, and ambiguous targets. Go graph fixtures cover exact root/nested go.mod package imports, package aggregation, runtime cycles, module-only changes, malformed metadata, external/conditional coverage, and worktree/staged/hypothetical views.
• Deduplication fixtures cover whole-file, callable-body, and arbitrary 48-token-region identity in Node, Python, Rust, and Go; baseline debt, exact rename, copy/delete, third-copy, nested callables, parser failure, forced anchor collisions, maximal-region merging, repetitive streams, cascade suppression, and truncation.
• Interface fixtures cover mixed runtime/type Node selectors, wildcard/namespace baseline authority, explicit exports and directly exported shapes, exact Python relative selectors/static and missing __all__, Rust structural dependency limits with unsupported public-surface coverage, Go package-aggregated exports and struct/interface shapes with namespace-width imports, partial lower bounds, baseline debt, declaration/test/barrel exclusions, important-node rename/deletion, and every default threshold boundary.
• Documentation fixtures cover strict registry parsing, missing/stale/renamed/deleted bindings, exact before/after document bytes, no-trigger lazy capture, concurrent mutation, and divergent linked worktrees.

§Robustness

• Two or more linked worktrees execute concurrently without cache corruption or cross-worktree findings.
• Worktrees at the same tree reuse unchanged file facts; divergent trees never share snapshot results incorrectly.
• Dirty, staged, untracked, deleted, renamed, and ASP-hypothetical files bind to exact content identities.
• Cache truncation, corruption, unsupported schema versions, abandoned temporary files, and concurrent writers produce safe misses/non-pass states.
• Path traversal, symlinks, directories, unsupported languages, non-UTF-8 bytes, giant frames/files/lines, callback refusal, truncated listings, malformed callback success payloads, malformed JSON-RPC, duplicate request IDs, cancellation, early exit, and timeouts are tested.
• Output never includes candidate absolute paths, unbounded source content, or host-owned ASP fields.
• Native diagnostics never expose scratch/target absolute paths, and temporary source/target trees never become reusable application state.
• Native post-run verification binds and revalidates the materialized root directory identity, requires callback files to remain regular and byte-identical, and rejects unexpected scratch entries. Only Rust-native may permit and hash a newly generated root Cargo.lock; Node/Python permit no generated entry. This is mutation detection, not containment.
• The private harness process group is swept on every terminal path, including successful provider exit, but this remains best-effort lifecycle cleanup because candidate descendants may change group/session.
• Native reports advisory execution assurance and is absent from default Check and installed hooks until an external OS sandbox enforces mount/filesystem, network, descendant, CPU/RSS, and secret boundaries, including reads through external/path dependencies and writes by executed code.
• Graph topology, comparisons, dirty views, and resolved targets are never persisted. Content facts are shared across linked worktrees without cross-worktree findings.
• Sense handles staged deletions/additions, dirty overrides, untracked files, exact renames, sparse files, unborn HEAD, and source mutation during capture without mixing views.
• Graph and exact-duplicate algorithms remain deterministic and bounded for self-loops, disjoint and expanding SCCs, dense edges, deep paths, ambiguous resolution, baseline duplicate debt, rename/copy-delete continuity, large duplicate groups, and oversized outputs.

§Performance Measurements

• Criterion or equivalent benchmarks record cold and warm latency, throughput, parsed file count, and cache hits for investigation.
• Fast checks never enumerate or materialize the whole workspace for a changed-path request unless a selected rule explicitly requires workspace scope.
• Large-project stress includes at least 10,000 files and a 1,000-file changed set without unbounded memory or quadratic behavior.
• Native integration exercises profile switching, explicit comparisons/timing, all-provider applicability skips, project-aware selected roots, provider-aware capture, Node locked TypeScript checking, runtime identity, and explicit configured/unconfigured file counts, Python .venv selection, Pyright/mypy parsing, ambient-import degradation, and file-count validation, Rust Cargo/rustc-launcher identity and diagnostic de-duplication, large-result human summarization, cancellation/output bounds, and candidate-tree non-mutation.
• Sense benchmarks report capture, combined fact loading/extraction, resolution, cycles, observations, exact duplication, rendering, wall time, RSS, unique source bytes analyzed, and hits/misses for cold/warm 1k and 10k repositories, a meaningful one-file overlay, 1k dependency-changing files, dense edges, many baseline SCCs, and concurrent linked worktrees. The release stress also records empty-changed Verify wall time, phase timing, cache evidence, and RSS on the 10k repository.
• The 10k fixture records cold and warm timings, one-file overlays, eight concurrent linked worktrees, and peak request RSS. Performance measurements are diagnostic evidence, never release pass/fail criteria.

§ASP Boundary

• Accept only canonical ASP check/evaluate requests and advertise only implemented behavior.
• Assessments bind the exact baseline, recomputed ChangeSet digest, read blobs, config, build, timing, and cache state.
• Artifact checksums do not claim trust, certification, registry status, authority, or a host decision.

§Adversarial Review

• Independent reviewers challenge the architecture and implementation before installation work begins.
• After implementation, one dedicated adversarial tester per language family exercises varied layouts and sizes.
• Findings are fixed and retested until no reproducible correctness, isolation, or crash defect remains within the acceptance scope. Performance measurements remain visible for regression investigation.

§Release Proof

• Normal CI runs the eight-worktree documentation-isolation Sense stress by exact test name. This exercises concurrent cache sharing, divergent worktree findings, and warm-cache reuse without opting environment-sensitive Sense latency thresholds into the shared runner gate.
• CI runs the ignored Sense stress suite with --nocapture to retain graph, cache, timing, worktree, and Linux RSS evidence. No elapsed-time or RSS threshold gates a release; the test still enforces bounded completion and deterministic behavior.
• Release proof retains both versioned platform archives, validates each with the same extractor shipped to npm, and binds them in both the npm package and GitHub Release SHA256SUMS. The package version, Git tag, Cargo version, release URL, and archive filename must agree exactly. npm removal proof uses opcore uninstall before npm removes the facade because npm v7 and newer provide no uninstall lifecycle hook.