Skip to content

Commit b303c21

Browse files
committed
🧱 Close the generated-XMD durable protocol and state the evaluation profile
Foundation for #713's protected <Evaluate>, not the surface itself. Six things the amended contract needs before a component can be built on them. The retained record is versioned. Version 2 tags itself at both the result and the policy level and carries the Workspace basis as one optional member, because an ordinary host evaluates against no Workspace and a reader that treated a missing basis as an empty one would compare those two equal. The untagged #369 record stays readable as version 1, proved against frozen literal records rather than version-2 records mechanically rewritten — a rewrite proves only that the rewriter and the reader agree. Both versions are now closed at every level: policy, Workspace basis, allowed entry, named invocation, and request. A member this build does not know means a record written under rules it does not have, so reading the members it recognizes would admit a grant on terms it never saw. `parseRequestRecord()` is the wrong reader for a retained ceiling — it ignores unknown members and treats a malformed timeout as an absent one — so requests read through a closed reader here instead. Exact text joins the ceilings a continuation is held to. An admission is a decision about one fragment; a caller now holding different text is asking for a decision nobody made, so it refuses rather than silently expanding the retained copy. GX24/GX24b asserted the superseded behavior and now assert this, with GX24c as the unchanged-text control. A Workspace basis is validated where it is stated, not only where it is compared: non-empty unique roots and a selected root the host retains. A basis with no roots or a selected root nothing holds is not a stricter grant, it is nothing for a continuation to be held to. `ExecutionInstallation.evaluation` carries one host profile, refused in the plural on the same terms as `symbols`, and reaches canonical expansion on the private authority. The deep by-value capture, the per-entry request ceilings and the captured provider operations are the next commit; this one places the singleton and its carrier.
1 parent bb2c1c4 commit b303c21

7 files changed

Lines changed: 911 additions & 82 deletions

File tree

