fix(release): isolate draft visibility admission

[slashdevcorpse]

Summary

• isolate exact draft visibility validation in a five-minute Ubuntu admission job with the only pre-build contents: write token
• authenticate protected main, the owner-triggered controller, source SHA, version, tag, and draft ID before checkout
• keep dependency installation and release qualification in the read-only preflight
• require both admission and preflight before Windows/macOS builds, and require admission success before publication
• lock exact step structure, environment bindings, fail-closed commands, validator ownership, permission exceptions, and all dependent-job topology in workflow contracts

Root cause

Release Drafter run https://github.com/slashdevcorpse/synara/actions/runs/29865616891 failed closed because the reusable preflight had contents: read; its token could not enumerate the private draft that the controller had just validated. Windows and publication were correctly skipped. The caller already grants contents: write, so this change narrows that capability to a minimal admission job rather than exposing it to the heavy preflight.

Verification

• bun run --cwd scripts test -- lib/super-synara-workflow-contract.test.ts lib/workflow-contracts.test.ts lib/super-synara-release-state.test.ts lib/super-synara-github-payload.test.ts lib/gh-cli.test.ts (90 passed)
• node scripts/verify-workflow-contracts.ts
• exact-file oxfmt --check on the five touched files
• exact-file oxlint on the four touched TypeScript files (two existing no-array-sort warnings only)
• git diff --check
• two independent review passes; blocking contract-drift findings addressed in follow-up commits

After merge and protected-main checks, the release controller will be rerun in windows-only mode against the exact merged SHA.

Summary by CodeRabbit

• New Features
  • Added a dedicated draft-admission validation job that runs before prerelease builds and publishing.
  • Publishing now waits for successful draft admission in addition to existing preflight checks.
• Bug Fixes
  • Strengthened workflow contract checks to enforce fail-closed draft visibility, strict caller/owner validation, exact step structure, and correct job dependency wiring.
  • Pinned key GitHub Actions (checkout/setup-node) for consistent release behavior.
  • Updated allowed write permissions to permit write access specifically for the draft-admission stage.
• Tests
  • Expanded contract tests to validate draft-admission isolation, dependency tampering rejection, and phase-specific “run exactly once” behavior.

Greptile Summary

This PR isolates release-draft visibility validation into a dedicated draft_admission job that holds contents: write, fixing the root cause where the read-only preflight job could not enumerate private draft releases. All native build jobs and publish are gated on both draft_admission and preflight succeeding, and the topology is locked by updated workflow contracts and tests.

• Adds draft_admission as a five-minute, write-scoped Ubuntu job that authenticates the caller workflow ref, protected-main status, source SHA, owner/actor, VERSION regex, TAG format, and DRAFT_ID before checkout and draft validation.
• Removes the "Validate GitHub tag and release state" step from preflight, replacing it with the stricter admission step; updates PUBLISH_JOB_CONDITION and the allowedWritePermission allowlist accordingly.
• Extends contract tests (verifyDraftAdmissionJob, verifyPublicationJobDependencies) with exact-key and exact-array checks, and locks down bypass mutations.

Confidence Score: 5/5

Safe to merge — narrows a concrete permission gap, and the new contract enforcement is locked down end-to-end.

The root cause (read-only preflight token blocking draft enumeration) is correctly fixed by isolating the capability to a minimal, write-scoped job. Contract changes lock the new structure with exact-key and exact-array comparisons, the allowlist is updated, and the test suite exercises every meaningful bypass mutation.

No files require special attention.

Important Files Changed

