Skip to content

Commit e286fed

Browse files
authored
🔒 Report the authored form on the invocation the engine issued (#569)
* 🔒 Report the authored form on the invocation the engine issued A component whose two spellings do different things learns which one it is by asking `Component.hasContent()`. That is a composable chain: its outermost handler answers first, so middleware installed anywhere outside the invocation answers ahead of the engine's own account of the element, and a handler that answers per call can report one form to a caller checking and the other to the component. `<File>` chooses between reading a file and writing over it with that answer, so a self-closing `<File path="notes.md" />` could be made to render an empty string over the file the document wrote a read for — in an ordinary authored document, with no generated source anywhere near it. The authored form is a fact about the invocation rather than about the surroundings it runs in, so it now travels on the invocation. `ComponentInvocation` gains `hasContent(): boolean`: synchronous, immutable, projecting nothing, suspending on nothing, and spending no durable identity. The boolean is recorded in the private issuance state when canonical execution mints the invocation and read straight off it, so there is no context, map, registry entry or exported lookup beside it — the only way to the fact is an object the engine handed over. A component evaluated through a separately loaded copy therefore calls what it received rather than a helper of its own copy. Implementing the method does not make an object an invocation. Durable identity stays the private field a claimant recognizes, so a structural look-alike answering `hasContent()` still claims nothing. `<File>` and workflow's `<Dir>` take their invocation and select their form only from it. Both are irreversible in one direction, which is what separates them from the components that merely render differently. There is no fallback: a call arriving without a genuine invocation refuses before `cwd()`, before its children, and therefore before any provider. Nothing else changes — the same Files provider, the same content projection, the same lexical cwd, the same failures and durable effects — and without hostile middleware the rendered output, bindings and provider calls are what they were. The contextual operation stays exported and composable. It remains the right answer for a component deciding how to render; it is no longer the answer for one deciding what to do. Verified with the four boundary suites (10 tests, 104 steps) and `deno task test --changed`, which selected 199 files and passed 494 tests in 21m28s. Reverting `<File>` to the contextual answer fails all four FL27/FL28 cases, including both exact toggles. Refs #369 * 📄 Say what the contextual content answer does and does not guarantee Two sentences claimed more than the code does. The language specification said a component whose two forms select different effects reads the authored form from its invocation. That describes `<File>` and `<Dir>` and nothing else: every other component reads the contextual operation, and saying otherwise reads as a rule the reader can rely on. It now states the boundary as it is — only the invocation's own `hasContent()` is authoritative, those two read it, and a component reading the contextual operation has no authored-form guarantee at all. The architecture said moving the remaining eleven consumers to the invocation is a follow-up, and that until it happens they are held to the weaker rule. A contract describes what is built, not what is planned. It now records only the present terms: those eleven read the contextual answer, so middleware may alter the effect, the guard or the retained data each of their branches decides, and this invocation boundary makes no stronger guarantee for them. Which consumer decides what is already enumerated beside it; the sequencing belongs in the handback. Documentation only: no source, test, assertion or test identifier changes. Refs #369 --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent 1b3126a commit e286fed

12 files changed

Lines changed: 731 additions & 29 deletions

File tree

‎architecture.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2561,6 +2561,38 @@ registration leaves a claimant that answers for nothing. The claimant exists as
25612561
the argument of that one call: not published, not named, not reachable from a
25622562
document, and not derivable from anything a handler holds.
25632563

2564+
**The invocation carries one readable fact, for the same reason.** How the
2565+
element was written — `<C />` against `<C>…</C>` and `<C></C>` — is a property
2566+
of the invocation rather than of the surroundings it runs in, and a component
2567+
whose two spellings select different *effects* is choosing with it. The
2568+
contextual `Component.hasContent()` answers the same question through the
2569+
composable chain, where the outermost handler answers first and may answer
2570+
differently on each call; a caller that checks it and then invokes something
2571+
which asks again has verified nothing, because the two are separate dispatches.
2572+
So `ComponentInvocation` reports the authored form directly: synchronous,
2573+
immutable, projecting nothing and spending no identity, held as owner-kept state
2574+
inside canonical core and reachable only through the object the engine minted.
2575+
There is no context, map, registry entry or exported lookup beside it, and
2576+
implementing the method does not make an object an invocation — durable identity
2577+
remains the private field a claimant recognizes.
2578+
2579+
Core's `<File>` and the workflow package's `<Dir>` select their effect from that
2580+
fact and have no fallback to the contextual answer. Both are irreversible in one
2581+
direction: a `<File />` reported as content-bearing renders an empty string over
2582+
the file the document wrote a read for.
2583+
2584+
The contextual operation stays exported and composable, and every other
2585+
component still reads it. That is not a statement that the remaining readers are
2586+
safe. Eleven of them branch on it, and the branch decides more than how to
2587+
render: `<Issue>` selects a read against an external upsert, `<Repository>`,
2588+
`<Worktree>`, `<TempDir>` and `<IssueTracker>` decide whether a context or a
2589+
working directory is installed for their descendants at all, `<Git.Add>`,
2590+
`<Git.Push>`, `<Git.Switch>` and `<Json>` turn a content-bearing invocation into
2591+
a refusal, and `<Git.Commit>` and `<PullRequest>` decide what body is committed
2592+
or published. Each reads the contextual answer, so middleware may alter the
2593+
effect, the guard or the retained data each of those branches decides, and this
2594+
invocation boundary makes no stronger guarantee for them.
2595+
25642596
**Which domain an invocation is in is decided by what resolution selected, not
25652597
by the name that was asked for.** An authored name is what a document wrote, and
25662598
what it resolves to is decided by tiers, registrations and middleware, so a

‎packages/core/src/components/File.ts‎

Lines changed: 34 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ import { cwd } from "@executablemd/runtime";
6464
import { parseFilesFailure } from "@executablemd/runtime";
6565
import type { FilesFailureData, FileWriteFailureData, FilesReason } from "@executablemd/runtime";
6666
import { content } from "../component-api.ts";
67-
import { hasContent } from "../content-context.ts";
67+
import type { ComponentInvocation } from "../invocation-identity.ts";
6868
import { ContentError, DocumentationError, ProjectedContentError } from "../errors.ts";
6969
import { checkFilePath, readFileText, writeFileText } from "../files.ts";
7070
import type { Json } from "../types.ts";
@@ -87,11 +87,22 @@ export class FileAccessError extends Error {
8787
}
8888
}
8989

