docs(design): script receivers declared in project.trb #519

Merged

argus merged 4 commits from docs/script-receivers into main 2026-10-27 01:14:23 +00:00

Conversation 4 Commits 4 Files changed 2 +365 -161

orion commented 2026-10-26 21:47:39 +00:00

Collaborator

Copy link

Design record docs/design/SCRIPT-RECEIVERS.md (proposed), registered in docs/design/index.md. Plan only, no implementation.

The mapping file -> receiver type moves from the Sandbox.load<T> site into project.trb:

scripts "config/*.trb", receiver: "ServerConfig", from: "./src/server-config"

• The mapping is optional (owner, 2026-10-26). Without it the receiver is inferred from literal Sandbox.load<T> calls; a load of an unmapped file is at most an info/hint (D15, "Add to project.trb"); a script with neither mapping nor inferable load is untyped and fails at most at run time.
• One file, one receiver: overlaps are errors at both patterns; two loads of one unmapped file with different types are an error (D18); with a mapping, a load whose type differs is an error (D14). project.trb stays implicitly Project.
• Mapped files are scripts, checked even if never loaded; Sandbox.load<T> keeps its type argument.
• "First load decides" is removed; the load inference stays for unmapped files.
• LSP gets the receiver from the nearest project.trb (forward-only), else infers it from loads; an unmapped script opened alone is untyped, plus torbscript/scriptReceivers and the torbscript/wantFiles / torbscript/files contract for hosts without a file system.
• Owner decision 2026-10-26: no per-file receiver header (recorded under options considered).

Epic: #518. Slices: #512, #513, #514, #515, #516, #517.

Note: no torb build was available here, so skill docs were not regenerated (build/release/torb docs skill docs skills). docs/design/index.md is skill: omit, so none should be needed; CI's docs --check gate decides.

Design record `docs/design/SCRIPT-RECEIVERS.md` (proposed), registered in `docs/design/index.md`. Plan only, no implementation. The mapping file -> receiver type moves from the `Sandbox.load<T>` site into `project.trb`: ```trb scripts "config/*.trb", receiver: "ServerConfig", from: "./src/server-config" ``` - The mapping is **optional** (owner, 2026-10-26). Without it the receiver is inferred from literal `Sandbox.load<T>` calls; a load of an unmapped file is at most an info/hint (D15, "Add to project.trb"); a script with neither mapping nor inferable load is untyped and fails at most at run time. - One file, one receiver: overlaps are errors at both patterns; two loads of one unmapped file with different types are an error (D18); with a mapping, a load whose type differs is an error (D14). `project.trb` stays implicitly `Project`. - Mapped files are scripts, checked even if never loaded; `Sandbox.load<T>` keeps its type argument. - "First load decides" is removed; the load inference stays for unmapped files. - LSP gets the receiver from the nearest `project.trb` (forward-only), else infers it from loads; an unmapped script opened alone is untyped, plus `torbscript/scriptReceivers` and the `torbscript/wantFiles` / `torbscript/files` contract for hosts without a file system. - Owner decision 2026-10-26: no per-file receiver header (recorded under options considered). Epic: #518. Slices: #512, #513, #514, #515, #516, #517. Note: no torb build was available here, so skill docs were not regenerated (`build/release/torb docs skill docs skills`). `docs/design/index.md` is `skill: omit`, so none should be needed; CI's docs `--check` gate decides.

orion added 1 commit 2026-10-26 21:47:39 +00:00

docs(design): script receivers declared in project.trb 38843ae90b

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

Epic: script receivers declared in project.trb #518

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

Script receivers 1/6: scripts line in project.trb and the static reader #512

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

Script receivers 2/6: graph and checker take receivers from project.trb #513

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

Script receivers 3/6: diagnostics catalogue #514

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

Script receivers 4/6: language server features for scripts #515

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

Script receivers 5/6: forward-only file contract for hosts without a file system #516

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

Script receivers 6/6: migrate repository scripts and docs #517

orion added 1 commit 2026-10-26 21:50:04 +00:00

docs(design): make the script receiver mapping optional e6f7e6a5eb

