Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
551 changes: 274 additions & 277 deletions .github/workflows/release.yml

Large diffs are not rendered by default.

11 changes: 7 additions & 4 deletions docs/collaboration-runtime-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: "Knowgrph Collaboration Runtime Contract"
doc_type: "Runtime Contract"
status: "active"
contract_version: 29
contract_version: 30
frontmatter_contract: "required"
ci_command_timeout_ms: 300000
ci_command_timeout_overrides:
Expand Down Expand Up @@ -208,10 +208,13 @@ The automatic gate passes only with at least two distinct authenticated device p
- CI never deploys.
- Only a workflow listed in `deployment.allowed_workflows` may contain deployment commands.
- The allowed workflow must use the trigger declared by `deployment.required_trigger`, restricted to `deployment.required_branch`.
- A protected green merge to `main` proves Dev integration only. `turn:end` must converge canonical localhost `main` to that exact fetched revision and emit an `agentic-local-review-candidate/v1` receipt. The workflow starts only through explicit candidate preparation on protected `main`, validates that receipt, builds once, and loads the neutral lifecycle contract from the exact pinned Agentic Canvas OS checkout. It persists joined Integration, Runtime Review, and Candidate receipts binding the collaboration tuple, source and dependency closure, execution-policy revision, target, artifact, immutable manifest, and rollback identity before pausing at the protected `production` environment.
- A protected green merge to `main` proves Dev integration only. `turn:end` must converge canonical localhost `main` to that exact fetched revision and emit an `agentic-local-review-candidate/v1` receipt. Before dispatch, the repository-owned evidence producer emits `knowgrph-production-release-evidence/v1`, with exactly 19 preservation inventory entries, 19 retained observations, their content digests, and the last-known-good Pages deployment, publication-mirror revision, and D1 state contract. Candidate creation accepts it only through the lifecycle CLI's `--release-evidence <path>` input. Missing entries, ownership/fence/byte drift, ambiguous dispositions, or predecessor drift blocks candidate preparation; preservation evidence creates no mutation or Production authority.
- The workflow starts only through explicit candidate preparation on protected `main`, revalidates the exact pre-dispatch evidence bytes and local-review receipt, builds once, and loads the neutral lifecycle contract from the exact pinned Agentic Canvas OS checkout. It persists joined Integration, Runtime Review, and Candidate receipts binding the collaboration tuple, source and dependency closure, execution-policy revision, target, artifact, immutable manifest, and rollback identity before pausing at the protected `production` environment.
- Forward deployment requires exactly one authenticated GitHub `User` approval for the `production` environment and the prepared neutral candidate digest. The controller records and immediately consumes the single-candidate Human Authorization receipt before the first forward mutation; missing, bot, ambiguous, expired, replayed, or candidate-drifted approval fails closed. GitHub workflow concurrency serializes the target, while the neutral controller contract coalesces an identical dispatch and fences a competing candidate.
- The workflow deploys the already-built bytes, records Live Verification only after smoke, browser-fidelity, and returning-user service-worker convergence, publishes the verified mirror, then records Publication. The complete six-receipt chain is retained as a run-scoped artifact. Any new `main`, source or runtime tree, dependency closure, policy, target, artifact, manifest, receipt link, or candidate digest invalidates authorization; a rebuild is a new candidate.
- The protected workflow owns the complete Production sequence; no local checkout owns an equivalent path. It deploys the already-built Pages bytes and emits `agentic-deployment-receipt/v1`, performs bounded direct D1 reconciliation/readback and emits `agentic-state-reconciliation-receipt/v1`, then verifies the immutable deployment origin, stable Pages route, and custom domains as separate transports. Exact identity, probe, browser, service-worker, and readiness-marker-byte parity are required for `agentic-live-verification-receipt/v2`.
- Only validated Live Verification v2 opens mirror publication. The workflow publishes the exact generated mirror, emits `agentic-publication-receipt/v2`, and persists the joined chain in `agentic-collaborative-release-lifecycle/v2` with `completion: production-complete`. Loose receipts, legacy lifecycle v1 observations, successful URLs, or a workflow status cannot replace the closed v2 carrier. Any new `main`, source or runtime tree, dependency closure, policy, target, artifact, manifest, receipt link, candidate digest, transport identity, or rebuild invalidates the frontier.
- Schema-map reconciliation must use the clean protected Knowgrph source corpus and the exact captured guideline-mirror revision. Dirty or untracked documents in any local checkout are never implicit publication input.
- Before release, the controller idempotently disables Cloudflare Pages Git-triggered production and preview deployments and verifies convergence. It fails closed if ownership cannot converge; verified Direct Upload from `Production Release` is the sole deployment owner.
- The GitHub `production` environment must require an authenticated human reviewer, disable administrator bypass, and restrict deployment to protected branches; credentials remain environment-scoped and least-privilege.
- Prod repositories and Cloudflare resources remain untouched by pull-request CI, local developer commands, pushes, schedules, and repository dispatches. Automated rollback may restore only the captured immutable last-known-good deployment after a failed authorized forward release.
- Prod repositories and Cloudflare resources remain untouched by pull-request CI, local developer commands, pushes, schedules, and repository dispatches. Direct local Pages deployment, D1 reconciliation, production probing, mirror publication, or rollback is forbidden even when credentials are locally available.
- Before mutation, the workflow binds the exact last-known-good Pages deployment, mirror revision, and D1 state. A failed authorized forward release stops subsequent mutation, restores only that Pages target, records an explicit D1 state disposition, requires restoration probes, leaves the prior mirror unchanged, and emits `agentic-rollback-receipt/v1`. Only the joined Deployment v1 → Rollback v1 branch may close the v2 carrier as `rolled-back`; partial restore, ambiguous state, mirror movement, or publication on that branch fails closed.
77 changes: 56 additions & 21 deletions docs/documents/knowgrph-cloudflare-document.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
title: "Reference implementation: Knowgrph Cloud Platform Product and Technical Specification"
id: "md:knowgrph-cloudflare-document"
doc_type: "Product and Technical Specification"
version: "2.0.0"
date: "2026-07-30"
version: "2.1.0"
date: "2026-08-13"
lang: "en-US"
owner: "docs.cloudflare-platform-boundary"
local_rung: "spec-complete"
Expand Down Expand Up @@ -41,6 +41,12 @@ Source presence, a `wrangler.toml` route, an old preview URL, an earlier deploym
historical check result must not promote either rung. This document grants no deployment, remote
mutation, DNS mutation, paid-provider, or secret-management authority.

