website/docs/native-commons-controller.md

Native Commons and nonpublishing PR verification

This source adds data adapters to the independently installed controller. It does not install a controller, make a production pin, change a provider, add a schema migration or establish operational acceptance. The existing artifact, planner, Cloudflare, promotion and HTTP engines are reused unchanged. Commons promotion defaults OFF, and the native schema and existing six live bindings leave dormant identity and QA behavior OFF.

Fixed configuration and credential profiles

The external config has integer schema:3 and exactly pins, policy, consumer, source_repository, credentials, attestation_key, workspace. The schema-2 pins table has exactly production and review. Root separately accepts both immutable pins. All bundle, runtime, repository, workflow path/hash and job fields must match between them. Production has events:["push"] and Repository checks / repository-baseline (push); review has events:["pull_request"] and Repository checks / repository-baseline (pull_request). There is no caller-selected pin or pin path.

Mode	Target	Credential profile	Final consumer
verify	review	verify	nonpublishing review
plan	production-static	static	static plan
publish	production-static	static	static publication
recover	production-static	static	static recovery
commons-plan	production-commons	commons-plan	read-only Commons plan
commons-promote	production-commons	commons-promote	code-only Commons promotion

The operating package maps each profile to its fixed Root-owned template and materializes only the selected profile at the single fixed credentials path (active-credentials.json). Paths, target, profile and environment values are not client options. The closed key-set check runs before any native read, runtime initialization or container action. All profiles require exactly:

GITHUB_ACTIONS, GITHUB_SERVER_URL, GITHUB_API_URL, GITHUB_REPOSITORY, GITHUB_REPOSITORY_ID, GITHUB_REF, GITHUB_SHA, GITHUB_RUN_ID, GITHUB_RUN_ATTEMPT.

Profile	Additional exact keys
verify	NATIVE_FORGE_TOKEN
static	STATIC_FORGE_TOKEN, STATIC_PUBLISH_ENABLED, STATIC_API_RELEASE_SHA, STATIC_ORIGIN_IP, STATIC_SSH_USER, STATIC_SSH_PORT, STATIC_SSH_HOST_KEY, STATIC_RUNTIME_SHA256, STATIC_SSH_KEY, CF_RELEASE_TOKEN
commons-plan and commons-promote	COMMONS_FORGE_TOKEN, COMMONS_CF_TOKEN, COMMONS_ACCOUNT_ID, COMMONS_ZONE_ID, COMMONS_D1_ID, COMMONS_ROUTE_ID, COMMONS_ORIGIN_IP, COMMONS_PROMOTE_ENABLED

Review uses a repository-read-only token and cannot carry SSH, edge, provider or database authority. Commons credentials cannot appear in static or review profiles. Root scopes the Commons plan template to the required provider reads; the plan code issues no intent or provider write. The provider's D1 schema-query POST carries only the fixed SELECT in commons_artifact.SCHEMA_QUERY; metadata and preserved-schema reads do not execute a migration or access application rows. Commons plan requires the promotion flag false; promote also accepts a loaded OFF profile but refuses execution unless the flag is exactly true.

Request and receipt domains

The protected request has exactly integer schema:1, candidate, mode, target, credential_profile, repository_id, controller_run_id, controller_run_attempt, review. Repository ID comes from the protected template. Run ID (positive, at most 15 digits) and attempt (1–99) come from the durable shared operating allocator, never a client. review is null outside verify. For verify it has exactly positive integer number, head_sha equal to candidate, base_sha, head_ref, base_ref:"main". The bootstrap CLI accepts --pull-request, --base-sha, --head-ref only for verify; no other mode can carry those options. Canonical refs, same-repository names and immutable IDs are checked live, and current protected main must equal the bound base.

Receipt v3 authenticates the whole typed request, pin, independent bundle/runtime identities, native record, prepared-input inventory, complete fixed command sequence, three builds and resulting artifact inventory. Ordinary receipts use kind forge-execution-hmac and prefix oss-oo/execution/v3\0. Review uses kind forge-review-hmac and prefix oss-oo/review/v1\0. Prefixes denote their ASCII bytes followed by one NUL. No old schema, unprefixed MAC, kind relabeling or review-to-production substitution is accepted. Plan and promote also have distinct request modes; a plan receipt cannot authorize promotion.

Verify checks the same open, unmerged, same-repository PR at pre-build, post-build and final-consumer boundaries. It binds exact PR number, head/base branches and SHAs, repository IDs/names, current main, native ordinary pull_request run, exact workflow bytes, newest successful run, complete pagination, server re-read, successful jobs/attempts and status-link display index. The authenticated review record hashes the full current PR object and native payload. Metadata links are never authority. Verify reads public main's protected flag but never the privileged full branch-protection route. Root reads the full protection independently; Commons production rechecks every exact D4 field at its production boundaries. A passing review result explicitly has publication_verified:false and promoted:false. A merge requires a new native push proof and a complete mode-specific production chain.

Data-only Commons adapter and write boundaries

Protected main and release ledgers

Same-repository native Actions tokens have repository write authority; the workflow's permissions mapping does not make them read-only. Removing production credentials from Actions is necessary but does not replace protected refs.

