lael-labs/t3code

packages/plugin-runtime-poc/README.md+2−2

@@ -14,8 +14,8 @@ this is the smallest and fastest planner in the experiment. for production, its · 13 unmodified lines
14		14
15	## proved	15	## proved
16		16
17	- 18 tests cover dependency order, blocking, rollback, cycles, unchanged instance reuse, provider-value replacement, unusual ids and slots, cleanup failures, immutable snapshots, and a 20,000-plugin stack-safe chain	17	- 23 tests cover dependency order, blocking, rollback, cycles, unchanged instance reuse, order-insensitive declarations, activation implementation replacement, cleanup reporting, unusual ids and slots, immutable snapshots, and a 20,000-plugin stack-safe chain
18	- manifest validation keeps mobile declarative	18	- manifest validation enforces semver, prevents entrypoint path escape, and keeps mobile declarative
19	- the demo exercises activation, replacement, teardown, and a 250-plugin chain	19	- the demo exercises activation, replacement, teardown, and a 250-plugin chain
20		20
21	## run	21	## run

packages/plugin-runtime-poc/src/contract.ts+6−2

 export interface PluginRuntimeSnapshot {
   readonly active: ReadonlyArray<string>;
-  readonly blocked: Readonly<Record<string, string>>;
+  readonly blocked: Readonly<Partial<Record<string, string>>>;
-  readonly contributions: Readonly<Record<string, ReadonlyArray<Contribution>>>;
+  readonly contributions: Readonly<Partial<Record<string, ReadonlyArray<Contribution>>>>;
 }
 export interface PluginRuntime {
     readonly phase: "activate" | "deactivate";
     readonly pluginId: string;
   }) => void;
+  readonly onCleanupError?: (event: {
+    readonly phase: "retire" | "rollback";
+    readonly error: unknown;
+  }) => void;
 }
 export type PluginRuntimeFactory = (options?: PluginRuntimeOptions) => PluginRuntime;

packages/plugin-runtime-poc/src/manifest.test.ts+16−0