90-
export default printErrors(function* (props: Record<string, Json>): Operation<string> {
90+
export default printErrors(function* (
91+
props: Record<string, Json>,
92+
invocation: ComponentInvocation,
93+
): Operation<string> {
9194
const requested = String(props.path);
95+
// Which of the two things this element is comes from the invocation the
96+
// engine handed this call, and from nowhere else. `Component.hasContent()`
97+
// answers the same question through the composable chain, so a handler
98+
// installed outside this invocation answers ahead of the engine — and one
99+
// that answers per call reports one shape to a caller checking and the other
100+
// here. Either would render an empty string over a file the document wrote
101+
// `<File path="…" />` to read.
102+
const writing = authoredContent(invocation, requested);
92103
const directory = yield* cwd();
93104

94-
if (yield* hasContent()) {
105+
if (writing) {
95106
const admitted = yield* checkFilePath({ cwd: directory, path: requested });
96107
if (!admitted.ok) {
97108
throw new FileAccessError(refusal(requested, "write", parseFilesFailure(admitted.error)));
@@ -114,6 +125,26 @@ export default printErrors(function* (props: Record<string, Json>): Operation<st
114125
return read.value;
115126
});
116127

128+
/**
129+
* How this element was written, from the invocation the engine issued.
130+
*
131+
* There is no fallback to the contextual answer. A call arriving without a
132+
* genuine invocation is not one the engine made — a handler holding this
133+
* implementation and calling it somewhere else is the case that matters — and
134+
* this component chooses between reading a file and writing over it, so it
135+
* refuses rather than guessing. The refusal happens before `cwd()`, before the
136+
* children, and therefore before any provider is reached.
137+
*/
138+
function authoredContent(invocation: ComponentInvocation, requested: string): boolean {
139+
if (typeof invocation?.hasContent !== "function") {
140+
throw new FileAccessError(
141+
`<File path=${JSON.stringify(requested)} /> was called without the invocation the engine ` +
142+
"issued, so which form it was written as cannot be established.",
143+
);
144+
}
145+
return invocation.hasContent();
146+
}
147+
117148
/**
118149
* The rendered children, or a failure if anything went wrong producing them.
119150
*

‎packages/core/src/expand.ts‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2864,7 +2864,18 @@ function* expandFunctionComponent(
28642864
// The frame is the one the body is about to run in, so an issuance
28652865
// routed into a concurrent invocation of the same component answers
28662866
// nothing there.
2867-
const issued = issueInvocation(expansion.id, name, selected, yield* useScope());
2867+
//
2868+
// The authored shape travels with it, taken from the scan the same way
2869+
// the contextual answer below is. Both report it; only this one is
2870+
// beyond reach of the chain that reports it, which is what a component
2871+
// choosing an effect from it needs.
2872+
const issued = issueInvocation(
2873+
expansion.id,
2874+
name,
2875+
selected,
2876+
yield* useScope(),
2877+
!selfClosing,
2878+
);
28682879
const handle = createProjectionHandle({
28692880
invocation,
28702881
projecting: issued.projecting,

‎packages/core/src/invocation-identity.ts‎

Lines changed: 45 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -59,10 +59,15 @@ import type {
5959
/**
6060
* What a function component receives beside its props.
6161
*
62-
* Deliberately opaque: there is nothing on it to read. A component that merely
63-
* passes it along needs nothing from it, and one that wants to build one finds
64-
* no shape to copy. What it names is answered by a claimant, and only for the
65-
* execution that minted both.
62+
* Almost opaque. What it names is answered by a claimant, and only for the
63+
* execution that minted both; there is no shape here to copy and nothing to
64+
* read about the caller, the binding, the children, the environment or the
65+
* scope.
66+
*
67+
* The one thing it reports is how the element that caused this invocation was
68+
* written, because that is a fact about *this invocation* rather than about the
69+
* surroundings it runs in — and a component whose two spellings do different
70+
* things is choosing an effect with it.
6671
*
6772
* The brand is declared and never exported, so it names a type and nothing a
6873
* value can carry — the runtime test is the private field below, not this.
@@ -71,6 +76,24 @@ declare const Invocation: unique symbol;
7176

7277
export interface ComponentInvocation {
7378
readonly [Invocation]?: never;
79+
/**
80+
* Whether the element was written with content: `<C>…</C>` and `<C></C>`
81+
* yes, `<C />` no.
82+
*
83+
* The authored shape, immutable and synchronous. It projects nothing,
84+
* suspends on nothing, asks nothing of the middleware chain, and does not
85+
* spend this invocation's durable identity — reading it leaves the claimant
86+
* exactly as it was.
87+
*
88+
* This is what an *effect-selecting* branch reads. `Component.hasContent()`
89+
* answers the same question through the composable chain, where a handler
90+
* installed anywhere outside the invocation answers ahead of the engine, and
91+
* where a handler that answers per call can report one shape to a check and
92+
* the other to the component. That is fine for a component choosing how to
93+
* render; it is not fine for one choosing whether to read a file or write
94+
* over it.
95+
*/
96+
hasContent(): boolean;
7497
}
7598

7699
/** A durable identity that cannot be claimed here. */
@@ -164,6 +187,8 @@ interface Issuance {
164187
readonly id: string;
165188
/** The component this is an invocation of, as the engine resolved it. */
166189
readonly component: string;
190+
/** How the element was written, as the engine scanned it. */
191+
readonly content: boolean;
167192
/** The domain this execution gave that component, when it gave one. */
168193
readonly domain: IdentityDomain | undefined;
169194
/** The frame the engine invoked the implementation in. */
@@ -191,6 +216,20 @@ class EngineInvocation implements ComponentInvocation {
191216
Object.freeze(this);
192217
}
193218

219+
/**
220+
* The authored shape, read straight off the owner-kept issuance.
221+
*
222+
* Not a Context, not a contextual Api answer, not a registry entry, not a
223+
* property anything could redefine on a copy, and not a lookup exported for
224+
* somebody to reach: the state is private to this module and the only way to
225+
* it is an object the engine minted and handed over. A component evaluated
226+
* through a second loaded copy of core still calls this object, so what it
227+
* gets is the fact its own copy's helpers could not answer.
228+
*/
229+
hasContent(): boolean {
230+
return this.#issuance.content;
231+
}
232+
194233
static {
195234
stateOf = (value) =>
196235
typeof value === "object" && value !== null && #issuance in value
@@ -205,10 +244,12 @@ export function issueInvocation(
205244
component: string,
206245
domain: IdentityDomain | undefined,
207246
frame: Scope,
247+
content: boolean,
208248
): IssuedInvocation {
209249
const issuance: Issuance = {
210250
id,
211251
component,
252+
content,
212253
domain,
213254
frame,
214255
live: true,

0 commit comments

Comments
 (0)