Every production preflight requires the exact accepted main rule and the rule for its selected ledger (oss-static-ledger or oss-commons-ledger). Main keeps direct pushes disabled and the existing native pull-request check, and permits merges by repository writers under the owner-approved all-Labor merge policy. The main merge whitelist is disabled; its dormant ClaudiuSchuster entry stays unchanged. This source policy aligns with infrastructure policy revision e1ff16103f2a47943c191aa26b88f2be1f1d78a6. Release operator identity remains pinned independently. Ledger rules keep their merge whitelist enabled with empty user/team lists, forbidding all merges. They permit ordinary pushes only by ClaudiuSchuster, admit no teams/deploy keys or unprotected file patterns, and apply to administrators. Native protected-ref enforcement prevents force updates and deletion. A missing ledger branch still requires its protection rule before first creation.

The collaborator permission response must bind the allowed login to immutable account ID 2 and the accepted owner role. This is account-bound authority, not a claim of exclusivity to one machine or one PAT. A rename, changed account/role, missing field, widened rule or unknown policy field stops the controller. The rules are fixed accepted source policy; live values never become new pins.

Commons rechecks these rules through its existing fresh gates before intents, provider mutations and terminal records. Static publication and recovery check them with native provenance, including an obligatory callback immediately before each ledger push. Missing callbacks refuse without executing Git push. A later failure leaves an unresolved record rather than claiming a successful close. Read-only PR verification still reads neither branch-protection administration nor collaborator-permission routes. The Commons intent's protection_sha256 remains the exact main-rule digest; selected-ledger enforcement is an additional fresh gate, not an assertion that this digest includes all authorization inputs.

Packet and provider gates

The native controller retains the complete original 52 test commands in their exact order and adds four normal/optimized adapter commands. Integration must add the accepted operating-package tests without removing that subsequence. SAST and every test/build retain fresh network-none containers and readonly inputs. After the post-build native check, the pinned consumer prepares a deterministic packet from readonly exported application data in a separate network-none container with no credential mount. No candidate module is imported. The packet joins the receipt inventory. There is no raw packet CLI, arbitrary artifact override, alternative provider engine or workflow-owned authority.

The final Commons consumer rechecks the receipt, native/main/protection and prepared artifacts, binds every candidate module to its actual Git blob, and requires the original seven migration files, hashes and modes. It reconstructs the live predecessor through the existing complete-module verifier and a local credential-free Git object adapter, including the accepted eight-module predecessor. A missing object, module or schema change refuses. Account, zone, physical D1 UUID, route, schedule, bindings, settings and schema come from fixed protected target policy and the preserved baseline; live drift is not learned as a replacement policy. The existing HTTP acceptance runs before any intent.

Commons plan ends here after a read-only history check. Commons promote calls the unchanged engine through an owned ledger and guarded provider seam. Fresh native/main/protection, HMAC/request/artifact checks, owned intent and preserved provider state precede upload, activation and restore. The pre-upload state must be pristine. Before activation the unchanged engine proves this invocation's annotated staged version; the adapter allows that owned pending version. Restore requires the engine's exact owned deployment pins and preserved candidate state. Foreign stages/deployments/configuration are not adopted or overwritten. Unknown upload/activation/restore replies retain the engine's bounded reconciliation and single-attempt rules; a lost activation reply never authorizes an unowned restore.

Separate append-only promotion ledger

Only oss-commons-ledger carries native Commons records; oss-static-ledger retains its static purpose. No absence of this new branch is inferred from a failed fetch or API error. A successful exact missing-ref observation permits a new root record, followed by one ordinary non-force push. Concurrent unrelated root creation and every non-fast-forward race refuse. A branch that was seen cannot later disappear or be rewritten and restart history.

Each ledger commit adds exactly one new 100644 ledger/<run-attempt>/intent.json or outcome.json, preserves every older blob and has one parent (the first root has none). The 15-digit run and two-digit attempt come only from the authenticated request. Intent binds request, commit, packet digest, complete native record, execution MAC digest, protection digest, every predecessor module Git blob/tree and unchanged engine-plan payload. Outcome binds the complete intent digest and one of promoted, rolled_back, unresolved. Only this invocation's confirmed exact open intent can pass a provider write gate or be closed. A foreign open, closed, stale, replayed or unresolved record cannot be adopted.

Each append attempts one push and performs at most three bounded read-only confirmation attempts. An applied write with a lost reply can be recognized as the exact owned commit and record. Unconfirmed writes block every later action; they are never repeated. The Git transport places no credential in argv, remote URL, helper contents or repository config. Its transient askpass environment is controller-owned, redirects/configured credential helpers/hooks are disabled, and the helper validates the exact HTTPS endpoint and prompt path.

Evidence and gates

test-commons-forgejo.py uses synthetic GET/provider response shapes and actual private local bare Git remotes. test-forgejo-review.py exercises exact PR drift, full IDs/refs, receipt domains, profiles, three controller boundaries and the real triple-artifact checker. Its recorded runtime seam is inert fixture code, not full SAST/runtime acceptance. All keys/provider IDs are synthetic; no real database, dump, remote write or live deployment is involved.

Independent exact-source review, accepted operating integration and its allocator corrections, complete resulting bundles/runtime/pins, actual protected host and service-context proof, credential withdrawal, read-only PR run, fresh protected merged-main native push proof, full fixed policy/SAST sequence, preserved provider plan/backup/restore evidence, complete promotion/HTTP/ledger/rollback evidence and separate static publication acceptance remain operator gates. Source tests grant none of those gates. Identity product dependencies and future schema changes remain separate from this code-only Commons release.