@code-yeongyu/senpi-realm-registry 0.0.0-reserve.0 → 2026.11.13

package/README.md

@@ -0,0 +1,6 @@
+# @earendil-works/pi-realm-registry
+
+One pinned, versioned registry instance per JavaScript realm (omo#12965). senpi's engine modules keep every table that one
+engine copy writes and another reads behind `realmRegistry(keyName, create, isV1)`, so a second copy of the engine in
+the same process shares the table instead of keeping a private one. Private workspace package; published as
+`@code-yeongyu/senpi-realm-registry` with pi-ai and vendored into the engine tarball.

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * One registry instance per JavaScript realm, whatever number of engine copies load (omo#12965).
+ *
+ * A process can evaluate senpi's engine modules more than once (the bundled CLI next to the SDK graph a plugin imports,
+ * a re-evaluated extension generation, an embedder's second install). A table one copy writes and another reads must
+ * therefore not live in module scope. Each such table is a frozen interface object whose state lives only in the
+ * closure of the copy that created it, pinned on `globalThis` under `Symbol.for(keyName)` (non-writable,
+ * non-configurable, non-enumerable). Every later copy adopts that instance and calls through its functions: nothing
+ * crosses copies through class identity, and readers validate every value that does.
+ *
+ * Permanent contract: a key name never changes; its v1 members are never removed or repurposed, and later versions only
+ * add members, so a copy adopts any pinned, frozen object that satisfies the v1 check and ignores members it does not
+ * know. A slot that is not pinned that way (planted before senpi loaded, an accessor, another shape) is refused with a
+ * typed error that names the key and never a value. Workers, `vm` contexts and child processes are other realms and
+ * hold their own instances. This package holds no state of its own, so every inlined copy applies one rule.
+ */
+export declare const REALM_REGISTRY_FOREIGN = "SENPI_REALM_REGISTRY_FOREIGN";
+export declare class RealmRegistryError extends Error {
+    readonly code: typeof REALM_REGISTRY_FOREIGN;
+    readonly key: string;
+    constructor(keyName: string, cause?: unknown);
+}
+/** Builds the error a refused slot raises; the redaction registry keeps its own class and code (senpi#6334). */
+export type RealmRegistryRefusal = (cause?: unknown) => Error;
+/**
+ * The realm's single instance under `keyName`: the pinned one when it exists and satisfies `isV1`, else the frozen
+ * object `create()` builds, pinned now. Throws `refuse()` (by default `RealmRegistryError`) for any other slot value.
+ */
+export declare function realmRegistry<T extends object>(keyName: string, create: () => T, isV1: (value: unknown) => value is T, refuse?: RealmRegistryRefusal): T;
+/** The realm's instance under `keyName` without ever creating one: `undefined` when none exists yet. */
+export declare function realmRegistryLookup<T extends object>(keyName: string, isV1: (value: unknown) => value is T, refuse?: RealmRegistryRefusal): T | undefined;
+/** Whether `value` has every named member as a function, the usual v1 check. */
+export declare function hasFunctions(value: unknown, names: readonly string[]): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,77 @@
+/**
+ * One registry instance per JavaScript realm, whatever number of engine copies load (omo#12965).
+ *
+ * A process can evaluate senpi's engine modules more than once (the bundled CLI next to the SDK graph a plugin imports,
+ * a re-evaluated extension generation, an embedder's second install). A table one copy writes and another reads must
+ * therefore not live in module scope. Each such table is a frozen interface object whose state lives only in the
+ * closure of the copy that created it, pinned on `globalThis` under `Symbol.for(keyName)` (non-writable,
+ * non-configurable, non-enumerable). Every later copy adopts that instance and calls through its functions: nothing
+ * crosses copies through class identity, and readers validate every value that does.
+ *
+ * Permanent contract: a key name never changes; its v1 members are never removed or repurposed, and later versions only
+ * add members, so a copy adopts any pinned, frozen object that satisfies the v1 check and ignores members it does not
+ * know. A slot that is not pinned that way (planted before senpi loaded, an accessor, another shape) is refused with a
+ * typed error that names the key and never a value. Workers, `vm` contexts and child processes are other realms and
+ * hold their own instances. This package holds no state of its own, so every inlined copy applies one rule.
+ */
+export const REALM_REGISTRY_FOREIGN = "SENPI_REALM_REGISTRY_FOREIGN";
+export class RealmRegistryError extends Error {
+    constructor(keyName, cause) {
+        super(`The process-wide registry ${keyName} was not installed by senpi or is incompatible; restart the process.`, cause === undefined ? undefined : { cause });
+        this.name = "RealmRegistryError";
+        this.code = REALM_REGISTRY_FOREIGN;
+        this.key = keyName;
+    }
+}
+function foreignRegistry(keyName) {
+    return (cause) => new RealmRegistryError(keyName, cause);
+}
+function adopted(slot, isV1, refuse) {
+    const value = slot.value;
+    if (!("value" in slot) ||
+        slot.writable !== false ||
+        slot.configurable !== false ||
+        typeof value !== "object" ||
+        value === null ||
+        !Object.isFrozen(value) ||
+        !isV1(value)) {
+        throw refuse();
+    }
+    return value;
+}
+/**
+ * The realm's single instance under `keyName`: the pinned one when it exists and satisfies `isV1`, else the frozen
+ * object `create()` builds, pinned now. Throws `refuse()` (by default `RealmRegistryError`) for any other slot value.
+ */
+export function realmRegistry(keyName, create, isV1, refuse) {
+    const refusal = refuse ?? foreignRegistry(keyName);
+    const key = Symbol.for(keyName);
+    const slot = Reflect.getOwnPropertyDescriptor(globalThis, key);
+    if (slot !== undefined)
+        return adopted(slot, isV1, refusal);
+    const instance = Object.freeze(create());
+    try {
+        Object.defineProperty(globalThis, key, {
+            value: instance,
+            writable: false,
+            configurable: false,
+            enumerable: false,
+        });
+    }
+    catch (error) {
+        throw refusal(error);
+    }
+    return instance;
+}
+/** The realm's instance under `keyName` without ever creating one: `undefined` when none exists yet. */
+export function realmRegistryLookup(keyName, isV1, refuse) {
+    const slot = Reflect.getOwnPropertyDescriptor(globalThis, Symbol.for(keyName));
+    return slot === undefined ? undefined : adopted(slot, isV1, refuse ?? foreignRegistry(keyName));
+}
+/** Whether `value` has every named member as a function, the usual v1 check. */
+export function hasFunctions(value, names) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    return names.every((name) => typeof Reflect.get(value, name) === "function");
+}
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1 +1,44 @@
-{"name":"@code-yeongyu/senpi-realm-registry","version":"0.0.0-reserve.0","description":"Name reservation. Real versions are published by the senpi release workflow.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/code-yeongyu/senpi.git","directory":"packages/realm-registry"}}
+{
+	"name": "@code-yeongyu/senpi-realm-registry",
+	"version": "2026.11.13",
+	"description": "One pinned, versioned registry instance per JavaScript realm, shared by every copy of senpi's engine modules",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"!dist/**/*.map",
+		"README.md"
+	],
+	"scripts": {
+		"clean": "shx rm -rf dist",
+		"build": "tsc -p tsconfig.build.json",
+		"test": "node ../../scripts/run-tests.mjs vitest --run",
+		"prepublishOnly": "npm run clean && npm run build"
+	},
+	"keywords": [
+		"senpi",
+		"realm",
+		"registry"
+	],
+	"author": "Earendil Works",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/code-yeongyu/senpi.git",
+		"directory": "packages/realm-registry"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"devDependencies": {
+		"@types/node": "26.6.2",
+		"vitest": "5.0.1"
+	}
+}