The ACOS RELEASE-WORKFLOW v4 adapter assigns Pages Direct Upload, release-scoped direct D1
reconciliation/readback, immutable/stable/custom production probes, mirror publication, and
rollback exclusively to `.github/workflows/release.yml` after exact-candidate protected-environment
authorization. A local checkout, direct Wrangler command, deploy-capable package script, credential,
or green Dev check cannot perform or stand in for that protected sequence.

### Canonical ownership and reading order

This document deliberately contains no duplicate Invocation Register.
Expand Down Expand Up @@ -223,42 +229,71 @@ the Pages release boundary.
### Workflow: Protected Pages promotion

**Trigger**: a human supplies an exact protected `main` SHA and exact localhost-review candidate to
the manually dispatched release workflow.
the manually dispatched release workflow, together with the digest of repository-owned
pre-dispatch evidence.

**Happy path**:

1. The verify job checks out exact source/dependency revisions, materializes the review artifact,
runs integration, and builds the Pages candidate once.
1. Before dispatch, the repository-owned evidence producer emits
`knowgrph-production-release-evidence/v1`, content-addressing all 19 preserved lanes and the exact
last-known-good Pages deployment, publication-mirror revision, and D1 state contract. The verify
job revalidates those exact bytes, checks out exact
source/dependency revisions, materializes the review artifact, runs integration, and builds the
Pages candidate once.
2. While the protected `production` deployment is pending, `npm run production:authorize`
verifies the clean canonical checkouts, presents the candidate-bound terminal challenge,
and submits the environment approval with its exact evidence comment. A separate browser
approval is invalid.
3. The deploy job captures the previous Pages deployment, deploys the verified candidate,
reconciles canonical documentation into D1, and runs live/browser/service-worker checks.
4. Only after verification does the workflow publish the generated mirror and completion receipts.
3. The deploy job revalidates the last-known-good evidence, deploys the verified candidate, and
emits `agentic-deployment-receipt/v1`.
4. The same protected job reconciles canonical documents directly into D1, performs authoritative
readback with count/content/path-hash parity, and emits
`agentic-state-reconciliation-receipt/v1`.
5. It probes the immutable deployment origin, the stable Pages route, and the custom domains as
distinct transports. Exact identity, marker-byte parity, browser fidelity, and returning-user
service-worker convergence are required for `agentic-live-verification-receipt/v2`.
6. Only live v2 may open mirror publication. The workflow then emits
`agentic-publication-receipt/v2` and closes
`agentic-collaborative-release-lifecycle/v2` as `production-complete`.

