Palomar Reviewer
The editorial reviewer for mechanically passing Palomar submissions. No person starts a review or approves a report.
palomar-review reads submissions from the private PalomarSubmissionState repository the submission server writes, checks out the immutable source and a pinned PalomarPolicy commit, executes the ordered policy prompts with Codex, Claude, or another JSON-producing command, validates the final report, and then:
- delivers the review privately to the submitter, and to nobody else;
- once, and only once, the submitter chooses to register, prepares and opens the
append-only database pull request for a registrable entry;
- verifies the merged record and records the registration against the private
submission record.
The review is never posted in public. A review the submitter does not register leaves no public trace of itself, which is the whole reason the intake is private. What is public from the moment of submission is the mechanical verification: the repository, the commit, and the GitHub Actions run that checked them, because that run is a public workflow with public logs.
The reviewer takes the mechanical report from the verification run the submission server recorded for that submission, matched by run id and by exact run name. The submission id appears in a public run title, so anyone able to dispatch the workflow can produce a run carrying it; the name is therefore not the trust boundary. The report is bound to the private record's repository, commit, requested paths and authorization, and to pinned Comparator/Lean-export/Landrun/NanoDa revisions on a workflow commit that is an ancestor of main.
palomarreviewer.mechanical is the current mechanical-evidence contract. It owns the report schema, safe repository-path resolution, and the data bindings among the report, private submission record, and recorded workflow run. The CLI remains the composition root: it selects and downloads the server-recorded artifact, applies that contract before cloning source, and only then asks GitHub whether the validated workflow commit is still on main's lineage. The path helpers inspect filesystem metadata only inside a caller-supplied source checkout; the module reads no file contents and has no network, subprocess, environment, clock, or state-repository access. Registration separately rechecks the stored report bytes, semantic digest, and workflow-run digest before using an inspected workspace.
Failed preflight and full runs use the same trust boundary. ingest-failures downloads the exact recorded run's mode-specific artifact, validates its submission/source binding, redacts it to the diagnostics-v1 contract, and writes the failure together with its terminal status. A missing or untrusted artifact becomes an explicit Palomar-owned diagnostic rather than a submitter fault. The same atomic write creates a private operator-alert outbox entry for every diagnostic whose owner is palomar or provider, matching the status page's "Palomar must fix this" assignment. notify-operator-alerts posts each pending entry to Palomar maintainers / operator alerts with the submission, source commit, public workflow run, diagnostic, and next action, then conditionally records the returned Zulip message id. The status token is never rendered. Terminal submissions remain in the open queue until every alert is acknowledged, so a missing credential or Zulip outage is retried by a later pass. Delivery is at least once: the narrow failure window after Zulip accepts a message but before the conditional State write may produce a duplicate carrying the same stable alert-key prefix.
The notifier requires a Zulip bot's PALOMARZULIPEMAIL and PALOMARZULIPAPIKEY. Those secrets belong only in the trusted private State workflow; they must never be passed to public submission verification or to a candidate-controlled subprocess.
repair-queue handles the separate metadata-repair outbox. It accepts only the exact versioned profile allowlist, including bounded structured people, source, automation, and substantive-repository values. It creates missing mappings and round-trips valid YAML without replacing the whole file, refuses aliases and malformed YAML, and pushes only to an Actions-disabled fork in PalomarRepairs using PALOMARREPAIRTOKEN. Before opening a PR it runs the candidate commit through PalomarSubmission/scripts/verifysubmission.py prepare from main, the same entry point as ordinary preflight. That subprocess runs in the same fail-closed Bubblewrap namespace the review engines run in, and no host without bubblewrap runs it at all. What it is given is a git archive export of the Submission checkout at HEAD rather than the working tree, so neither .git/config, whose extraheader can carry the credential the checkout was made with, nor any untracked file beside it is reachable; the runner's interpreter, Git and Bundler read-only, never through a mount that would carry the operator's home, workspace, or temporary directory in with it; one writable directory; /dev/null on standard input; and an environment built from an exact list of names. That list is exact rather than prefixed because Bundler documents credentials in BUNDLE-prefixed variables (BUNDLEGITHUBCOM and every other BUNDLE<HOST<TLD), and a proxy variable whose URL carries userinfo is a refusal rather than something to pass on. Bubblewrap itself is started with that same environment, because it stays at PID 1 inside the namespace and /proc/1/environ is readable from in there. Neither State write authority nor either GitHub token crosses into candidate-controlled intake.
The documented residual is the network. prepare resolves the candidate commit by fetching it, Bubblewrap shares the host's network view or nothing at all, and it cannot filter egress; so repair preflight is supported only on an ephemeral runner with no private routing and no managed identity or instance-metadata endpoint that grants anything, which is what a GitHub-hosted runner is. A self-hosted runner that can reach an internal network is not a supported place to run it. Failed candidate validation leaves an actionable explanation and manual patch, removes the temporary repair branch, and never opens a knowingly failing PR. Finished pull requests also have their exact deterministic repair branch removed on a best-effort basis.
upgrade-repair-failures reruns current preflight for settled profile-1 formalization.missingsections failures and replaces only their failure guidance with profile-3 diagnostics and safe draft values. The submission id, status, original run link, and history are retained, and a migration event is appended. Pass --submission ID for one record or omit it for all eligible records; as with every State mutation, the operator must explicitly set PALOMARALLOWSTATEWRITES=1.
palomarreviewer.authorization is the pure registration-authorization contract. It owns the permitted push-proof methods, binds the private State record to the report and review, requires the positive one-time consent state, and checks that the delivered, consented-to, and registering review have one canonical digest. New work applies the complete contract after the credential-output backstop, no-blocking-problem outcome check, and stored report/run/policy bindings and before source preservation, render, or database work. Recovery of an already-created branch applies the narrower current State/review/source standing first, then validates the reserved public record instead of repeating those side effects. The module performs no retrieval, filesystem access, subprocess, network, State write, or public action.
Mechanical review accepts the explicit technical-test relationship so an operator can exercise the pipeline honestly. Registration authorization rejects that relationship, its State marker, or its distinct proof method before any public side effect, even if a consent flag was forged.
palomarreviewer.checkpoint owns the saved-attempt, deterministic-branch, same-repository PR, immutable-record, and idempotent State-checkpoint contract. The CLI supplies its GitHub read/create and conditional State-write adapters; the module has no dependency back into the CLI and exposes no compatibility path for a branch or record outside the one current reserved shape.