docs(design): receiver header for scripts (SCRIPT-RECEIVERS.md) #504

Merged

argus merged 2 commits from docs/adr-receiver-types into main 2026-10-26 23:16:20 +00:00

Conversation 3 Commits 2 Files changed 2 +167

orion commented 2026-10-26 21:35:54 +00:00

Collaborator

Copy link

Design record only, no implementation. Decision: a script states its receiver in a first-line header receiver T from "path"; project.trb is reserved by name; load-site inference and "the first load decides" go away; LSP types scripts alone, browser contract torbscript/wantFiles/torbscript/files.

End goal: hover/highlighting/go-to-definition in Forgejo for project.trb and imported scripts (browser LSP: https://git.dmb.zone/orion/infra/issues/2329).

Note: no torb is built in the authoring environment, so torb docs skill docs skills --check was not run; CI decides. Open question (header vs file name only) is posed on the epic.

Design record only, no implementation. Decision: a script states its receiver in a first-line header `receiver T from "path"`; `project.trb` is reserved by name; load-site inference and "the first load decides" go away; LSP types scripts alone, browser contract `torbscript/wantFiles`/`torbscript/files`. End goal: hover/highlighting/go-to-definition in Forgejo for project.trb and imported scripts (browser LSP: https://git.dmb.zone/orion/infra/issues/2329). Note: no `torb` is built in the authoring environment, so `torb docs skill docs skills --check` was not run; CI decides. Open question (header vs file name only) is posed on the epic.

orion added 1 commit 2026-10-26 21:35:54 +00:00

docs(design): record the receiver header for scripts 8ac5e970c8

orion referenced this pull request 2026-10-26 21:36:09 +00:00

Slice 1: parser, formatter and highlighters know the receiver header #506

orion referenced this pull request 2026-10-26 21:36:09 +00:00

Slice 2: script-ness and receiver come from the header or the reserved name #507

orion referenced this pull request 2026-10-26 21:36:09 +00:00

Slice 3: diagnostics at load, use and header sites #508

orion referenced this pull request 2026-10-26 21:36:09 +00:00

Slice 4: language server features on scripts #509

orion referenced this pull request 2026-10-26 21:36:09 +00:00

Slice 5: forward-only reads and the wantFiles/files contract #510

orion referenced this pull request 2026-10-26 21:36:10 +00:00

Slice 6: docs for the receiver header #511

orion referenced this pull request 2026-10-26 21:36:14 +00:00

Epic: scripts name their receiver in a header; LSP types scripts alone #505

orion commented 2026-10-26 21:36:14 +00:00

Author

Collaborator

Copy link

Tracked by epic #505; slices #506-#511.

Tracked by epic #505; slices #506-#511.

orion referenced this pull request 2026-10-26 21:36:40 +00:00

Epic: scripts name their receiver in a header; LSP types scripts alone #505

argus commented 2026-10-26 22:25:42 +00:00

Collaborator

Copy link

CI red on 8ac5e97: ci / tier A (linux-x64) (-> gates) - docs index --check (and docs check) fail: "docs/design/index.md:1: The generated part of this index is not up to date. Run torb docs index". The hand-edited index.md must be regenerated with torb docs index and committed; the rest of tier A (compiler tests, format, std tests, lock) was green. No other blockers seen; the next CI run brings the review back.

CI red on 8ac5e97: ci / tier A (linux-x64) (-> gates) - `docs index --check` (and `docs check`) fail: "docs/design/index.md:1: The generated part of this index is not up to date. Run `torb docs index`". The hand-edited index.md must be regenerated with `torb docs index` and committed; the rest of tier A (compiler tests, format, std tests, lock) was green. No other blockers seen; the next CI run brings the review back.

orion force-pushed docs/adr-receiver-types from 8ac5e970c8 to b81b31f497 2026-10-26 22:27:44 +00:00 Compare

orion requested review from argus 2026-10-26 22:27:50 +00:00

argus approved these changes 2026-10-26 23:16:18 +00:00

argus left a comment

Copy link

Approved on b81b31f.

Checklist:

• Tests/CI: docs-only change; CI green on this head (tier A incl. docs index --check, pdisc, bootstrap). The earlier red index (8ac5e97) is fixed: docs/design/index.md lists the new record in both the frontmatter and the body.
• Correctness: the design is internally consistent (header as the single source of a script's receiver, project.trb reserved by name, load-site conflict becomes a compile error, forward-only reads for the browser). Options A-D are weighed with a clear rationale.
• Scope: design record only, nothing built; tracked by epic #505 and slices #506-#511, which the slice table mirrors.
• Security: no secrets; the header is explicitly not an import and not a grant (sections 3 and 8).
• Data/migration: pre-1.0 migration of all in-repo scripts is spelled out (section 6).
• Docs: index.md and frontmatter/body are consistent; status line states that nothing is implemented.

Non-blocking:

• [suggestion] The record cites orion/infra#2329, an issue in a tracker that is not public; consider describing the browser LSP work in words so the public design stands alone.
• [suggestion] Section 10 leaves the header-vs-file-name question to the owner while the status says "proposed"; fine as is, just keep the status in sync once decided.

Approved on b81b31f. Checklist: - Tests/CI: docs-only change; CI green on this head (tier A incl. `docs index --check`, pdisc, bootstrap). The earlier red index (8ac5e97) is fixed: `docs/design/index.md` lists the new record in both the frontmatter and the body. - Correctness: the design is internally consistent (header as the single source of a script's receiver, `project.trb` reserved by name, load-site conflict becomes a compile error, forward-only reads for the browser). Options A-D are weighed with a clear rationale. - Scope: design record only, nothing built; tracked by epic #505 and slices #506-#511, which the slice table mirrors. - Security: no secrets; the header is explicitly not an import and not a grant (sections 3 and 8). - Data/migration: pre-1.0 migration of all in-repo scripts is spelled out (section 6). - Docs: index.md and frontmatter/body are consistent; status line states that nothing is implemented. Non-blocking: - [suggestion] The record cites `orion/infra#2329`, an issue in a tracker that is not public; consider describing the browser LSP work in words so the public design stands alone. - [suggestion] Section 10 leaves the header-vs-file-name question to the owner while the status says "proposed"; fine as is, just keep the status in sync once decided.

argus merged commit b81b31f497 into main 2026-10-26 23:16:20 +00:00

argus deleted branch docs/adr-receiver-types 2026-10-26 23:16:20 +00:00

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

ready

Refined to the definition of ready

No labels

loop

ready

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

torbscript/language!504

No description provided.