Skip to content

Commit d9985f1

Browse files
committed
🧵 Give each execution its own packaged-asset reader (#758)
The seam I added for SYN46 was a module-scoped mutable variable with an exported setter. One variable shared by every execution in the process: two runs would read through each other's reader, and substituting one changed what an unrelated execution was told the product says. A test-only intent does not make shared mutable state execution-local. The reader is now a value. It travels from where the execution is built — `runInvocation` → `invoke` → `executeDocument` → the observation — and the observation holds its own, so narrowing carries it and two executions in one process cannot reach each other's. There is no setter, no Context, no provider, no installation field and no hook: nothing a document, a component or an installed package can name reaches it at all. Production still uses the direct Effection filesystem. `executeReadingAssetsWith()` replaces `withAssetReader()`: it *builds a new execution* around a reader rather than changing anything an existing one holds, and is exported from `src/execute.ts` alone — not from `mod.ts`, not from `host.ts`. Importing it from a repository component gives you the ability to start your own execution, which you already had; it gives you no way to touch the current one's reader. SYN48 is the control that makes this a fact rather than a claim: one execution suspended inside documentation-index construction, a second ordinary execution overlapping it in the same process. The ordinary one reads canonical documentation and completes independently. Restoring the module-global implementation makes SYN48 fail, which is the check I should have written the first time — SYN46 alone passes under both designs.
1 parent 9d92bcb commit d9985f1

4 files changed

Lines changed: 172 additions & 65 deletions

File tree

‎packages/core/src/component-documentation.ts‎

Lines changed: 36 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -47,12 +47,15 @@ export function agentDocumentationUrl(): URL {
4747
* Agent components to document, and demanding their documentation would refuse
4848
* an index for a profile that is complete without them.
4949
*/
50-
export function* agentDocumentation(): Operation<DocumentationContribution> {
50+
export function* agentDocumentation(
51+
read: DocumentationReader = packagedAssetReader,
52+
): Operation<DocumentationContribution> {
5153
return {
52-
source: yield* readPackagedDocumentation(agentDocumentationUrl(), {
53-
owner: CORE_ORIGIN,
54-
asset: "packages/core/src/agent/components.md",
55-
}),
54+
source: yield* readPackagedDocumentation(
55+
agentDocumentationUrl(),
56+
{ owner: CORE_ORIGIN, asset: "packages/core/src/agent/components.md" },
57+
read,
58+
),
5659
supplies: AGENT_COMPONENT_NAMES,
5760
};
5861
}
@@ -64,7 +67,9 @@ const AGENT_COMPONENT_NAMES: ReadonlySet<string> = new Set([
6467
]);
6568

6669
/** Core's documentation source, read from the package rather than the caller. */
67-
export function* readCoreDocumentation(): Operation<DocumentationSource> {
70+
export function* readCoreDocumentation(
71+
read: DocumentationReader = packagedAssetReader,
72+
): Operation<DocumentationSource> {
6873
const url = componentDocumentationUrl();
6974
try {
7075
return {
@@ -78,7 +83,7 @@ export function* readCoreDocumentation(): Operation<DocumentationSource> {
7883
// out of its own package, so it goes to the filesystem directly, at a URL
7984
// derived from this module — package-relative whatever the working
8085
// directory and search path are.
81-
text: yield* readAsset(url),
86+
text: yield* read(url),
8287
};
8388
} catch (error) {
8489
throw new Error(
@@ -100,51 +105,38 @@ export function* packageDocumentation(
100105
url: URL,
101106
named: { owner: string; asset: string },
102107
supplies: Iterable<string>,
108+
read: DocumentationReader = packagedAssetReader,
103109
): Operation<DocumentationContribution> {
104110
return {
105-
source: yield* readPackagedDocumentation(url, named),
111+
source: yield* readPackagedDocumentation(url, named, read),
106112
supplies: new Set(supplies),
107113
};
108114
}
109115

110116
/**
111-
* What reads a packaged asset, so a test can suspend inside index construction.
117+
* How one execution reads its packaged assets.
112118
*
113-
* Module-private and deliberately not re-exported from `mod.ts`: it is not a
114-
* provider, not a Context and not a package hook, so nothing a document, a
115-
* component or an installed package can reach replaces it. What it exists for
116-
* is evidence — cancelling *inside the documentation work* is a different claim
117-
* from cancelling inside catalog discovery, and there is no other point in this
118-
* operation a test can stand at.
119+
* Carried by value from where the execution is built, never held in module
120+
* scope. A module-level reader would be one variable shared by every execution
121+
* in the process: two runs in one process would read through each other's, and
122+
* a test that substituted one would change what an unrelated execution is told
123+
* the product says. It is also not a provider, a Context, an installation field
124+
* or a hook — nothing a document, a component or an installed package can reach
125+
* names it at all.
119126
*/
120-
let readAsset: (url: URL) => Operation<string> = readTextFile;
127+
export type DocumentationReader = (url: URL) => Operation<string>;
121128

122-
/**
123-
* Substitute the asset reader for the duration of `body`, then restore it.
124-
*
125-
* Called by core's own tests through the source module, never through the
126-
* package's public surface.
127-
*/
128-
export function* withAssetReader<T>(
129-
reader: (url: URL) => Operation<string>,
130-
body: () => Operation<T>,
131-
): Operation<T> {
132-
const previous = readAsset;
133-
readAsset = reader;
134-
try {
135-
return yield* body();
136-
} finally {
137-
readAsset = previous;
138-
}
139-
}
129+
/** The reader every ordinary execution uses. */
130+
export const packagedAssetReader: DocumentationReader = readTextFile;
140131

141132
/** One packaged documentation asset, read the same guarded way. */
142133
export function* readPackagedDocumentation(
143134
url: URL,
144135
named: { owner: string; asset: string },
136+
read: DocumentationReader = packagedAssetReader,
145137
): Operation<DocumentationSource> {
146138
try {
147-
return { ...named, text: yield* readAsset(url) };
139+
return { ...named, text: yield* read(url) };
148140
} catch (error) {
149141
throw new Error(
150142
`the packaged component documentation ${named.asset} is missing from this build ` +
@@ -177,9 +169,17 @@ export function* documentationIndexFor(
177169
* could hide the documentation of a component it does.
178170
*/
179171
contributed: readonly DocumentationContribution[] = [],
172+
/**
173+
* How this execution reads core's own asset.
174+
*
175+
* By value, from whoever built the observation. Nothing module-scoped, so two
176+
* executions in one process each read through their own and neither can
177+
* change what the other is told.
178+
*/
179+
read: DocumentationReader = packagedAssetReader,
180180
): Operation<DocumentationIndex> {
181181
const core: DocumentationContribution = {
182-
source: yield* readCoreDocumentation(),
182+
source: yield* readCoreDocumentation(read),
183183
supplies: CORE_COMPONENT_NAMES,
184184
};
185185
const all = [core, ...contributed];

‎packages/core/src/execute.ts‎

Lines changed: 39 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,8 @@ import { ExecutionImports } from "./components/import-authority.ts";
141141
import type { ExpansionAuthority, ImportTier } from "./components/import-authority.ts";
142142
import { PROTECTED_COMPONENTS, ProtectedImports } from "./components/protected.ts";
143143
import { rootCatalogObservation, snapshotContributions } from "./syntax-observation.ts";
144-
import type { DocumentationContribution } from "./component-documentation.ts";
144+
import { packagedAssetReader } from "./component-documentation.ts";
145+
import type { DocumentationContribution, DocumentationReader } from "./component-documentation.ts";
145146
import type { CatalogContribution } from "./syntax-observation.ts";
146147
import type { WorkflowComponentBundle, WorkflowImportAuthority } from "./components/bundle.ts";
147148
import type { CodeBlockContext, CodeBlockResult, EvalEnv } from "./types.ts";
@@ -2161,6 +2162,8 @@ function* executeDocument(
21612162
* the profile actually assembled.
21622163
*/
21632164
documentation: readonly DocumentationContribution[] = [],
2165+
/** This execution's packaged-asset reader, carried by value from the caller. */
2166+
readAsset: DocumentationReader = packagedAssetReader,
21642167
): Operation<DocumentExecution> {
21652168
const {
21662169
stream,
@@ -2348,6 +2351,7 @@ function* executeDocument(
23482351
},
23492352
catalogs[0],
23502353
documentation,
2354+
readAsset,
23512355
),
23522356
};
23532357

@@ -2735,6 +2739,13 @@ export const Execution: Api<ExecutionApi> = createApi<ExecutionApi>("Execution",
27352739
function* runInvocation(
27362740
options: ExecuteOptions,
27372741
installations: readonly ExecutionInstallation[],
2742+
/**
2743+
* How this execution reads its packaged documentation assets.
2744+
*
2745+
* Defaulted to the real filesystem reader and carried by value from here into
2746+
* the observation, so it belongs to this execution alone.
2747+
*/
2748+
readAsset: DocumentationReader = packagedAssetReader,
27382749
observed?: () => void,
27392750
): Operation<DocumentExecution> {
27402751
const ready = withResolvers<DocumentExecution>();
@@ -2767,7 +2778,7 @@ function* runInvocation(
27672778
let published = false;
27682779
try {
27692780
yield* scoped(function* () {
2770-
const execution = yield* invoke(options, installations);
2781+
const execution = yield* invoke(options, installations, readAsset);
27712782
published = true;
27722783
ready.resolve(execution);
27732784
state.document = yield* execution;
@@ -2953,6 +2964,8 @@ function detachedSchema<Schema extends PropsSchema | ReturnsSchema>(schema: Sche
29532964
function* invoke(
29542965
options: ExecuteOptions,
29552966
installations: readonly ExecutionInstallation[],
2967+
/** This execution's packaged-asset reader, carried by value from its caller. */
2968+
readAsset: DocumentationReader = packagedAssetReader,
29562969
): Operation<DocumentExecution> {
29572970
const admissions = Object.freeze(
29582971
installations.flatMap((installation) => [...(installation.admissions ?? [])]),
@@ -3115,6 +3128,7 @@ function* invoke(
31153128
declarations,
31163129
catalogs,
31173130
documentation,
3131+
readAsset,
31183132
);
31193133
}
31203134

@@ -3152,7 +3166,7 @@ export function executeObserved(
31523166
): Operation<DocumentExecution> {
31533167
// The callback is read here, once, and passed on as a value. What the caller
31543168
// does to its own record afterwards is its own business.
3155-
return runInvocation(options, [...installations], observers.observed);
3169+
return runInvocation(options, [...installations], packagedAssetReader, observers.observed);
31563170
}
31573171

31583172
/**
@@ -3170,6 +3184,28 @@ export function executeInstalled(
31703184
return runInvocation(options, [...installations]);
31713185
}
31723186

3187+
/**
3188+
* One execution whose packaged-asset reads go through `read`.
3189+
*
3190+
* Core's own evidence seam, exported from this module and from neither `mod.ts`
3191+
* nor `host.ts`, so it is not part of the package's surface. It *builds a new
3192+
* execution* around the reader rather than changing anything an existing one
3193+
* holds — so importing it from a repository component, an installed package or
3194+
* a document's own code cannot reach the current execution's reader, and two
3195+
* executions in one process are unaffected by each other.
3196+
*
3197+
* It exists because cancelling *inside documentation-index construction* is a
3198+
* different claim from cancelling inside catalog discovery, and there is no
3199+
* other point in that operation a test can stand at.
3200+
*/
3201+
export function executeReadingAssetsWith(
3202+
options: ExecuteOptions,
3203+
installations: readonly ExecutionInstallation[],
3204+
readAsset: DocumentationReader,
3205+
): Operation<DocumentExecution> {
3206+
return runInvocation(options, [...installations], readAsset);
3207+
}
3208+
31733209
/**
31743210
* Apply every additive completion policy, in registration order.
31753211
*

‎packages/core/src/syntax-observation.ts‎

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,8 @@ import { inspectSyntax } from "./inspect.ts";
3434
import type { SyntaxCatalog } from "./inspect.ts";
3535
import { renderSelectedDocumentation, renderSyntaxMarkdown } from "./syntax-markdown.ts";
3636
import type { SelectedEntry } from "./syntax-markdown.ts";
37-
import { documentationIndexFor } from "./component-documentation.ts";
38-
import type { DocumentationContribution } from "./component-documentation.ts";
37+
import { documentationIndexFor, packagedAssetReader } from "./component-documentation.ts";
38+
import type { DocumentationContribution, DocumentationReader } from "./component-documentation.ts";
3939
import type { DocumentationIndex } from "./documentation-index.ts";
4040
import { UnknownComponentError } from "./documentation-index.ts";
4141
import type { WorkflowImportAuthority } from "./components/bundle.ts";
@@ -133,6 +133,16 @@ export function rootCatalogObservation(
133133
* fallback sentence inside a document.
134134
*/
135135
documentation: readonly DocumentationContribution[] = [],
136+
/**
137+
* How this execution reads its packaged assets.
138+
*
139+
* Held by the observation, so it belongs to this execution and no other. It
140+
* reaches here from where the execution was built and from nowhere else —
141+
* there is no setter, no context and no installation field that names it, so
142+
* a document, a component or an installed package cannot substitute one, and
143+
* a second execution in the same process is unaffected by this one's.
144+
*/
145+
read: DocumentationReader = packagedAssetReader,
136146
): CatalogObservation {
137147
function* current(): Operation<SyntaxCatalog> {
138148
return contribution === undefined ? yield* derived(inputs) : yield* contribution();
@@ -141,7 +151,7 @@ export function rootCatalogObservation(
141151
// ones the installation boundary captured rather than whatever the caller's
142152
// objects hold by the time a document asks.
143153
const captured = snapshotContributions(documentation);
144-
return observing(current, current, captured);
154+
return observing(current, current, captured, read);
145155
}
146156

147157
/**
@@ -155,6 +165,7 @@ function observing(
155165
reference: () => Operation<SyntaxCatalog>,
156166
executable: () => Operation<SyntaxCatalog>,
157167
documentation: readonly DocumentationContribution[],
168+
read: DocumentationReader,
158169
): CatalogObservation {
159170
return {
160171
*observe(): Operation<string> {
@@ -163,7 +174,7 @@ function observing(
163174
*document(names: readonly string[]): Operation<string> {
164175
const authoring = yield* reference();
165176
const runnable = yield* executable();
166-
const index = yield* documentationIndexFor(documentation);
177+
const index = yield* documentationIndexFor(documentation, read);
167178
return renderSelectedDocumentation(select(authoring, runnable, names, index));
168179
},
169180
narrow(admitted: SyntaxCatalog): CatalogObservation {
@@ -178,6 +189,7 @@ function observing(
178189
return admitted;
179190
},
180191
documentation,
192+
read,
181193
);
182194
},
183195
};
@@ -341,6 +353,8 @@ export function fixedCatalogObservation(
341353
* installs the executable catalog; this is the index that goes with it.
342354
*/
343355
documentation: readonly DocumentationContribution[] = [],
356+
/** How this observation reads packaged assets — this execution's, by value. */
357+
read: DocumentationReader = packagedAssetReader,
344358
): CatalogObservation {
345359
const captured = snapshotContributions(documentation);
346360
return observing(
@@ -353,5 +367,6 @@ export function fixedCatalogObservation(
353367
return catalog;
354368
},
355369
captured,
370+
read,
356371
);
357372
}

0 commit comments

Comments
 (0)