Define the explicit OS, toolchain, host, API, configuration, and storage support policy

[Punisheroot]

Context

Needle is a pre-alpha source project and currently makes no stable installation
or configuration promise. The repository documents Rust 1.90.0, Node.js 22
for the embedded web build, Codex 0.144.0 for the validated App Server
adapter, MCP protocol versions 2025-06-18 and 2024-11-05, additive SQLite
migrations, and a format revision for configuration export/import. Windows has
bounded live calibration; Linux and macOS have code/CI support only. These facts
are distributed across setup, configuration, transport, fixture, and status
documents rather than one enforceable policy.

Expected outcome

Publish one versioned compatibility matrix that distinguishes supported,
validated, experimental, and unsupported combinations. The policy covers OS and
architecture, Rust/toolchain, Node/npm build tooling, native Codex/App Server,
CLI/API/MCP schemas, TOML configuration format, SQLite storage/migrations, and
archive targets. Machine-readable fixtures and negative tests enforce the
matrix; a policy change is reviewable and cannot silently broaden support.

Scope

• Define the minimum/maximum or tested range for Windows, Linux, and macOS,
  including architecture and any MSVC/SDK or Unix-socket constraints that are
  actually validated.
• State Rust 1.90.0 and Node.js 22 roles precisely (compiler/test/build
  requirements versus runtime requirements) and record lockfile/toolchain
  identity.
• Bind the Codex/App Server adapter to its supported version and required
  methods/approval fields using the existing compatibility.json fixture;
  define how a newer/older Codex version is rejected or downgraded.
• Version the CLI/API/MCP contracts, semantic/Need IR and proof/result schema
  revisions, and document that pre-alpha interfaces remain unstable until an
  explicit policy transition.
• Define the generic schema-version, fixture, digest, and unknown-version
  rejection policy for configuration projections. Concrete Claude Code and
  Cursor schema pins belong to their host-specific adapter work, not this
  foundational matrix.
• Define configuration export/import compatibility (format_revision, digest
  checks, rejected revisions) and SQLite storage migration/checksum behavior,
  including backup/upgrade and downgrade expectations.
• Add a single human-readable policy plus machine-readable matrix/fixtures and
  CI tests for supported and intentionally rejected combinations.

Non-goals

• Claiming a stable public API, database schema, installation, or support window
  before the policy is accepted and release gates pass.
• Adding a new host adapter, provider, OS, architecture, or migration solely to
  make the matrix look complete.
• Turning configuration interoperability into non-Codex execution or
  orchestration support.
• Publishing archives or releases; this policy is an input to
  the cross-platform plugin archive release work.

Acceptance criteria

• docs/ contains one normative compatibility policy with a table that
  labels each OS/architecture, Rust/toolchain, Node/npm, Codex/App Server,
  CLI/API/MCP, configuration, storage, and archive combination as supported,
  validated-only, experimental, or unsupported.
• The policy records the current known anchors: Rust 1.90.0, Node.js 22
  build-only, Codex 0.144.0, MCP 2025-06-18/2024-11-05, configuration
  format revision, and SQLite migration/checksum behavior; it does not invent
  live evidence for Linux or macOS.
• A machine-readable matrix and fixture digest are checked in; CI validates
  every supported row and asserts that unsupported Codex/API/config/storage
  revisions fail closed with actionable diagnostics.
• The Codex fixture test verifies the version and required methods/approval
  shapes, and a fixture for a mismatched Codex version is rejected.
• TOML export/import fixtures cover accepted and rejected format revisions,
  definition-digest mismatch, omitted credentials, and round-trip stability.
• SQLite fixtures cover a fresh database, all current additive migrations,
  checksum mismatch, and a documented backup/upgrade path; downgrade behavior is
  explicit rather than implied.
• CI documentation distinguishes code compilation from provider-backed
  platform evidence and identifies the exact commands that are safe offline.
• A policy revision changes the matrix/fixture digest and is recorded in the
  release/readiness checklist; no automatic support expansion occurs.

Validation

cd crates/needle-app/web
npm ci
npm run build
cd ../../..
cargo fmt --all -- --check
cargo test --locked -p needle-platform-codex fixture_is_bound_to_supported_version_and_required_approval_methods
cargo test --locked -p needle-runtime --lib
cargo test --locked -p needle-core --lib
cargo test --locked --workspace

The focused fixture tests must be extended with the new matrix, config, and
storage fixtures. The workspace command is the final offline compatibility
regression check; no command in this issue authorizes a provider run.

Starting points

• PROJECT_STATUS.md (current platform/evidence and release limitations).
• docs/DEVELOPER_SETUP.md (Rust, Node, Codex, build, and runtime boundaries).
• docs/CONFIGURATION.md (ConfigExport, format/digest checks, SQLite profile,
  and credential boundary).
• docs/MCP_TRANSPORT.md (supported protocol revisions and schema behavior).
• crates/needle-platform-codex/src/app_server.rs
  (validate_compatibility_fixture and its focused test).
• crates/needle-runtime/src/store.rs (config import/export and checksummed
  migrations).
• fixtures/codex-app-server/0.144.0/compatibility.json.

Dependencies

• This policy is foundational. The portable Linux live preflight and operator
  harness, machine-enforceable provider preflight, and cross-platform plugin
  archive release work consume its matrix and fixture digest after acceptance;
  none is a prerequisite for defining the policy.
• Any API/config/storage row must name its owning schema/fixture and migration
  policy before it is marked supported.
• Compatibility claims remain subordinate to PROJECT_STATUS.md evidence
  levels and the Codex-first execution boundary.

Ownership and risk

The compatibility owner owns the normative matrix, fixture schema/digests, and
documentation synchronization. Platform, API, and storage reviewers own the
negative cases and upgrade/downgrade safety. The primary risk is accidental
support inflation from compiling on an OS or accepting an unknown schema;
require explicit fixture evidence and fail closed on unknown versions.