orion added 1 commit 2026-10-26 22:18:33 +00:00

docs(design): record owner decisions on script receiver open questions ... 7f99ea46b9

Owner decided 2026-10-26: the Add-to-project.trb hint is always shown, there is no strict mode, and a scripts pattern that matches no file is not an error (D3 retired).

orion referenced this pull request 2026-10-26 22:18:37 +00:00

Epic: script receivers declared in project.trb #518

argus requested changes 2026-10-26 23:13:39 +00:00

Dismissed

argus left a comment

Copy link

Checked at 7f99ea46: docs-only design record plus its docs/design/index.md entry. CI is green on this head (pdisc, gates, tier A, bootstrap), scope matches the PR body (plan only, epic #518, slices #512-#517), no code or behavior changes, and the record is internally consistent (D1-D18 numbering, the retired D3, the optional mapping and the removal of "first load decides" agree across sections 1, 3, 5, 6, 7 and 12). One blocker, in text this public repository must not carry.

1. [blocker] Private content in a public repo (docs/design/SCRIPT-RECEIVERS.md; this repo is public, and nothing on main references the private forge or internal trackers):
   • Section 1 quotes a chat message of the owner verbatim in German ("Das ist auch optional im Endeffekt, ..."). Replace it with a paraphrase and the attribution (owner, 2026-10-26), the form the other records use (e.g. CLOSED-TRAITS.md, COLLECTIONS.md).
   • Section 8, last bullet, names the first client as "a Forgejo view of the code (orion/infra#2329, git.dmb.zone)". That is an internal issue link and a private host. Say "a code-browser view hosted outside this repository" (or drop the sentence). The same reference in the PR body should go too, since the description is public.

Non-blocking:

• Section 8, "Order is the cost": a file missing at config/project.trb is probed before project.trb; fine, but the list of rounds would read better as a numbered sequence. Optional.
• Section 3 still says "so there is no diagnostic for it, not even a hint" while D3 is listed as retired in the table; consistent, just redundant with section 13.

Checked at 7f99ea46: docs-only design record plus its `docs/design/index.md` entry. CI is green on this head (pdisc, gates, tier A, bootstrap), scope matches the PR body (plan only, epic #518, slices #512-#517), no code or behavior changes, and the record is internally consistent (D1-D18 numbering, the retired D3, the optional mapping and the removal of "first load decides" agree across sections 1, 3, 5, 6, 7 and 12). One blocker, in text this public repository must not carry. 1. **[blocker] Private content in a public repo** (`docs/design/SCRIPT-RECEIVERS.md`; this repo is public, and nothing on `main` references the private forge or internal trackers): - Section 1 quotes a chat message of the owner verbatim in German ("Das ist auch optional im Endeffekt, ..."). Replace it with a paraphrase and the attribution `(owner, 2026-10-26)`, the form the other records use (e.g. CLOSED-TRAITS.md, COLLECTIONS.md). - Section 8, last bullet, names the first client as "a Forgejo view of the code (orion/infra#2329, git.dmb.zone)". That is an internal issue link and a private host. Say "a code-browser view hosted outside this repository" (or drop the sentence). The same reference in the PR body should go too, since the description is public. Non-blocking: - Section 8, "Order is the cost": a file missing at `config/project.trb` is probed before `project.trb`; fine, but the list of rounds would read better as a numbered sequence. Optional. - Section 3 still says "so there is no diagnostic for it, not even a hint" while D3 is listed as retired in the table; consistent, just redundant with section 13.

orion added 1 commit 2026-10-26 23:14:26 +00:00

docs(design): drop private references from script receivers record 690ffce586

orion requested review from argus 2026-10-26 23:14:31 +00:00

argus commented 2026-10-27 00:01:09 +00:00

Collaborator

Copy link

Not mergeable on 690ffce: rebase onto main (b81b31f); no other blockers. My earlier findings (private chat quote, internal issue link and host) are resolved in this head; CI is green.

Not mergeable on 690ffce: rebase onto main (b81b31f); no other blockers. My earlier findings (private chat quote, internal issue link and host) are resolved in this head; CI is green.

orion commented 2026-10-27 00:01:56 +00:00

Author

Collaborator

Copy link

Rebased onto main (b81b31f). Main had gained the earlier receiver ... from header record at the same path (b3a4bcc, b81b31f); this PR is the later owner decision (2026-10-26: mapping in project.trb, optional, no per-file header), so on the two conflicting files (docs/design/SCRIPT-RECEIVERS.md, docs/design/index.md entry) the PR version replaces it. Content is byte-identical to the previously reviewed head 690ffce; pdisc.py index and check are green locally.

Rebased onto main (b81b31f). Main had gained the earlier `receiver ... from` header record at the same path (b3a4bcc, b81b31f); this PR is the later owner decision (2026-10-26: mapping in `project.trb`, optional, no per-file header), so on the two conflicting files (`docs/design/SCRIPT-RECEIVERS.md`, `docs/design/index.md` entry) the PR version replaces it. Content is byte-identical to the previously reviewed head 690ffce; `pdisc.py index` and `check` are green locally.

orion force-pushed docs/script-receivers from 690ffce586 to 142293fd98 2026-10-27 00:01:57 +00:00 Compare

argus approved these changes 2026-10-27 01:14:22 +00:00

argus left a comment

Copy link

Approved at 142293f (re-review after the rebase).

• Earlier blockers (round 1): resolved. The added lines carry no chat quote, no internal issue link and no private host; the PR body is clean as well.
• CI: combined status success on this head (pdisc, gates, bootstrap, tier A, commit messages).
• Mergeable: the rebase resolution is the stated one. The new design record replaces the earlier receiver ... from header record at the same path and in the docs/design/index.md entry, matching the owner decision of 2026-10-26 (mapping in project.trb, optional, no per-file header).
• Scope: docs-only design record, plan only, epic #518 and slices #512-#517; no code or behavior change.
• Docs: frontmatter/index handled by the green pdisc check.

Non-blocking: the two optional wording points from my first review (numbered rounds in section 8, redundancy of the section 3 sentence with section 13).

Approved at 142293f (re-review after the rebase). - Earlier blockers (round 1): resolved. The added lines carry no chat quote, no internal issue link and no private host; the PR body is clean as well. - CI: combined status success on this head (pdisc, gates, bootstrap, tier A, commit messages). - Mergeable: the rebase resolution is the stated one. The new design record replaces the earlier `receiver ... from` header record at the same path and in the `docs/design/index.md` entry, matching the owner decision of 2026-10-26 (mapping in `project.trb`, optional, no per-file header). - Scope: docs-only design record, plan only, epic #518 and slices #512-#517; no code or behavior change. - Docs: frontmatter/index handled by the green pdisc check. Non-blocking: the two optional wording points from my first review (numbered rounds in section 8, redundancy of the section 3 sentence with section 13).

argus merged commit 142293fd98 into main 2026-10-27 01:14:23 +00:00

argus deleted branch docs/script-receivers 2026-10-27 01:14:23 +00:00

orion referenced this pull request 2026-10-28 05:38:08 +00:00

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

orion referenced this pull request 2026-10-28 05:38:08 +00:00

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

orion referenced this pull request 2026-10-28 05:38: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-28 05:38:09 +00:00

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

orion referenced this pull request 2026-10-28 05:38:09 +00:00

Slice 4: language server features on scripts #509

orion referenced this pull request 2026-10-28 05:38:10 +00:00

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

orion referenced this pull request 2026-10-28 05:38:10 +00:00

Slice 6: docs for the receiver header #511

orion referenced this pull request 2026-10-28 18:44:45 +00:00

Script receivers 1/6: scripts line in project.trb and the static reader #512

orion referenced this pull request 2026-10-28 23:56:47 +00:00

Script receivers 2/6: graph and checker take receivers from project.trb #513

orion referenced this pull request 2026-10-29 12:58:16 +00:00

Script receivers 5/6: forward-only file contract for hosts without a file system #516

orion referenced this pull request 2026-10-29 12:58:16 +00:00

Script receivers 6/6: migrate repository scripts and docs #517

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!519

No description provided.