‎packages/core/src/components/import-authority.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ import type {
2727
import type { DeclaredImports, PrivateClosure } from "./declared-markdown.ts";
2828
import type { ExactSource } from "../output/exact-source.ts";
2929
import type { SyntaxReference } from "../syntax-reference.ts";
30+
import type { FragmentEvaluationProfile } from "../evaluation-profile.ts";
3031

3132
/** A definition an import may answer with. */
3233
export type ImportedDefinition = ComponentDefinition | FunctionComponentDefinition;
@@ -121,6 +122,21 @@ export interface ExpansionAuthority {
121122
* projected and an imported definition each carry what the site carried.
122123
*/
123124
readonly syntax?: SyntaxReference;
125+
/**
126+
* The maximum authority a generated fragment may be evaluated under.
127+
*
128+
* Stated by the trusted host at the installation boundary, before the root
129+
* import and before any document, component or middleware code exists, and
130+
* handed here by value like everything else on this object. It is on the
131+
* private authority rather than in a context for the reason the rest are, and
132+
* one more: `<Evaluate>` is a *public* component, so any author may write it,
133+
* and what keeps that from being a capability is that the ceiling it narrows
134+
* from was settled by somebody the document cannot reach.
135+
*
136+
* Absent for a host that offers no evaluation. That is not an unrestricted
137+
* evaluation — it is no evaluation, and `<Evaluate>` refuses.
138+
*/
139+
readonly evaluation?: FragmentEvaluationProfile;
124140
/**
125141
* The bodies this execution will enter for the components canonical core
126142
* protects.
Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
/**
2+
* What a trusted host allows a generated fragment to do, stated before any
3+
* document code exists.
4+
*
5+
* `<Evaluate>` is a public component: any author may write it, and canonical
6+
* core owns what it means. That settles *which implementation runs* and nothing
7+
* else — a protected name is not authority, and a component that granted some
8+
* by being protected would be a capability anybody could reach by spelling it.
9+
* So the authority is here instead, in a value the host hands canonical
10+
* execution at the installation boundary: the maximum a fragment may do under
11+
* this host, whatever a document later asks for.
12+
*
13+
* `allow` then selects from this profile. It can narrow it and it can do
14+
* nothing else — a class this profile has no table for is a policy that cannot
15+
* be stated, not a fragment to refuse, and a table entry an author never asked
16+
* for is simply not selected.
17+
*
18+
* ## One per execution
19+
*
20+
* Two profiles would be two answers to "what may a fragment do here", and
21+
* choosing between them by installation order would make authority depend on
22+
* assembly. So an execution accepts one, refuses two, and evaluating without one
23+
* refuses before the producer runs — a host that stated no profile did not
24+
* decline to restrict evaluation, it declined to offer it.
25+
*
26+
* It is captured by value with the rest of the installation, before the root
27+
* import and before any document, component or middleware code exists. Nothing a
28+
* running document can reach names it: not a context, whose name is not a
29+
* secret; not a registry, which a nested scope layers over; not a prop, which an
30+
* author writes.
31+
*/
32+
33+
import type { GeneratedMutation, GeneratedObservation } from "./generated-xmd.ts";
34+
35+
/**
36+
* The Workspace basis a workflow host evaluates against.
37+
*
38+
* Absent for an ordinary run, which has no Workspace and addresses its Files
39+
* provider directly. Present for a workflow run, where an admitted effect
40+
* crosses the run's own transaction-bound provider and the retained roots are
41+
* the provenance a continuation is held to.
42+
*/
43+
export interface FragmentWorkspace {
44+
/** The retained roots this host is willing to expose. */
45+
readonly roots: readonly string[];
46+
/** The one root admitted effects address. */
47+
readonly selectedRoot: string;
48+
}
49+
50+
/**
51+
* One host's complete statement of what a fragment may do.
52+
*
53+
* The two tables are stated whether or not a document asks for either: `allow`
54+
* selects from what the host already installed and can add nothing to it, so a
55+
* host that omits the write table has made a fragment unable to write no matter
56+
* what an author writes in `allow`.
57+
*/
58+
export interface FragmentEvaluationProfile {
59+
/**
60+
* The pinned identities the `read` class resolves to.
61+
*
62+
* For both standard profiles this is exactly the self-closing `<File>`.
63+
* `<Fetch>` joins it only where the host also states the exact requests it
64+
* may perform, because an unbounded network read is a different decision
65+
* from an admitted one.
66+
*/
67+
readonly read: readonly GeneratedObservation[];
68+
/**
69+
* The pinned identities the `write` class resolves to, when this host offers
70+
* the class at all.
71+
*
72+
* For both standard profiles this is exactly paired `<File>`, paired `<Dir>`
73+
* and self-closing `<File.Delete>`. It does not include the read table:
74+
* `write` selects mutation and nothing else, so an author needing both writes
75+
* `allow={["read", "write"]}`.
76+
*/
77+
readonly write?: readonly GeneratedMutation[];
78+
/** The Workspace basis, for a host that evaluates against one. */
79+
readonly workspace?: FragmentWorkspace;
80+
/**
81+
* Whether this host accepts the released `source` spelling beside `text`.
82+
*
83+
* The workflow profile does, silently, because documents were written against
84+
* it before `text` existed. The ordinary profile does not: it never shipped
85+
* that spelling, and acquiring a legacy alias it has no legacy for would be
86+
* inventing one.
87+
*/
88+
readonly deprecatedSourceAlias?: boolean;
89+
}
90+
91+
/** What an execution that was offered no evaluation profile refuses with. */
92+
export const NO_PROFILE =
93+
"<Evaluate /> has no evaluation profile here: this host stated none, so nothing established " +
94+
"what a generated fragment may do. A profile is the host's own statement of the maximum " +
95+
"authority an evaluation has, and `allow` only narrows it.";
96+
97+
/** What an execution offered two evaluation profiles refuses with. */
98+
export const TWO_PROFILES =
99+
"two installations stated the evaluation profile this execution offers. One execution offers " +
100+
"one maximum authority, so what a generated fragment may do is never a question of assembly " +
101+
"order.";

‎packages/core/src/execute.ts‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,8 @@ import type { ExpansionAuthority, ImportTier } from "./components/import-authori
142142
import { PROTECTED_COMPONENTS, ProtectedImports } from "./components/protected.ts";
143143
import { rootSyntaxReference } from "./syntax-reference.ts";
144144
import { capturedDocumentation } from "./documentation-api.ts";
145+
import { TWO_PROFILES } from "./evaluation-profile.ts";
146+
import type { FragmentEvaluationProfile } from "./evaluation-profile.ts";
145147
import { packagedAssetReader } from "./component-documentation.ts";
146148
import type { DocumentationContribution, DocumentationReader } from "./component-documentation.ts";
147149
import type { SyntaxSymbolsProvider } from "./syntax-reference.ts";
@@ -2173,6 +2175,15 @@ function* executeDocument(
21732175
documentation: readonly DocumentationContribution[] = [],
21742176
/** This execution's packaged-asset reader, carried by value from the caller. */
21752177
readAsset: DocumentationReader = packagedAssetReader,
2178+
/**
2179+
* The one evaluation profile this host stated, when it stated one.
2180+
*
2181+
* Carried by value like the symbols provider beside it, and handed to core's
2182+
* own expansion on the private authority rather than through any context: it
2183+
* is the ceiling `<Evaluate>` narrows from, and a document that could reach it
2184+
* could raise it.
2185+
*/
2186+
evaluation?: FragmentEvaluationProfile,
21762187
): Operation<DocumentExecution> {
21772188
const {
21782189
stream,
@@ -2361,6 +2372,10 @@ function* executeDocument(
23612372
providers[0],
23622373
documentation,
23632374
),
2375+
// The ceiling a generated fragment is evaluated under, when this host
2376+
// offers evaluation at all. Absent is a host that offers none, and
2377+
// `<Evaluate>` refuses on that rather than inventing one.
2378+
...(evaluation === undefined ? {} : { evaluation }),
23642379
};
23652380

23662381
// Install the document's runtime Component providers before durableRun
@@ -2655,6 +2670,23 @@ export interface ExecutionInstallation {
26552670
* once at the same boundary.
26562671
*/
26572672
readonly symbols?: SyntaxSymbolsProvider;
2673+
/**
2674+
* The maximum authority a generated fragment may be evaluated under here.
2675+
*
2676+
* Captured by value alongside the rest, before any installation runs, for a
2677+
* reason the others share and this one sharpens: `<Evaluate>` is a public
2678+
* component, so any author may write it, and what stops that from being a
2679+
* capability is that the ceiling was stated by the host before a document
2680+
* existed. Nothing a running document reaches names this — not a context,
2681+
* whose name is not a secret; not a registry, which a nested scope layers
2682+
* over; not a prop, which an author writes.
2683+
*
2684+
* Omitted is the ordinary case for a host that offers no evaluation at all:
2685+
* `<Evaluate>` then refuses before the producer runs, rather than evaluating
2686+
* under a ceiling nobody stated. One execution accepts one; two are refused
2687+
* rather than ordered.
2688+
*/
2689+
readonly evaluation?: FragmentEvaluationProfile;
26582690
install?(): Operation<void>;
26592691
}
26602692

@@ -3072,6 +3104,22 @@ function* invoke(
30723104
);
30733105
}
30743106

3107+
// The maximum authority a generated fragment may be evaluated under here,
3108+
// read on the same terms and for a stronger reason: two profiles would be two
3109+
// answers to what a fragment may *do*, and choosing between them by
3110+
// installation order would make authority depend on assembly. A host that
3111+
// stated none offers no evaluation at all, which `<Evaluate>` refuses with
3112+
// rather than inventing a ceiling for.
3113+
const profiles = Object.freeze(
3114+
installations.flatMap((installation) => {
3115+
const profile = installation.evaluation;
3116+
return profile === undefined ? [] : [profile];
3117+
}),
3118+
);
3119+
if (profiles.length > 1) {
3120+
throw new Error(TWO_PROFILES);
3121+
}
3122+
30753123
for (const installation of installations) {
30763124
if (installation.install) {
30773125
yield* installation.install();
@@ -3123,6 +3171,7 @@ function* invoke(
31233171
providers,
31243172
documentation,
31253173
readAsset,
3174+
profiles[0],
31263175
);
31273176
}
31283177

0 commit comments

Comments
 (0)