Filename	Overview
.github/workflows/super-synara-prerelease.yml	Adds draft_admission job with contents: write; gates windows_x64, macos_arm64, and publish on it; removes draft validation from the read-only preflight job.
scripts/lib/super-synara-workflow-contract.ts	Adds verifyDraftAdmissionJob and verifyPublicationJobDependencies; moves SETUP_NODE_ACTION and adds CHECKOUT_ACTION to top-level constants; updates PUBLISH_JOB_CONDITION.
scripts/lib/super-synara-workflow-contract.test.ts	Adds three new it blocks covering admission permission enforcement, authorization step mutations, validation step mutations, validator-isolation rules, and job dependency wiring.
scripts/lib/workflow-contracts.ts	Updates allowedWritePermission to allowlist jobs.draft_admission.permissions instead of jobs.reserve_tag.permissions.
scripts/lib/workflow-contracts.test.ts	Adds positive and negative test cases for the updated allowlist, confirming draft_admission is valid and preflight with contents: write is rejected.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    trigger([workflow_call]) --> draft_admission
    draft_admission["draft_admission\n(ubuntu-24.04, contents: write)\nAuthorize + Checkout + Setup Node + Validate draft"]
    trigger --> preflight
    preflight["preflight\n(ubuntu-24.04, contents: read)"]
    draft_admission --> windows_x64
    preflight --> windows_x64
    draft_admission --> macos_arm64
    preflight --> macos_arm64
    windows_x64 --> publish
    macos_arm64 --> publish
    draft_admission --> publish
    preflight --> publish
    publish["publish"]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    trigger([workflow_call]) --> draft_admission
    draft_admission["draft_admission\n(ubuntu-24.04, contents: write)\nAuthorize + Checkout + Setup Node + Validate draft"]
    trigger --> preflight
    preflight["preflight\n(ubuntu-24.04, contents: read)"]
    draft_admission --> windows_x64
    preflight --> windows_x64
    draft_admission --> macos_arm64
    preflight --> macos_arm64
    windows_x64 --> publish
    macos_arm64 --> publish
    draft_admission --> publish
    preflight --> publish
    publish["publish"]

Loading

_{Reviews (4): Last reviewed commit: "test(release): confine state validation ..." | Re-trigger Greptile}

[coderabbitai]

📝 Walkthrough

Walkthrough

The prerelease workflow adds a draft_admission job for source and draft validation, wires downstream jobs to require it, and extends workflow contract verification and tests for admission structure, permissions, dependencies, and failure messages.

Changes

Draft admission and publication gating

Layer / File(s)	Summary
Add draft admission and downstream gating .github/workflows/super-synara-prerelease.yml	Adds source, ownership, version, tag, and draft validation before checkout; build and publish jobs now require successful admission.
Enforce admission job contracts scripts/lib/super-synara-workflow-contract.ts	Requires the admission job, validates its steps and security conditions, and enforces exact downstream dependencies and publish gating.
Cover permissions and regression cases scripts/lib/super-synara-workflow-contract.test.ts, scripts/lib/workflow-contracts.test.ts, scripts/lib/workflow-contracts.ts	Adds admission, dependency, and permission tests and updates expected authentication failure messages.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant WorkflowTrigger
  participant DraftAdmission
  participant Preflight
  participant Publish
  WorkflowTrigger->>DraftAdmission: Validate protected source and draft identity
  DraftAdmission->>DraftAdmission: Checkout admitted SHA and verify draft visibility
  DraftAdmission->>Preflight: Successful admission
  Preflight->>Publish: Validation result
  DraftAdmission->>Publish: Admission result
  Publish->>Publish: Require admission and lane success

Loading

Possibly related PRs

• slashdevcorpse/synara#56: Tightens related owned-draft lookup requirements in the shared workflow contract.
• slashdevcorpse/synara#58: Extends related owned-draft visibility and publication workflow contract checks.
• slashdevcorpse/synara#63: Also enforces pinned actions/setup-node usage in workflow contracts.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise and accurately describes the main change: isolating draft visibility admission in the release flow.
Description check	✅ Passed	It clearly covers what changed, why, and verification; the UI section is non-applicable.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 85.96491% with 8 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
scripts/lib/super-synara-workflow-contract.ts	85.96%	3 Missing and 5 partials ⚠️

📢 Thoughts on this report? Let us know!

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request