Document Boatstack’s control model and architecture. - #230
Conversation
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Codex automated review
Verdict: patch is incorrect
Confidence: 0.99
The patch publishes an unreachable checked example and makes two incorrect claims about executable program identity and compiler boundaries. Model-level verification is not recommended before merge; these failures are directly established from the production reducer, canonicalizer, and SDK implementation.
| targets: [ | ||
| marked("active-plan", fact("plan", ["active"])), | ||
| ], |
There was a problem hiding this comment.
[P2] Make the checked Flow example target a reachable plan state
Invariant: a published checked Flow must be able to reach its entry target through its declared lifecycle. With all plan.activate prerequisites satisfied and plan=approved, the only declared transition sets the plan to locked; active is not even a valid PlanState. The target therefore remains false and no declared transition can make further progress. This patch introduces the invalid target, while its example checker only lowers raw IR and checks the target ID, so CI still passes. Users copying the canonical example get a blocking Flow. A regression test should compile the example through the production resolver, apply plan.activate from an approved snapshot, and assert the entry becomes marked.
Confidence: 0.99
| Changing the entry name does not change Boatstack's semantics. Changing a | ||
| target, lifecycle step, priority, authority requirement, or producer changes | ||
| executable program semantics and therefore the program identity. |
There was a problem hiding this comment.
[P2] Do not describe entry renames as semantically neutral
Invariant: documentation must identify every change that alters executable program identity. Renaming run to another entry ID changes the canonical document because entry IDs are retained when descriptions and diagnostics are stripped; consequently the program fingerprint and generated projection identity change, invalidating prior prescriptions and artifacts. The new text says the opposite, despite the adjacent concepts guide calling entry names semantic identifiers. The smallest regression oracle is to compile two otherwise identical programs with different entry IDs and assert distinct fingerprints and projection paths, then document that result.
Confidence: 0.99
| `@operatorstack/boatstack` declares complete Control Program IR. The main | ||
| composition boundary is `defineFlow`; it validates and canonicalizes authoring | ||
| data into raw IR but does not execute a Flow. |
There was a problem hiding this comment.
[P3] Keep raw IR lowering distinct from validation and canonicalization
Invariant: the authoring guide must not present unvalidated raw IR as a checked canonical program. defineFlow merely copies arrays, fills defaults, and adds schema fields; for example, invalid IDs or duplicate entries are returned without error and are rejected only by the Go compiler later. This patch newly claims that defineFlow validates and canonicalizes, which can cause callers to treat its output as executable. A regression test should pass an invalid definition through defineFlow, demonstrate that only production compilation rejects it, and bind the documentation wording to that boundary.
Confidence: 0.98
1 participant
Problem
Boatstack's public documentation mixed stable concepts, current implementation details, exact reference facts, generated evidence, and superseded V1 design material. TypeDoc also lacked a durable global landing page, project guides, and checks for both SDK packages.
New structure
Important non-change
This is documentation-only behaviorally. It does not change runtime code, schemas, transitions, authority, compiler semantics, emitted Control Program IR, generated architecture artifacts, or public TypeScript signatures.
Verification
npm cinpm run test:flow-sdknpm run docs:checkpython3 -m unittest discover -s .github/tests -p 'test_*.py' -vpython3 .github/scripts/run_go_tests.pycd boatstack && go test ./...cd boatstack && go test -race ./...cd boatstack && go vet ./...cd boatstack && go build ./...origin/maingit diff --checkDocumentation ownership
docs/concepts/,docs/glossary.mddocs/architecture/authored guidesdocs/product-delivery/docs/*.mdreference pathsdocs/typescript/docs/history/; retired V1 documents are not retained