Skip to content

docs: deploy procedure follows the supervisor-start cutover order; tooling tied to steps (#78) - #79

Merged
anuzzolilli-oss merged 3 commits into
masterfrom
2026-11-16_deploy-procedure-doc-gaps
Nov 18, 2026
Merged

anuzzolilli-oss merged 3 commits into
masterfrom
2026-11-16_deploy-procedure-doc-gaps

Conversation

@anuzzolilli-oss

@anuzzolilli-oss anuzzolilli-oss commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Scope

Closes #78. Follow-up to #74 / #77. Docs only: four files, no source, test, config or env change.

  • docs/cindy-project.md + docs/cindy-project.zh-CN.md (first commit only)
  • reference/cindy-project.md + reference/cindy-project.zh-CN.md

Three commits: 4f94dad27 covers section B of #78, 22d4580ab covers section A, and 46be1dfef corrects four statements in the section A text after an independent read-only check against the scripts (status-file fields in step 9, the 90-second wait in step 6, the candidate proxy in step 8, one step reference in the tooling paragraph).

Owner decisions (2026-11-16)

Section A of #78 was an open owner decision. The owner answered three questions in chat on 2026-11-16:

Question Answer
Which cutover order is the sanctioned one The order the kept Deploy-Master.ps1 implements (supervisor starts the new release)
End state when a rollback itself fails Stay inhibited and escalate to the owner
Point step 5 at the receipt instead of repeating the release identity Yes

Reading confirmed by the owner (2026-11-17). Under the script order the supervisor also starts the restored release, which needs the hold lifted. "Stay inhibited" therefore means: lift the hold to start the previous release, check it, and if it fails put the hold back (inhibit set, task disabled, supervisor stopped), leave any proxy process as it is, attempt nothing further and report.

What changed for section A (22d4580ab, 46be1dfef)

Step Change
4 The hold is given in the script's order: inhibit, disable the scheduled task, stop the supervisor; the old proxy keeps serving. Says step 6 lifts the hold (was "step 9 removes it")
5 No longer repeats the current release identity. New values come from the candidate (build-info.json commit, the release directory, the version from the step 1 test); the release being replaced is in the launcher defaults and in named receipt fields
6 Cut over only when idle (stand down, not "drain"); stop only the old proxy; lift the hold; the supervisor starts the new release, no manual start. The fail-closed list and "rechecked every PollSeconds" are now true at this point because supervision is running. States the success test and the rollback trigger
7 Checks run with supervision running. Says the kept script checks only health identity and process counts before rewriting receipts, so a failure here is rolled back with receipts already rewritten
8 Rollback under a new hold; launcher only or launcher plus receipts depending on where it failed; lift the hold so the supervisor starts the previous release; re-check. Defines the failed-rollback end state
9 Now a confirmation that maintenance has ended (inhibit absent, task enabled, one supervisor, status reports the live release), with the failed rollback as the one exception
10 Adds what to report after a failed rollback
Tooling paragraph Maps Deploy-Master.ps1 to steps 2, 4–5, 6 and 8, and to the receipt rewrite that step 7 describes
Closing paragraph No longer says the script and the steps disagree. Records the decision, and says where the kept scripts still depart from the steps: both re-enable supervision after a rollback without requiring the previous release to be healthy, so the hold has to be applied by hand

The third open item in #78 section A (how a hand-started proxy comes under supervision) no longer applies: nothing is started by hand under this order. The closing paragraph says so.

The kept scripts were not edited. Bringing them in line with the failed-rollback end state would be separate work on the owner's say-so.

What changed for section B (4f94dad27)

# Gap Fix
1 Tooling not tied to steps Step 1 names iso-test.mjs and fold-test.mjs; the tooling paragraph maps each kept file to its step
2 Tooling path and "initial repair" label Cites the receipt's masterBackupRoot (currently before-master-20261114-214204), notes the byte-identical copy in -191918, and says each backup's rollback script targets its own cutover
3 Build ordering and file locations Step 1 points at the recipe in step 3; step 3 says the wrapper and build script are not in the repository, where to copy the wrapper, how to run the build, and what the candidate folder holds
4 Step 5 contradicted itself Change only the release-identifying defaults (ProxyPath, ExpectedCommit, and ExpectedVersion when the version changes); notes the kept script edits exactly two lines and does not cover a version change
5 Two rollbacks described as one; step 10 undefined after rollback Step 8 restores receipts only if they were already rewritten; step 10 has a success path and a rollback path; Rollback-MasterDeploy.ps1 is described as the undo of one completed cutover
6 Rollback-TunedLiveProxy.ps1 misdescribed Described as the deeper rollback to the pre-tuning 2026-11-07 backup (config and launcher), not to the previous release
7 Step 9 en/zh drift Chinese aligned to the English
8 Snapshot history skipped a build 4b6687bc-live added to the superseded history with its cutover backup

Evidence basis

Read on 2026-11-16 from the machine, read-only:

Claim Source
Hold order: inhibit, task disabled, supervisor stopped, old proxy still healthy, launcher written Deploy-Master.ps1 sections 2–3
Idle check (no established client connections, otherwise stand down) Deploy-Master.ps1 preflight and section 4
Cut order and success test (expected version and commit from the single listener's PID, one proxy, one supervisor, 90 s) Deploy-Master.ps1 section 4
Supervisor starts a proxy only when no matching proxy exists and nothing listens on the port; fail-closed cases; recheck every PollSeconds header and decision function of Start-BillionContextProxy.ps1
The scheduled task has a repeating trigger supervision-receipt.json task
Receipts rewritten and rollback script written only after the health check, before any functional check Deploy-Master.ps1 section 5
Failure branch re-enables supervision and only reports whether the old release is healthy Deploy-Master.ps1 catch block
Rollback-MasterDeploy.ps1 restores the launcher and both receipts, re-enables supervision, checks nothing the script in before-master-20261114-214204
One fixed version in the script's health check Deploy-Master.ps1 HealthyAs
Receipt fields naming the release tuned-deployment.json (releaseRoot, build), supervision-receipt.json (masterDeploy.proxyRelease)
The isolated test checks the reported version and commit iso-test.mjs
Section B sources unchanged from the first commit: directory listings, both receipts, the three scripts, build.mjs, the test script headers

No credentials or config contents appear; paths are written with %APPDATA%.

Verification

  • node tools/check-architecture-docs.mjs — all green
  • git diff --check — clean; CRLF line endings preserved, no bare LF
  • en/zh parity: every changed sentence has its counterpart, same step count (10/10)
  • Step cross-references re-checked after the renumbering of responsibilities
  • No doc added or moved, so the indexes need no edit

Nothing was executed against the live proxy and the live port was not touched. No deployment claim is made.

Noted, not changed

The docs/ snapshot pages and the reference/ pages contain a literal user-profile path in a few places. They are already on master and outside #78, so they are left for the owner to decide.

Assisted-by: Cindy (https://cindy.app)

…fers (#78)

Follow-up to #74/#77. Fixes the parts of the deploy procedure that do not
depend on the open cutover-order decision recorded in #78:

- name the kept iso-test/fold-test checks in step 1 and point it at the
  build recipe in step 3
- say where live-entry.ts and build.mjs live and how the build is run
- resolve step 5's contradiction about which launcher defaults change
- separate the in-cutover rollback from Rollback-MasterDeploy.ps1 and
  define step 10 on the rollback path
- cite the receipt's masterBackupRoot for the tooling, and describe
  Rollback-TunedLiveProxy.ps1 as the deeper pre-tuning rollback
- record 4b6687b-live in the superseded history
- remove the step 9 en/zh drift

Steps 6-9 are not rewritten. The page now states what Deploy-Master.ps1
does at cutover and that it differs from those steps.

Assisted-by: Cindy (https://cindy.app)
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

📦 Built Package Artifact

Branch: 2026-11-16_deploy-procedure-doc-gaps (46be1df)

Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr79.tgz
npm install -g package

Install instructions are refreshed on each push.

Owner decision of 2026-11-16 on issue #78 section A:

- The sanctioned cutover order is the one the kept Deploy-Master.ps1
  implements: hold supervision, edit the launcher, stop the old proxy when
  idle, lift the hold and let the supervisor start the new release, check
  with supervision running. Steps 4 and 6-10 are rewritten to that order
  in English and Chinese.
- A failed rollback ends with the hold back in place and a report to the
  owner. The page says the kept scripts re-enable supervision regardless,
  so the hold has to be applied by hand after them.
- Step 5 no longer repeats the current release identity; it names the
  candidate and receipt fields that carry it.

Docs only. Nothing was run against the live proxy.

Assisted-by: Cindy (https://cindy.app)
@anuzzolilli-oss anuzzolilli-oss changed the title docs: tie deploy tooling to steps and state where the kept script differs (#78) docs: deploy procedure follows the supervisor-start cutover order; tooling tied to steps (#78) Nov 17, 2026
- Step 9: supervisor-status.json has no version or commit field; verify
  the monitored child and healthMatch there and the version and commit
  from the health endpoint. The restored proxy may be adopted, not started.
- Step 6: the kept script waits 90 s for health only, then checks the
  process counts once.
- Step 8: a candidate proxy exists only if the cutover got that far.
- Tooling paragraph: the script's receipt rewrite is the one step 7
  describes, not step 10's finalization.

Assisted-by: Cindy (https://cindy.app)
@anuzzolilli-oss
anuzzolilli-oss marked this pull request as ready for review November 17, 2026 23:54
@kilo-code-bot

kilo-code-bot Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

(ai: openai/gpt-6-astra)

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Light documentation review at 46be1dfef62f649236090c21f35d08066fc00cb5: no CRITICAL or WARNING findings. Reviewed the deployment history and revised build, cutover, rollback, and supervision instructions.

Files Reviewed (2 files)
  • docs/cindy-project.md
  • reference/cindy-project.md

Both Chinese counterparts are present; translation contents were excluded under REVIEW.md. The machine-local deployment scripts and receipts were unavailable for independent verification. No code or tests were executed.


Reviewed by gpt-6-astra · Input: 42 · Output: 4.2K · Cached: 877.2K

Review guidance: REVIEW.md from base branch master

@anuzzolilli-oss
anuzzolilli-oss merged commit 27a4f23 into master Nov 18, 2026
42 checks passed
@anuzzolilli-oss
anuzzolilli-oss deleted the 2026-11-16_deploy-procedure-doc-gaps branch November 18, 2026 03:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: deploy procedure and kept tooling disagree at cutover; remaining gaps after #77

1 participant