@@ -40,9 +40,25 @@ describe("PluginManifest", () => { · 39 unmodified lines
40		40
41	it("rejects malformed versions and capability ids", () => {	41	it("rejects malformed versions and capability ids", () => {
42	expect(() => decodeManifest({ ...validManifest, version: "next" })).toThrow();	42	expect(() => decodeManifest({ ...validManifest, version: "next" })).toThrow();
		43	expect(() => decodeManifest({ ...validManifest, version: "01.2.3" })).toThrow();
		44	expect(() => decodeManifest({ ...validManifest, version: "1.2.3-.." })).toThrow();
		45	expect(decodeManifest({ ...validManifest, version: "1.2.3+build.7" }).version).toBe(
		46	"1.2.3+build.7",
		47	);
43	expect(() => decodeManifest({ ...validManifest, requires: ["t3.commands"] })).toThrow();	48	expect(() => decodeManifest({ ...validManifest, requires: ["t3.commands"] })).toThrow();
44	});	49	});
45		50
		51	it("rejects entrypoints that escape the plugin directory", () => {
		52	for (const server of ["./../outside.js", "./dist/../../outside.js"]) {
		53	expect(() =>
		54	decodeManifest({
		55	...validManifest,
		56	entrypoints: { ...validManifest.entrypoints, server },
		57	}),
		58	).toThrow();
		59	}
		60	});
		61
46	it("keeps mobile declarative by excluding a mobile executable entrypoint", () => {	62	it("keeps mobile declarative by excluding a mobile executable entrypoint", () => {
47	const decoded = decodeManifest({	63	const decoded = decodeManifest({
48	...validManifest,	64	...validManifest,

packages/plugin-runtime-poc/src/manifest.ts+6−2

 );
 const SemanticVersion = Schema.String.check(
-  Schema.isPattern(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/),
+  Schema.isPattern(
+    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:0|[1-9]\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/,
+  ),
 );
 const CapabilityId = Schema.String.check(Schema.isPattern(/^[a-z0-9][a-z0-9.-]*@[1-9]\d*$/));
-const RelativeEntrypoint = Schema.String.check(Schema.isPattern(/^\.\/[A-Za-z0-9_./-]+$/));
+const RelativeEntrypoint = Schema.String.check(
+  Schema.isPattern(/^\.\/(?!(?:\.\.(?:\/|$)|.*\/\.\.(?:\/|$)))[A-Za-z0-9_./-]+$/),
+);
 const Permission = Schema.String.check(Schema.isPattern(/^[a-z][a-z-]*:.+$/));
 const ContributionCatalog = Schema.Struct({

packages/plugin-runtime-poc/src/pureRuntime.ts+33−17

 };
 const sameDefinitionShape = (previous: PluginDefinition, desired: PluginDefinition) => {
-  const previousRequires = previous.requires ?? [];
+  const previousRequires = [...(previous.requires ?? [])].sort();
-  const desiredRequires = desired.requires ?? [];
+  const desiredRequires = [...(desired.requires ?? [])].sort();
   const previousProvidedServices = previous.provides ?? {};
   const desiredProvidedServices = desired.provides ?? {};
   const previousProvides = Object.keys(previousProvidedServices);
   return (
     previous.version === desired.version &&
+    Object.is(previous.activate, desired.activate) &&
     previousRequires.length === desiredRequires.length &&
     previousRequires.every((capability, index) => capability === desiredRequires[index]) &&
     previousProvides.length === desiredProvides.length &&
     previousProvides.every(
-      (capability, index) =>
+      (capability) =>
-        capability === desiredProvides[index] &&
+        Object.hasOwn(desiredProvidedServices, capability) &&
         Object.is(previousProvidedServices[capability], desiredProvidedServices[capability]),
     )
   );
 };
-const messageOf = (error: unknown) =>
-  error instanceof Error ? error.message : "plugin activation failed";
 export const createPureRuntime: PluginRuntimeFactory = (options = {}): PluginRuntime => {
   let current = emptyComposition();
   let disposed = false;
     return errors;
   };
+  const reportCleanupErrors = (phase: "retire" | "rollback", errors: ReadonlyArray<unknown>) => {
+    for (const error of errors) {
+      try {
+        options.onCleanupError?.({ phase, error });
+      } catch {
+        // Cleanup reporting must not replace an activation failure or invalidate a commit.
+      }
+    }
+  };
   const stage = async (
     definitions: ReadonlyArray<PluginDefinition>,
     previous: Composition,
           activating = false;
         }
-        instance.activated = true;
-        options.onLifecycle?.({ phase: "activate", pluginId: definition.id });
         for (const [capability, service] of Object.entries(definition.provides ?? {})) {
           services.set(capability, service);
         }
       };
     } catch (activationError) {
       const cleanupErrors = await deactivateAll(staged);
-      if (cleanupErrors.length > 0) {
+      reportCleanupErrors("rollback", cleanupErrors);
-        throw new Error(
-          `${messageOf(activationError)}; ${cleanupErrors.length} rollback finalizer(s) also failed`,
-          { cause: activationError },
-        );
-      }
       throw activationError;
     }
   };
         const candidate = await stage(desired, previous);
         current = candidate;
+        const lifecycleErrors: Array<unknown> = [];
+        for (const instance of candidate.instances) {
+          if (instance.activated) continue;
+          instance.activated = true;
+          try {
+            options.onLifecycle?.({ phase: "activate", pluginId: instance.definition.id });
+          } catch (error) {
+            lifecycleErrors.push(error);
+          }
+        }
         const retained = new Set(candidate.instances);
         const retired = previous.instances.filter((instance) => !retained.has(instance));
         const cleanupErrors = await deactivateAll(retired);
-        if (cleanupErrors.length > 0) {
+        reportCleanupErrors("retire", cleanupErrors);
-          throw new AggregateError(cleanupErrors, "previous composition deactivation failed");
+        if (lifecycleErrors.length > 0) {
+          throw new AggregateError(
+            lifecycleErrors,
+            "committed composition lifecycle reporting failed",
+          );
         }
         return candidate.snapshot;
       });

packages/plugin-runtime-poc/src/runtimeContract.ts+143−2

@@ -116,6 +116,78 @@ export function defineRuntimeContract(name: string, createRuntime: PluginRuntime · 115 unmodified lines
116	expect(disposals).toBe(1);	116	expect(disposals).toBe(1);
117	});	117	});
118		118
		119	it("treats reordered requirements and providers as the same definition", async () => {
		120	let activations = 0;
		121	const firstService = {};
		122	const secondService = {};
		123	const activate: PluginDefinition["activate"] = () => {
		124	activations += 1;
		125	};
		126	const dependencies: ReadonlyArray<PluginDefinition> = [
		127	{
		128	id: "acme.first-dependency",
		129	version: "1.0.0",
		130	provides: { "acme.first@1": true },
		131	activate() {},
		132	},
		133	{
		134	id: "acme.second-dependency",
		135	version: "1.0.0",
		136	provides: { "acme.second@1": true },
		137	activate() {},
		138	},
		139	];
		140	const runtime = createRuntime();
		141	await runtime.reconcile([
		142	...dependencies,
		143	{
		144	id: "acme.stable-order",
		145	version: "1.0.0",
		146	requires: ["acme.first@1", "acme.second@1"],
		147	provides: { "acme.output-one@1": firstService, "acme.output-two@1": secondService },
		148	activate,
		149	},
		150	]);
		151
		152	await runtime.reconcile([
		153	...dependencies,
		154	{
		155	id: "acme.stable-order",
		156	version: "1.0.0",
		157	requires: ["acme.second@1", "acme.first@1"],
		158	provides: { "acme.output-two@1": secondService, "acme.output-one@1": firstService },
		159	activate,
		160	},
		161	]);
		162
		163	expect(activations).toBe(1);
		164	await runtime.dispose();
		165	});
		166
		167	it("restarts a plugin when its activation implementation changes", async () => {
		168	const runtime = createRuntime();
		169	const first: PluginDefinition = {
		170	id: "acme.implementation",
		171	version: "1.0.0",
		172	activate(context) {
		173	context.register("commands", { id: "implementation", label: "first" });
		174	},
		175	};
		176	const second: PluginDefinition = {
		177	id: "acme.implementation",
		178	version: "1.0.0",
		179	activate(context) {
		180	context.register("commands", { id: "implementation", label: "second" });
		181	},
		182	};
		183
		184	await runtime.reconcile([first]);
		185	const snapshot = await runtime.reconcile([second]);
		186
		187	expect(contributionLabels(snapshot, "commands")).toEqual(["second"]);
		188	await runtime.dispose();
		189	});
		190
119	it("restarts a changed provider and its dependents without touching independent plugins", async () => {	191	it("restarts a changed provider and its dependents without touching independent plugins", async () => {
120	let independentActivations = 0;	192	let independentActivations = 0;
121	const lifecycle: Array<string> = [];	193	const lifecycle: Array<string> = [];
@@ -237,11 +309,16 @@ export function defineRuntimeContract(name: string, createRuntime: PluginRuntime · 115 unmodified lines
237	await runtime.dispose();	309	await runtime.dispose();
238	});	310	});
239		311
240	it("does not report a failed candidate as activated", async () => {	312	it("does not report a rolled-back candidate as activated", async () => {
241	const lifecycle: Array<string> = [];	313	const lifecycle: Array<string> = [];
242	const runtime = createRuntime({	314	const runtime = createRuntime({
243	onLifecycle: ({ phase, pluginId }) => lifecycle.push(`${phase}:${pluginId}`),	315	onLifecycle: ({ phase, pluginId }) => lifecycle.push(`${phase}:${pluginId}`),
244	});	316	});
		317	const staged: PluginDefinition = {
		318	id: "acme.staged",
		319	version: "1.0.0",
		320	activate() {},
		321	};
245	const broken: PluginDefinition = {	322	const broken: PluginDefinition = {
246	id: "acme.broken",	323	id: "acme.broken",
247	version: "1.0.0",	324	version: "1.0.0",
@@ -250,12 +327,76 @@ export function defineRuntimeContract(name: string, createRuntime: PluginRuntime · 2 unmodified lines
250	},	327	},
251	};	328	};
252		329
253	await expect(runtime.reconcile([broken])).rejects.toThrow("activation failed");	330	await expect(runtime.reconcile([staged, broken])).rejects.toThrow("activation failed");
254		331
255	expect(lifecycle).toEqual([]);	332	expect(lifecycle).toEqual([]);
256	await runtime.dispose();	333	await runtime.dispose();
257	});	334	});
258		335
		336	it("preserves activation failures when rollback cleanup also fails", async () => {
		337	const activationError = new Error("activation failed");
		338	const cleanupError = new Error("rollback cleanup failed");
		339	const cleanupEvents: Array<{ readonly phase: string; readonly error: unknown }> = [];
		340	const runtime = createRuntime({
		341	onCleanupError: (event) => {
		342	cleanupEvents.push(event);
		343	throw new Error("cleanup observer failed");
		344	},
		345	});
		346	const broken: PluginDefinition = {
		347	id: "acme.rollback-error",
		348	version: "1.0.0",
		349	activate(context) {
		350	context.onDispose(() => {
		351	throw cleanupError;
		352	});
		353	throw activationError;
		354	},
		355	};
		356
		357	await expect(runtime.reconcile([broken])).rejects.toBe(activationError);
		358	expect(cleanupEvents).toEqual([{ phase: "rollback", error: cleanupError }]);
		359	await runtime.dispose();
		360	});
		361
		362	it("returns the committed snapshot when retiring an old plugin reports cleanup errors", async () => {
		363	const cleanupError = new Error("retirement cleanup failed");
		364	const cleanupEvents: Array<{ readonly phase: string; readonly error: unknown }> = [];
		365	const runtime = createRuntime({
		366	onCleanupError: (event) => {
		367	cleanupEvents.push(event);
		368	throw new Error("cleanup observer failed");
		369	},
		370	});
		371	await runtime.reconcile([
		372	{
		373	id: "acme.retirement-error",
		374	version: "1.0.0",
		375	activate(context) {
		376	context.register("commands", { id: "retirement", label: "old" });
		377	context.onDispose(() => {
		378	throw cleanupError;
		379	});
		380	},
		381	},
		382	]);
		383
		384	const snapshot = await runtime.reconcile([
		385	{
		386	id: "acme.retirement-error",
		387	version: "2.0.0",
		388	activate(context) {
		389	context.register("commands", { id: "retirement", label: "new" });
		390	},
		391	},
		392	]);
		393
		394	expect(contributionLabels(snapshot, "commands")).toEqual(["new"]);
		395	expect(runtime.snapshot()).toBe(snapshot);
		396	expect(cleanupEvents).toEqual([{ phase: "retire", error: cleanupError }]);
		397	await runtime.dispose();
		398	});
		399
259	it("attempts every plugin cleanup when one finalizer fails", async () => {	400	it("attempts every plugin cleanup when one finalizer fails", async () => {
260	const disposed: Array<string> = [];	401	const disposed: Array<string> = [];
261	const runtime = createRuntime();	402	const runtime = createRuntime();