**Alternate path**: if the generated mirror already represents the candidate, the workflow records
that state without creating an unnecessary mirror commit.

**Error path**: only after a successful Pages deploy followed by failure, the workflow checks out
the captured prior source, resolves its documentation dependency, restores the prior Pages
deployment, reconciles prior documentation into D1, and reruns smoke checks. It does not revert a
new persistent-mirror commit; failure after mirror publication can therefore require manual mirror
reconciliation.

**Postconditions**: either the exact candidate has delivery receipts and an identifiable prior
Pages state, or the rollback path has attempted restoration. No Worker or DNS publication is
implied.
**Error path**: only after this controller proves the exact Pages mutation, including a provider
commit followed by a nonzero deploy process exit, the workflow stops forward mutation, restores the
content-bound last-known-good Pages target, records the D1 disposition separately, reruns restoration
probes, leaves the last-known-good mirror unchanged, and emits `agentic-rollback-receipt/v1`. A
terminal D1 restore requires the same substantive direct-readback identity and zero graph snapshots;
the monotonic document revision counter is excluded because replay advances it. Pages restoration
does not assert D1 restoration. Partial restore, ambiguous state, mirror movement, or a malformed
predecessor chain fails closed and cannot close the carrier as `rolled-back`.

**Postconditions**: either the exact Deployment → State → Live v2 → Publication v2 chain closes the
v2 terminal carrier, or the exact Deployment → Rollback branch closes it after verified
restoration. An attempted restoration, loose receipt file, URL, D1 count, or mirror commit is not a
terminal claim. No Worker or DNS publication is implied.

The run-scoped terminal files are `deployment-receipt.json`,
`state-reconciliation-receipt.json`, `live-verification-receipt-v2.json`,
`publication-receipt-v2.json`, and `collaborative-release-lifecycle-v2.json`. The protected job also
retains the pre-mutation `previous-pages-project-api.json`,
`previous-pages-deployment-api.json`, `previous-pages-runtime-readiness.json`, and
`previous-d1-state-evidence.json`, deployment/D1 adapter output, and immutable-origin,
browser-fidelity, service-worker, and combined transport evidence. Only the validated terminal
carrier assigns completion semantics to those files. The Pages deployment evidence identifies
adapter `cloudflare-pages/wrangler-output-v1`; authoritative direct D1 evidence identifies adapter
`cloudflare-wrangler-d1-direct-readback/v1`.

### Data flow: Pages candidate and documentation reconciliation

| Stage | Component | Input | Output | Persistence | Error handling |
|---|---|---|---|---|---|
| Ingest | release verifier | exact source/dependency/review identities | validated candidate context | run-scoped artifacts | fail closed on mismatch |
| Ingest | release verifier | exact source/dependency/review identities + content-addressed 19-lane and last-known-good evidence | validated candidate context | run-scoped artifacts | fail closed on mismatch |
| Transform | Pages builder | source and pinned docs | static bytes + Functions + manifests | candidate artifact | non-zero build/parity result |
| Store | candidate publisher | immutable artifact | Pages deployment | configured delivery platform | retain prior deployment id |
| Serve | live verifiers | candidate/live origins | route, browser, and service-worker results | lifecycle receipts | retry within workflow bounds, then fail |
| Reconcile | docs seeder | pinned canonical docs | D1 documentation projection | configured D1 | rollback reseeds prior docs; no general D1 snapshot claim |
| Deploy | protected Pages adapter | immutable artifact | deployment id + immutable origin | configured delivery platform | bind the prior deployment before mutation |
| Reconcile | direct D1 adapter | pinned canonical docs + state contract | D1 projection + authoritative parity | configured D1 | explicit state disposition; no Pages-as-D1 rollback claim |
| Verify | transport adapters | immutable origin + stable Pages route + custom domains | separate probe/browser/service-worker evidence | lifecycle receipts | no transport substitution; fail closed on disagreement |
| Publish | protected mirror adapter | live-verification v2 predecessor | exact mirror revision + publication v2 | generated mirror repository | forbidden before live v2 |

### Data flow: Storage trust boundaries

Expand Down
Loading
Loading