Skip to content

Fleet: fail-closed TOML and CLI-flag contract admission across zed-pkg #87

Description

@ORESoftware

Problem

The current Zed release harness now validates the selected zed-cli and flags-2-env pair, but the organization does not yet have one fleet-level admission inventory for tracked TOML contracts.

The 2026-09-10 audit found a concrete coupled-pin defect: the tagged E2E workflow initially paired a current canonical flags-2-env revision with an older Zed CLI whose Cargo.toml still referenced the legacy repository and a different commit. PR zed-pkg/zed-e2e#40 fixes that tuple and adds repository-level checks, but equivalent drift can recur elsewhere.

Required scope

Create a fail-closed scanner and reusable admission workflow for every active zed-pkg repository. It must inventory and validate, as applicable:

  • .cli-flags.toml and every root .*-cli-flags.toml file;
  • .zpkg.toml and related Zed package manifests/locks;
  • Cargo.toml, workspace manifests, and rust-toolchain.toml;
  • pyproject.toml, Dart/Flutter TOML bridges, and other tracked *.toml files;
  • immutable cross-repository git revisions declared inside TOML;
  • canonical repository ownership, especially flags-2-env/flags-2-env and zed-pkg/* dependencies.

Admission behavior

  1. Parse every tracked TOML file with a standards-compliant parser; syntax errors are blocking.
  2. Execute the exact pinned native flags2env audit implementation against every CLI flag contract.
  3. Verify the parser revision equals the revision consumed by the selected CLI/runtime dependency; independent overrides must fail closed when incompatible.
  4. Validate .zpkg.toml with an immutable reviewed Zed CLI and run deterministic zed validate / zed pack smoke checks where a package manifest exists.
  5. Reject legacy owners, mutable branch references, mismatched lock/manifests, duplicate flag/environment declarations, and undocumented skipped files.
  6. Produce a machine-readable receipt with repository, source SHA, validator/toolchain SHAs, file digests, findings, and bounded exception metadata.
  7. Read the current PR candidate for the scanner repository itself while using default branches for other fleet members, following the exact-head pattern landed in .github#86.
  8. Keep exceptions path/pin scoped, owned, reasoned, and expiry bounded. Expired exceptions are blocking findings.

Safety and ownership

  • Treat authored TOML as authoritative; generated mirrors are evidence only.
  • Do not rewrite manifests automatically merely to make the gate pass.
  • Preserve my-ai/AGENTS.md semantic-conflict rules: no rebase/reset/stash/force-push or blanket side selection.
  • Never persist chat-provided credentials or weaken checks for private visibility; use an approved read-only Actions secret with an explicit bounded visibility exception until configured.

Acceptance criteria

  • Deterministic fixture tests cover valid files, malformed TOML, mutable refs, legacy owners, parser/CLI mismatch, duplicate flag declarations, stale .zpkg.lock, unreadable required repositories, and exception expiry.
  • Live scan covers all active visible zed-pkg repositories and retains evidence artifacts.
  • Reusable workflow is pinned by immutable merge SHA in consumers.
  • Existing TJSV fleet scanning remains independent and green.
  • zed-pkg/zed-e2e#40 and .github#86 remain regression inputs rather than duplicated implementations.

Related: DEN-3982, zed-pkg/zed-e2e#40, zed-pkg/.github#86.

Activity

  1. ORESoftware commented on Sep 10, 2026

    @ORESoftware
    ContributorAuthor

    2026-09-10 implementation evidence and follow-up scope

    The focused audit has now produced concrete regression inputs for this fleet task:

    • .github#86 merged exact-PR-candidate self-scanning for the existing TJSV fleet gate; post-merge policy/privacy/scratch/TJSV workflows are green.
    • zed-e2e#40 now binds a coherent immutable zed-cli/flags-2-env pair, parses all tracked TOML in both checkouts, validates the Cargo dependency URL/revision, and runs the exact native parser over all six root CLI contracts.
    • zed-cli#338 is the reopened authoritative Rust-native consolidation for current CLI/package TOML. It includes .zpkg.toml↔Cargo version parity, all tracked TOML parsing, native flags2env audit, fail-closed allow_unknown, canonical scalar type names, command-scope parity with Clap, root env/alias uniqueness, canonical dependency ownership, exact toolchain parity, and public Zed-bin/build-output checks.
    • Focused overlapping PRs were closed only after their useful semantics and regression coverage were visible in #338. The attempted stale-head update was rejected by a non-fast-forward guard; concurrent work was re-read instead of overwritten.

    Additional fleet acceptance criteria derived from this audit:

    1. distinguish Cargo build targets from deliberately public .zpkg.toml [bin] entries rather than forcing all binaries public;
    2. validate option/env uniqueness within each command scope, while allowing the same spelling or env in distinct subcommands where the typed CLI does;
    3. compare .zpkg.toml package identity to the ecosystem-native package manifest and validate every public binary against both the native build target and the Zed build-output allowlist;
    4. verify the exact Rust/toolchain version used by reusable and release workflows against rust-toolchain.toml;
    5. treat current PR candidate content as authoritative for the scanner repository itself and default-branch content for other fleet members.

    Linear could not create a new child because the workspace issue quota is exhausted; DEN-3982 now carries the link and evidence. This GitHub issue remains the canonical new-task record.

  2. ORESoftware commented on Sep 10, 2026

    @ORESoftware
    ContributorAuthor

    2026-09-10 execution checkpoint

    Two tested Zed/TOML changes are now merged:

    • .github#86 merged as b8fa19f1964fa541bca9a318f30c6a2643423e7a after exact head 7308cac538f8364db355cdc21ebc2bff300f53ec passed baseline policy, privacy, scratch-ignore, and the live TJSV fleet scan.
    • zed-mcp-server.rs#5 merged as eab36156077b7ae0f3a400245ff392968d0ee54e after exact head 4e43910707820988d2dae2623821b4ddd47c8fdd passed CI, MCP peer-contract, and secrets-audit workflows. It corrects the Zed CLI package range to the released ^0.3.0 line.

    Two larger candidates are review-ready but intentionally not merged while exact-head GitHub Actions remain queued:

    • zed-cli#338, current clean product tree at 0b0230cf8b8f0aa6b89b7df0e1894541969f31a0, consolidates CLI/TOML/package/toolchain checks. A transient branch-specific write-enabled repair workflow was detected and removed; c5f0ce5... and 0b0230c... have identical trees. Fresh exact-head workflows are queued and cancelled predecessors are not counted as passes.
    • zed-e2e#40, current head 8c5dc64755396903b3fd7dacc33da29c318f771a, binds canonical flags-2-env, a coherent immutable CLI/parser tuple, tracked-TOML parsing, .zpkg.toml package-line parity, and native audit of all six root CLI flag contracts. Its four required workflows are queued/pending.

    The organization currently has a substantial Actions backlog, also affecting post-merge jobs on already-landed commits. No queued, pending, cancelled, or zero-step run is being represented as successful.

    This issue remains the canonical fleet follow-up for expanding those repo-local checks across all active zed-pkg TOML surfaces. No credential value was persisted, rotated, or revoked, and no rebase/reset/stash/force update or blanket conflict-side selection was used.

  3. ORESoftware commented on Sep 10, 2026

    @ORESoftware
    ContributorAuthor

    Google Chat exact-window reconciliation linkage: ORESoftware/my-ai#141, tail record S10-05 (2026-09-10).

    This issue is the canonical owner for that prompt's Zed-specific requirement; do not create a duplicate issue merely for Chat accounting. Please treat the following as explicit acceptance refinements:

    • consume the canonical flags2env env-manifest/reconciliation behavior tracked by ORESoftware/flags-2-env#49 rather than implementing a second TOML/env parser;
    • include .cli-flags.toml plus every tracked root/runtime *.toml family in the same deterministic inventory, with explicit skipped-file reasons;
    • cross-check CLI/argv-capable env ownership against env-only secret bindings and fail closed on duplicates/conflicts;
    • retain machine-readable source SHA/tool SHA/file-digest evidence so Chat reconciliation can point to immutable implementation proof;
    • keep zed-cli#345, zed-cli#350, .github#88, and zed-web-server.rs#55 as child/canonical slices where their scopes match rather than duplicating them.

    Historical Chat bodies/credentials are intentionally not reproduced here. Final completion should link the exact implementation PR heads back to ORESoftware/my-ai#141.

  4. ORESoftware commented on Sep 14, 2026

    @ORESoftware
    ContributorAuthor

    Broader package/SDK env-contract refinement after re-verifying the canonical implementation: flags-2-env/flags-2-env#16 is merged at 333c2ace93c362d274171ab0e0edf613d96a8e59 and already owns deterministic root [[env]] discovery, value-free manifest.env, .cli-flags.toml indexing, argv-vs-env-only ownership, secret/default refusal, and key-only encrypted/plain inventory reconciliation. Zed fleet work should consume that exact authority rather than recreate it.

    Add one Zed-specific layer that #16 intentionally does not own: transitive package env requirements. A library/SDK package such as ores-locks-and-leases or ores-redis-lru-cache should be able to publish value-free environment metadata through .zpkg.toml/package metadata, and zed validate should compute the deterministic transitive union for an application. Requirements:

    • preserve source package + version/revision provenance for every env requirement;
    • merge compatible repeated keys, but fail on type/required/secret/exposure disagreement;
    • distinguish runtime-required, build-only, dev/test-only, server-only, and client-safe scope where the package metadata declares it;
    • never synthesize env-only secrets into argv flags;
    • emit the transitive requirement set through the canonical flags2env JSON/manifest representation rather than inventing a second format;
    • compare the resolved application set with its .cli-flags.toml, domain TOMLs, and ores-cli source-read evidence;
    • include cycle/diamond dependency fixtures so the result is deterministic regardless of traversal order.

    This keeps package declaration ownership in Zed, environment normalization in flags2env, and fleet/source reconciliation in ores-cli.

  5. self-assigned this
    on Sep 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions