@spearwolf/shadow-objects 0.34.0 → 0.35.0

package/src/model-context/tools/getEntity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getEntity.d.ts","sourceRoot":"","sources":["../../../../src/model-context/tools/getEntity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,kBAAkB,EAAE,cAAc,EAAE,qBAAqB,EAAC,MAAM,wBAAwB,CAAC;AACtG,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAOL,KAAK,WAAW,EAGjB,MAAM,mBAAmB,CAAC;AAE3B,wGAAwG;AACxG,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,CAAC;IAC9C,SAAS,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,EAAE,CAAC;IAC3C,IAAI,CAAC,EAAE,qBAAqB,CAAC;IAC7B,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;CAC/B;AAED,eAAO,MAAM,mBAAmB,QAAS,WAAW,KAAG,oBA2DnD,CAAC"}

package/src/model-context/tools/getEntity.js

@@ -0,0 +1,65 @@
+import {
+  buildRequest,
+  defineTool,
+  describeEnv,
+  inspectEnvs,
+  NamespaceInputSchema,
+  runTool,
+  ToolError,
+  textResult
+} from "../toolSupport.js";
+const createGetEntityTool = (ctx) => defineTool(ctx, "get-entity", {
+  title: "Get Entity",
+  description: "One Entity in full -- token, properties, Shadow Objects, Entity Contexts, its children one level down -- with the chain of ancestors above it and the View's component of the same uuid next to it, which is where a divergence between View and Kernel becomes visible. Without a namespace every environment is asked; a uuid held in more than one comes back once per environment.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      uuid: { type: "string", description: "The uuid of the Entity, as the tree and the search report it." },
+      namespace: NamespaceInputSchema
+    },
+    required: ["uuid"],
+    additionalProperties: false
+  },
+  execute: runTool(async (input, signal) => {
+    const uuid = input.requiredString("uuid");
+    const envs = await inspectEnvs(
+      input.string("namespace"),
+      buildRequest(ctx.limits, { rootUuids: [uuid], maxDepth: 1 }),
+      signal,
+      ctx
+    );
+    const matches = [];
+    for (const s of envs) {
+      const node = s.kernel?.roots[0];
+      if (node === void 0) continue;
+      const { ancestors = [], ...entity } = node;
+      const entry = { namespace: s.namespace, entity, ancestors };
+      const view = s.view?.roots[0];
+      if (view !== void 0) entry.view = view;
+      if (s.kernel?.truncation !== void 0) entry.truncation = s.kernel.truncation;
+      matches.push(entry);
+    }
+    if (matches.length === 0) {
+      const failed = envs.filter((s) => s.error !== void 0).map(describeEnv);
+      throw new ToolError(
+        `no Shadow Environment holds an Entity "${uuid}"${failed.length > 0 ? ` (${failed.join("; ")})` : ""}`
+      );
+    }
+    const errors = [];
+    for (const s of envs) {
+      if (s.error !== void 0) errors.push({ namespace: s.namespace, error: s.error });
+    }
+    let summary = matches.map((m) => {
+      const where = m.ancestors.length === 0 ? "a root" : `under ${m.ancestors.map((a) => a.token).join(" > ")}`;
+      return `${m.namespace}: ${m.entity.token} "${m.entity.uuid}", ${where}, ${m.entity.childCount} children`;
+    }).join("; ");
+    if (errors.length > 0) {
+      summary += `; failed: ${errors.map((e) => `${e.namespace} (${e.error.name}: ${e.error.message})`).join(", ")}`;
+    }
+    return textResult(summary, errors.length > 0 ? { matches, errors } : { matches });
+  })
+});
+export {
+  createGetEntityTool
+};
+//# sourceMappingURL=getEntity.js.map

package/src/model-context/tools/getEntity.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/model-context/tools/getEntity.ts"],
+  "sourcesContent": ["import type {EntityNodeSnapshot, TruncationNote, ViewComponentSnapshot} from '../../inspect/types.js';\nimport type {ModelContextToolLike} from '../ModelContextLike.js';\nimport {\n  buildRequest,\n  defineTool,\n  describeEnv,\n  inspectEnvs,\n  NamespaceInputSchema,\n  runTool,\n  type ToolContext,\n  ToolError,\n  textResult,\n} from '../toolSupport.js';\n\n/** One Entity in one environment, with the chain above it and the View's component of the same uuid. */\nexport interface EntityMatchEntry {\n  namespace: string;\n  entity: Omit<EntityNodeSnapshot, 'ancestors'>;\n  ancestors: {uuid: string; token: string}[];\n  view?: ViewComponentSnapshot;\n  truncation?: TruncationNote[];\n}\n\nexport const createGetEntityTool = (ctx: ToolContext): ModelContextToolLike =>\n  defineTool(ctx, 'get-entity', {\n    title: 'Get Entity',\n    description:\n      \"One Entity in full -- token, properties, Shadow Objects, Entity Contexts, its children one level down -- with the chain of ancestors above it and the View's component of the same uuid next to it, which is where a divergence between View and Kernel becomes visible. Without a namespace every environment is asked; a uuid held in more than one comes back once per environment.\",\n    inputSchema: {\n      type: 'object',\n      properties: {\n        uuid: {type: 'string', description: 'The uuid of the Entity, as the tree and the search report it.'},\n        namespace: NamespaceInputSchema,\n      },\n      required: ['uuid'],\n      additionalProperties: false,\n    },\n    execute: runTool(async (input, signal) => {\n      const uuid = input.requiredString('uuid');\n      // the depth is this tool's, not the exposure's: one level of children, and the chain above\n      const envs = await inspectEnvs(\n        input.string('namespace'),\n        buildRequest(ctx.limits, {rootUuids: [uuid], maxDepth: 1}),\n        signal,\n        ctx,\n      );\n\n      const matches: EntityMatchEntry[] = [];\n      for (const s of envs) {\n        const node = s.kernel?.roots[0];\n        if (node === undefined) continue;\n        const {ancestors = [], ...entity} = node;\n        const entry: EntityMatchEntry = {namespace: s.namespace, entity, ancestors};\n        const view = s.view?.roots[0];\n        if (view !== undefined) entry.view = view;\n        if (s.kernel?.truncation !== undefined) entry.truncation = s.kernel.truncation;\n        matches.push(entry);\n      }\n\n      if (matches.length === 0) {\n        const failed = envs.filter((s) => s.error !== undefined).map(describeEnv);\n        throw new ToolError(\n          `no Shadow Environment holds an Entity \"${uuid}\"${failed.length > 0 ? ` (${failed.join('; ')})` : ''}`,\n        );\n      }\n\n      const errors: {namespace: string; error: {name: string; message: string}}[] = [];\n      for (const s of envs) {\n        if (s.error !== undefined) errors.push({namespace: s.namespace, error: s.error});\n      }\n\n      let summary = matches\n        .map((m) => {\n          const where = m.ancestors.length === 0 ? 'a root' : `under ${m.ancestors.map((a) => a.token).join(' > ')}`;\n          return `${m.namespace}: ${m.entity.token} \"${m.entity.uuid}\", ${where}, ${m.entity.childCount} children`;\n        })\n        .join('; ');\n      if (errors.length > 0) {\n        summary += `; failed: ${errors.map((e) => `${e.namespace} (${e.error.name}: ${e.error.message})`).join(', ')}`;\n      }\n      return textResult(summary, errors.length > 0 ? {matches, errors} : {matches});\n    }),\n  });\n"],
+  "mappings": "AAEA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEA;AAAA,EACA;AAAA,OACK;AAWA,MAAM,sBAAsB,CAAC,QAClC,WAAW,KAAK,cAAc;AAAA,EAC5B,OAAO;AAAA,EACP,aACE;AAAA,EACF,aAAa;AAAA,IACX,MAAM;AAAA,IACN,YAAY;AAAA,MACV,MAAM,EAAC,MAAM,UAAU,aAAa,gEAA+D;AAAA,MACnG,WAAW;AAAA,IACb;AAAA,IACA,UAAU,CAAC,MAAM;AAAA,IACjB,sBAAsB;AAAA,EACxB;AAAA,EACA,SAAS,QAAQ,OAAO,OAAO,WAAW;AACxC,UAAM,OAAO,MAAM,eAAe,MAAM;AAExC,UAAM,OAAO,MAAM;AAAA,MACjB,MAAM,OAAO,WAAW;AAAA,MACxB,aAAa,IAAI,QAAQ,EAAC,WAAW,CAAC,IAAI,GAAG,UAAU,EAAC,CAAC;AAAA,MACzD;AAAA,MACA;AAAA,IACF;AAEA,UAAM,UAA8B,CAAC;AACrC,eAAW,KAAK,MAAM;AACpB,YAAM,OAAO,EAAE,QAAQ,MAAM,CAAC;AAC9B,UAAI,SAAS,OAAW;AACxB,YAAM,EAAC,YAAY,CAAC,GAAG,GAAG,OAAM,IAAI;AACpC,YAAM,QAA0B,EAAC,WAAW,EAAE,WAAW,QAAQ,UAAS;AAC1E,YAAM,OAAO,EAAE,MAAM,MAAM,CAAC;AAC5B,UAAI,SAAS,OAAW,OAAM,OAAO;AACrC,UAAI,EAAE,QAAQ,eAAe,OAAW,OAAM,aAAa,EAAE,OAAO;AACpE,cAAQ,KAAK,KAAK;AAAA,IACpB;AAEA,QAAI,QAAQ,WAAW,GAAG;AACxB,YAAM,SAAS,KAAK,OAAO,CAAC,MAAM,EAAE,UAAU,MAAS,EAAE,IAAI,WAAW;AACxE,YAAM,IAAI;AAAA,QACR,0CAA0C,IAAI,IAAI,OAAO,SAAS,IAAI,KAAK,OAAO,KAAK,IAAI,CAAC,MAAM,EAAE;AAAA,MACtG;AAAA,IACF;AAEA,UAAM,SAAwE,CAAC;AAC/E,eAAW,KAAK,MAAM;AACpB,UAAI,EAAE,UAAU,OAAW,QAAO,KAAK,EAAC,WAAW,EAAE,WAAW,OAAO,EAAE,MAAK,CAAC;AAAA,IACjF;AAEA,QAAI,UAAU,QACX,IAAI,CAAC,MAAM;AACV,YAAM,QAAQ,EAAE,UAAU,WAAW,IAAI,WAAW,SAAS,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,CAAC;AACxG,aAAO,GAAG,EAAE,SAAS,KAAK,EAAE,OAAO,KAAK,KAAK,EAAE,OAAO,IAAI,MAAM,KAAK,KAAK,EAAE,OAAO,UAAU;AAAA,IAC/F,CAAC,EACA,KAAK,IAAI;AACZ,QAAI,OAAO,SAAS,GAAG;AACrB,iBAAW,aAAa,OAAO,IAAI,CAAC,MAAM,GAAG,EAAE,SAAS,KAAK,EAAE,MAAM,IAAI,KAAK,EAAE,MAAM,OAAO,GAAG,EAAE,KAAK,IAAI,CAAC;AAAA,IAC9G;AACA,WAAO,WAAW,SAAS,OAAO,SAAS,IAAI,EAAC,SAAS,OAAM,IAAI,EAAC,QAAO,CAAC;AAAA,EAC9E,CAAC;AACH,CAAC;",
+  "names": []
+}

package/src/model-context/tools/getEntityTree.d.ts

@@ -0,0 +1,4 @@
+import type { ModelContextToolLike } from '../ModelContextLike.js';
+import { type ToolContext } from '../toolSupport.js';
+export declare const createGetEntityTreeTool: (ctx: ToolContext) => ModelContextToolLike;
+//# sourceMappingURL=getEntityTree.d.ts.map

package/src/model-context/tools/getEntityTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getEntityTree.d.ts","sourceRoot":"","sources":["../../../../src/model-context/tools/getEntityTree.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AACjE,OAAO,EASL,KAAK,WAAW,EAEjB,MAAM,mBAAmB,CAAC;AAE3B,eAAO,MAAM,uBAAuB,QAAS,WAAW,KAAG,oBAgDvD,CAAC"}

package/src/model-context/tools/getEntityTree.js

@@ -0,0 +1,58 @@
+import {
+  buildRequest,
+  defineTool,
+  describeEnv,
+  inspectEnvs,
+  NamespaceInputSchema,
+  NoEnvironments,
+  readInclude,
+  runTool,
+  textResult
+} from "../toolSupport.js";
+const createGetEntityTreeTool = (ctx) => defineTool(ctx, "get-entity-tree", {
+  title: "Get Entity Tree",
+  description: "The Entity Tree of one Shadow Environment, or of every one: per Entity its token, properties, Shadow Objects and Entity Contexts, next to the View's component tree of the same namespace. A cut walk carries truncation notes naming the uuids where it stopped; descend from there with rootUuid.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      namespace: NamespaceInputSchema,
+      rootUuid: { type: "string", description: "Descend from this Entity instead of the roots." },
+      maxDepth: { type: "integer", minimum: 0, description: "Tree depth below each root that is walked. Default 4." },
+      maxNodes: { type: "integer", minimum: 1, description: "Total number of Entities across the walk. Default 250." },
+      include: {
+        type: "array",
+        items: { type: "string", enum: ["props", "shadowObjects", "contexts", "registry"] },
+        description: "What to carry per Entity. Default: all four."
+      },
+      valueDepth: {
+        type: "integer",
+        minimum: 0,
+        description: "How deep nested property and context values are followed. Default 3."
+      }
+    },
+    additionalProperties: false
+  },
+  execute: runTool(async (input, signal) => {
+    const own = {};
+    const rootUuid = input.string("rootUuid");
+    if (rootUuid !== void 0) own.rootUuids = [rootUuid];
+    const maxDepth = input.number("maxDepth");
+    if (maxDepth !== void 0) own.maxDepth = maxDepth;
+    const maxNodes = input.number("maxNodes");
+    if (maxNodes !== void 0) own.maxNodes = maxNodes;
+    const include = readInclude(input);
+    if (include !== void 0) own.include = include;
+    const valueDepth = input.number("valueDepth");
+    if (valueDepth !== void 0) own.values = { maxDepth: valueDepth };
+    const envs = await inspectEnvs(input.string("namespace"), buildRequest(ctx.limits, own), signal, ctx);
+    const summary = envs.map((s) => {
+      const cut = s.kernel?.truncation?.length ?? 0;
+      return cut === 0 ? describeEnv(s) : `${describeEnv(s)}, ${cut} truncation note${cut === 1 ? "" : "s"}`;
+    }).join("; ");
+    return textResult(summary || NoEnvironments, { envs });
+  })
+});
+export {
+  createGetEntityTreeTool
+};
+//# sourceMappingURL=getEntityTree.js.map

package/src/model-context/tools/getEntityTree.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/model-context/tools/getEntityTree.ts"],
+  "sourcesContent": ["import type {InspectRequest} from '../../inspect/types.js';\nimport type {ModelContextToolLike} from '../ModelContextLike.js';\nimport {\n  buildRequest,\n  defineTool,\n  describeEnv,\n  inspectEnvs,\n  NamespaceInputSchema,\n  NoEnvironments,\n  readInclude,\n  runTool,\n  type ToolContext,\n  textResult,\n} from '../toolSupport.js';\n\nexport const createGetEntityTreeTool = (ctx: ToolContext): ModelContextToolLike =>\n  defineTool(ctx, 'get-entity-tree', {\n    title: 'Get Entity Tree',\n    description:\n      \"The Entity Tree of one Shadow Environment, or of every one: per Entity its token, properties, Shadow Objects and Entity Contexts, next to the View's component tree of the same namespace. A cut walk carries truncation notes naming the uuids where it stopped; descend from there with rootUuid.\",\n    inputSchema: {\n      type: 'object',\n      properties: {\n        namespace: NamespaceInputSchema,\n        rootUuid: {type: 'string', description: 'Descend from this Entity instead of the roots.'},\n        maxDepth: {type: 'integer', minimum: 0, description: 'Tree depth below each root that is walked. Default 4.'},\n        maxNodes: {type: 'integer', minimum: 1, description: 'Total number of Entities across the walk. Default 250.'},\n        include: {\n          type: 'array',\n          items: {type: 'string', enum: ['props', 'shadowObjects', 'contexts', 'registry']},\n          description: 'What to carry per Entity. Default: all four.',\n        },\n        valueDepth: {\n          type: 'integer',\n          minimum: 0,\n          description: 'How deep nested property and context values are followed. Default 3.',\n        },\n      },\n      additionalProperties: false,\n    },\n    execute: runTool(async (input, signal) => {\n      const own: InspectRequest = {};\n      const rootUuid = input.string('rootUuid');\n      if (rootUuid !== undefined) own.rootUuids = [rootUuid];\n      const maxDepth = input.number('maxDepth');\n      if (maxDepth !== undefined) own.maxDepth = maxDepth;\n      const maxNodes = input.number('maxNodes');\n      if (maxNodes !== undefined) own.maxNodes = maxNodes;\n      const include = readInclude(input);\n      if (include !== undefined) own.include = include;\n      const valueDepth = input.number('valueDepth');\n      if (valueDepth !== undefined) own.values = {maxDepth: valueDepth};\n\n      const envs = await inspectEnvs(input.string('namespace'), buildRequest(ctx.limits, own), signal, ctx);\n\n      const summary = envs\n        .map((s) => {\n          const cut = s.kernel?.truncation?.length ?? 0;\n          return cut === 0 ? describeEnv(s) : `${describeEnv(s)}, ${cut} truncation note${cut === 1 ? '' : 's'}`;\n        })\n        .join('; ');\n      return textResult(summary || NoEnvironments, {envs});\n    }),\n  });\n"],
+  "mappings": "AAEA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEA;AAAA,OACK;AAEA,MAAM,0BAA0B,CAAC,QACtC,WAAW,KAAK,mBAAmB;AAAA,EACjC,OAAO;AAAA,EACP,aACE;AAAA,EACF,aAAa;AAAA,IACX,MAAM;AAAA,IACN,YAAY;AAAA,MACV,WAAW;AAAA,MACX,UAAU,EAAC,MAAM,UAAU,aAAa,iDAAgD;AAAA,MACxF,UAAU,EAAC,MAAM,WAAW,SAAS,GAAG,aAAa,wDAAuD;AAAA,MAC5G,UAAU,EAAC,MAAM,WAAW,SAAS,GAAG,aAAa,yDAAwD;AAAA,MAC7G,SAAS;AAAA,QACP,MAAM;AAAA,QACN,OAAO,EAAC,MAAM,UAAU,MAAM,CAAC,SAAS,iBAAiB,YAAY,UAAU,EAAC;AAAA,QAChF,aAAa;AAAA,MACf;AAAA,MACA,YAAY;AAAA,QACV,MAAM;AAAA,QACN,SAAS;AAAA,QACT,aAAa;AAAA,MACf;AAAA,IACF;AAAA,IACA,sBAAsB;AAAA,EACxB;AAAA,EACA,SAAS,QAAQ,OAAO,OAAO,WAAW;AACxC,UAAM,MAAsB,CAAC;AAC7B,UAAM,WAAW,MAAM,OAAO,UAAU;AACxC,QAAI,aAAa,OAAW,KAAI,YAAY,CAAC,QAAQ;AACrD,UAAM,WAAW,MAAM,OAAO,UAAU;AACxC,QAAI,aAAa,OAAW,KAAI,WAAW;AAC3C,UAAM,WAAW,MAAM,OAAO,UAAU;AACxC,QAAI,aAAa,OAAW,KAAI,WAAW;AAC3C,UAAM,UAAU,YAAY,KAAK;AACjC,QAAI,YAAY,OAAW,KAAI,UAAU;AACzC,UAAM,aAAa,MAAM,OAAO,YAAY;AAC5C,QAAI,eAAe,OAAW,KAAI,SAAS,EAAC,UAAU,WAAU;AAEhE,UAAM,OAAO,MAAM,YAAY,MAAM,OAAO,WAAW,GAAG,aAAa,IAAI,QAAQ,GAAG,GAAG,QAAQ,GAAG;AAEpG,UAAM,UAAU,KACb,IAAI,CAAC,MAAM;AACV,YAAM,MAAM,EAAE,QAAQ,YAAY,UAAU;AAC5C,aAAO,QAAQ,IAAI,YAAY,CAAC,IAAI,GAAG,YAAY,CAAC,CAAC,KAAK,GAAG,mBAAmB,QAAQ,IAAI,KAAK,GAAG;AAAA,IACtG,CAAC,EACA,KAAK,IAAI;AACZ,WAAO,WAAW,WAAW,gBAAgB,EAAC,KAAI,CAAC;AAAA,EACrD,CAAC;AACH,CAAC;",
+  "names": []
+}

package/src/model-context/tools/getRegistry.d.ts

@@ -0,0 +1,14 @@
+import type { EnvSnapshot, RegistrySnapshot } from '../../inspect/types.js';
+import type { ModelContextToolLike } from '../ModelContextLike.js';
+import { type ToolContext } from '../toolSupport.js';
+export interface RegistryEntry {
+    namespace: string;
+    kind: EnvSnapshot['kind'];
+    registry?: RegistrySnapshot;
+    error?: {
+        name: string;
+        message: string;
+    };
+}
+export declare const createGetRegistryTool: (ctx: ToolContext) => ModelContextToolLike;
+//# sourceMappingURL=getRegistry.d.ts.map

package/src/model-context/tools/getRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getRegistry.d.ts","sourceRoot":"","sources":["../../../../src/model-context/tools/getRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,WAAW,EAAE,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AAC1E,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAOL,KAAK,WAAW,EAEjB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1B,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,KAAK,CAAC,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CAAC;CACzC;AAED,eAAO,MAAM,qBAAqB,QAAS,WAAW,KAAG,oBA+BrD,CAAC"}

package/src/model-context/tools/getRegistry.js

@@ -0,0 +1,39 @@
+import {
+  buildRequest,
+  defineTool,
+  inspectEnvs,
+  NamespaceInputSchema,
+  NoEnvironments,
+  runTool,
+  textResult
+} from "../toolSupport.js";
+const createGetRegistryTool = (ctx) => defineTool(ctx, "get-registry", {
+  title: "Get Registry",
+  description: "The composition rules of one Shadow Environment, or of every one: which Shadow Objects each token defines, which tokens a token routes to, and which property routes exist. The answer to why a Shadow Object is, or is not, on an Entity.",
+  inputSchema: { type: "object", properties: { namespace: NamespaceInputSchema }, additionalProperties: false },
+  execute: runTool(async (input, signal) => {
+    const envs = await inspectEnvs(
+      input.string("namespace"),
+      buildRequest(ctx.limits, { maxDepth: 0, maxNodes: 1, include: ["registry"] }),
+      signal,
+      ctx
+    );
+    const registries = envs.map((s) => {
+      const entry = { namespace: s.namespace, kind: s.kind };
+      if (s.kernel?.registry !== void 0) entry.registry = s.kernel.registry;
+      if (s.error !== void 0) entry.error = s.error;
+      return entry;
+    });
+    const summary = registries.map((r) => {
+      if (r.registry === void 0)
+        return `${r.namespace}: no registry${r.error === void 0 ? "" : ` (error: ${r.error.name}: ${r.error.message})`}`;
+      const { tokens, routes, propRoutes, isDefault } = r.registry;
+      return `${r.namespace}: ${Object.keys(tokens).length} tokens, ${Object.keys(routes).length} routes, ${Object.keys(propRoutes).length} property routes${isDefault ? ", the default registry" : ""}`;
+    }).join("; ");
+    return textResult(summary || NoEnvironments, { registries });
+  })
+});
+export {
+  createGetRegistryTool
+};
+//# sourceMappingURL=getRegistry.js.map

package/src/model-context/tools/getRegistry.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/model-context/tools/getRegistry.ts"],
+  "sourcesContent": ["import type {EnvSnapshot, RegistrySnapshot} from '../../inspect/types.js';\nimport type {ModelContextToolLike} from '../ModelContextLike.js';\nimport {\n  buildRequest,\n  defineTool,\n  inspectEnvs,\n  NamespaceInputSchema,\n  NoEnvironments,\n  runTool,\n  type ToolContext,\n  textResult,\n} from '../toolSupport.js';\n\nexport interface RegistryEntry {\n  namespace: string;\n  kind: EnvSnapshot['kind'];\n  registry?: RegistrySnapshot;\n  error?: {name: string; message: string};\n}\n\nexport const createGetRegistryTool = (ctx: ToolContext): ModelContextToolLike =>\n  defineTool(ctx, 'get-registry', {\n    title: 'Get Registry',\n    description:\n      'The composition rules of one Shadow Environment, or of every one: which Shadow Objects each token defines, which tokens a token routes to, and which property routes exist. The answer to why a Shadow Object is, or is not, on an Entity.',\n    inputSchema: {type: 'object', properties: {namespace: NamespaceInputSchema}, additionalProperties: false},\n    execute: runTool(async (input, signal) => {\n      const envs = await inspectEnvs(\n        input.string('namespace'),\n        buildRequest(ctx.limits, {maxDepth: 0, maxNodes: 1, include: ['registry']}),\n        signal,\n        ctx,\n      );\n\n      const registries = envs.map((s) => {\n        const entry: RegistryEntry = {namespace: s.namespace, kind: s.kind};\n        if (s.kernel?.registry !== undefined) entry.registry = s.kernel.registry;\n        if (s.error !== undefined) entry.error = s.error;\n        return entry;\n      });\n\n      const summary = registries\n        .map((r) => {\n          if (r.registry === undefined)\n            return `${r.namespace}: no registry${r.error === undefined ? '' : ` (error: ${r.error.name}: ${r.error.message})`}`;\n          const {tokens, routes, propRoutes, isDefault} = r.registry;\n          return `${r.namespace}: ${Object.keys(tokens).length} tokens, ${Object.keys(routes).length} routes, ${Object.keys(propRoutes).length} property routes${isDefault ? ', the default registry' : ''}`;\n        })\n        .join('; ');\n      return textResult(summary || NoEnvironments, {registries});\n    }),\n  });\n"],
+  "mappings": "AAEA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEA;AAAA,OACK;AASA,MAAM,wBAAwB,CAAC,QACpC,WAAW,KAAK,gBAAgB;AAAA,EAC9B,OAAO;AAAA,EACP,aACE;AAAA,EACF,aAAa,EAAC,MAAM,UAAU,YAAY,EAAC,WAAW,qBAAoB,GAAG,sBAAsB,MAAK;AAAA,EACxG,SAAS,QAAQ,OAAO,OAAO,WAAW;AACxC,UAAM,OAAO,MAAM;AAAA,MACjB,MAAM,OAAO,WAAW;AAAA,MACxB,aAAa,IAAI,QAAQ,EAAC,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC,UAAU,EAAC,CAAC;AAAA,MAC1E;AAAA,MACA;AAAA,IACF;AAEA,UAAM,aAAa,KAAK,IAAI,CAAC,MAAM;AACjC,YAAM,QAAuB,EAAC,WAAW,EAAE,WAAW,MAAM,EAAE,KAAI;AAClE,UAAI,EAAE,QAAQ,aAAa,OAAW,OAAM,WAAW,EAAE,OAAO;AAChE,UAAI,EAAE,UAAU,OAAW,OAAM,QAAQ,EAAE;AAC3C,aAAO;AAAA,IACT,CAAC;AAED,UAAM,UAAU,WACb,IAAI,CAAC,MAAM;AACV,UAAI,EAAE,aAAa;AACjB,eAAO,GAAG,EAAE,SAAS,gBAAgB,EAAE,UAAU,SAAY,KAAK,YAAY,EAAE,MAAM,IAAI,KAAK,EAAE,MAAM,OAAO,GAAG;AACnH,YAAM,EAAC,QAAQ,QAAQ,YAAY,UAAS,IAAI,EAAE;AAClD,aAAO,GAAG,EAAE,SAAS,KAAK,OAAO,KAAK,MAAM,EAAE,MAAM,YAAY,OAAO,KAAK,MAAM,EAAE,MAAM,YAAY,OAAO,KAAK,UAAU,EAAE,MAAM,mBAAmB,YAAY,2BAA2B,EAAE;AAAA,IAClM,CAAC,EACA,KAAK,IAAI;AACZ,WAAO,WAAW,WAAW,gBAAgB,EAAC,WAAU,CAAC;AAAA,EAC3D,CAAC;AACH,CAAC;",
+  "names": []
+}

package/src/model-context/tools/index.d.ts

@@ -0,0 +1,9 @@
+import type { ModelContextToolLike } from '../ModelContextLike.js';
+import type { ToolContext } from '../toolSupport.js';
+export type { FindEntitiesEntry } from './findEntities.js';
+export type { EntityMatchEntry } from './getEntity.js';
+export type { RegistryEntry } from './getRegistry.js';
+export type { EnvSummary } from './listEnvs.js';
+/** The five read-only tools, in the order they are registered. */
+export declare const createTools: (ctx: ToolContext) => ModelContextToolLike[];
+//# sourceMappingURL=index.d.ts.map

package/src/model-context/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/model-context/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAOnD,YAAY,EAAC,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AACzD,YAAY,EAAC,gBAAgB,EAAC,MAAM,gBAAgB,CAAC;AACrD,YAAY,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAC,UAAU,EAAC,MAAM,eAAe,CAAC;AAE9C,kEAAkE;AAClE,eAAO,MAAM,WAAW,QAAS,WAAW,KAAG,oBAAoB,EAMlE,CAAC"}

package/src/model-context/tools/index.js

@@ -0,0 +1,16 @@
+import { createFindEntitiesTool } from "./findEntities.js";
+import { createGetEntityTool } from "./getEntity.js";
+import { createGetEntityTreeTool } from "./getEntityTree.js";
+import { createGetRegistryTool } from "./getRegistry.js";
+import { createListEnvsTool } from "./listEnvs.js";
+const createTools = (ctx) => [
+  createListEnvsTool(ctx),
+  createGetEntityTreeTool(ctx),
+  createGetEntityTool(ctx),
+  createFindEntitiesTool(ctx),
+  createGetRegistryTool(ctx)
+];
+export {
+  createTools
+};
+//# sourceMappingURL=index.js.map

package/src/model-context/tools/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/model-context/tools/index.ts"],
+  "sourcesContent": ["import type {ModelContextToolLike} from '../ModelContextLike.js';\nimport type {ToolContext} from '../toolSupport.js';\nimport {createFindEntitiesTool} from './findEntities.js';\nimport {createGetEntityTool} from './getEntity.js';\nimport {createGetEntityTreeTool} from './getEntityTree.js';\nimport {createGetRegistryTool} from './getRegistry.js';\nimport {createListEnvsTool} from './listEnvs.js';\n\nexport type {FindEntitiesEntry} from './findEntities.js';\nexport type {EntityMatchEntry} from './getEntity.js';\nexport type {RegistryEntry} from './getRegistry.js';\nexport type {EnvSummary} from './listEnvs.js';\n\n/** The five read-only tools, in the order they are registered. */\nexport const createTools = (ctx: ToolContext): ModelContextToolLike[] => [\n  createListEnvsTool(ctx),\n  createGetEntityTreeTool(ctx),\n  createGetEntityTool(ctx),\n  createFindEntitiesTool(ctx),\n  createGetRegistryTool(ctx),\n];\n"],
+  "mappings": "AAEA,SAAQ,8BAA6B;AACrC,SAAQ,2BAA0B;AAClC,SAAQ,+BAA8B;AACtC,SAAQ,6BAA4B;AACpC,SAAQ,0BAAyB;AAQ1B,MAAM,cAAc,CAAC,QAA6C;AAAA,EACvE,mBAAmB,GAAG;AAAA,EACtB,wBAAwB,GAAG;AAAA,EAC3B,oBAAoB,GAAG;AAAA,EACvB,uBAAuB,GAAG;AAAA,EAC1B,sBAAsB,GAAG;AAC3B;",
+  "names": []
+}

package/src/model-context/tools/listEnvs.d.ts

@@ -0,0 +1,33 @@
+import type { EnvSnapshot } from '../../inspect/types.js';
+import type { ModelContextToolLike } from '../ModelContextLike.js';
+import { type ToolContext } from '../toolSupport.js';
+/** An environment reduced to what a first call needs: identity, state, counts. No tree. */
+export interface EnvSummary {
+    namespace: string;
+    isGlobalNamespace: boolean;
+    kind: EnvSnapshot['kind'];
+    state: EnvSnapshot['state'];
+    view?: {
+        takenAt: number;
+        counts: {
+            components: number;
+            roots: number;
+        };
+    };
+    kernel?: {
+        takenAt: number;
+        thread: 'main' | 'worker';
+        counts: {
+            entities: number;
+            roots: number;
+            shadowObjects: number;
+        };
+    };
+    error?: {
+        name: string;
+        message: string;
+    };
+}
+export declare const toEnvSummary: (s: EnvSnapshot) => EnvSummary;
+export declare const createListEnvsTool: (ctx: ToolContext) => ModelContextToolLike;
+//# sourceMappingURL=listEnvs.d.ts.map

package/src/model-context/tools/listEnvs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listEnvs.d.ts","sourceRoot":"","sources":["../../../../src/model-context/tools/listEnvs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAOL,KAAK,WAAW,EAEjB,MAAM,mBAAmB,CAAC;AAE3B,2FAA2F;AAC3F,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1B,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC5B,IAAI,CAAC,EAAE;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAC,CAAA;KAAC,CAAC;IACtE,MAAM,CAAC,EAAE;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;QAAC,MAAM,EAAE;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,aAAa,EAAE,MAAM,CAAA;SAAC,CAAA;KAAC,CAAC;IACxH,KAAK,CAAC,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CAAC;CACzC;AAED,eAAO,MAAM,YAAY,MAAO,WAAW,KAAG,UAM7C,CAAC;AAEF,eAAO,MAAM,kBAAkB,QAAS,WAAW,KAAG,oBAqBlD,CAAC"}

package/src/model-context/tools/listEnvs.js

@@ -0,0 +1,37 @@
+import {
+  buildRequest,
+  defineTool,
+  describeEnv,
+  inspectEnvs,
+  NoEnvironments,
+  runTool,
+  textResult
+} from "../toolSupport.js";
+const toEnvSummary = (s) => {
+  const summary = { namespace: s.namespace, isGlobalNamespace: s.isGlobalNamespace, kind: s.kind, state: s.state };
+  if (s.view !== void 0) summary.view = { takenAt: s.view.takenAt, counts: s.view.counts };
+  if (s.kernel !== void 0) summary.kernel = { takenAt: s.kernel.takenAt, thread: s.kernel.thread, counts: s.kernel.counts };
+  if (s.error !== void 0) summary.error = s.error;
+  return summary;
+};
+const createListEnvsTool = (ctx) => defineTool(ctx, "list-envs", {
+  title: "List Shadow Environments",
+  description: "Every Shadow Environment on the page: its namespace, kind (local, worker, custom, none), state, and the counts of View components and Kernel Entities. Carries no tree. The cheapest call and the one to make first; every other tool takes a namespace from this list.",
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  execute: runTool(async (_input, signal) => {
+    const snapshots = await inspectEnvs(
+      void 0,
+      buildRequest(ctx.limits, { maxDepth: 0, maxNodes: 1, include: [] }),
+      signal,
+      ctx
+    );
+    const envs = snapshots.map(toEnvSummary);
+    const summary = envs.length === 0 ? NoEnvironments : `${envs.length} Shadow Environment${envs.length === 1 ? "" : "s"}: ${snapshots.map(describeEnv).join("; ")}`;
+    return textResult(summary, { envs });
+  })
+});
+export {
+  createListEnvsTool,
+  toEnvSummary
+};
+//# sourceMappingURL=listEnvs.js.map

package/src/model-context/tools/listEnvs.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/model-context/tools/listEnvs.ts"],
+  "sourcesContent": ["import type {EnvSnapshot} from '../../inspect/types.js';\nimport type {ModelContextToolLike} from '../ModelContextLike.js';\nimport {\n  buildRequest,\n  defineTool,\n  describeEnv,\n  inspectEnvs,\n  NoEnvironments,\n  runTool,\n  type ToolContext,\n  textResult,\n} from '../toolSupport.js';\n\n/** An environment reduced to what a first call needs: identity, state, counts. No tree. */\nexport interface EnvSummary {\n  namespace: string;\n  isGlobalNamespace: boolean;\n  kind: EnvSnapshot['kind'];\n  state: EnvSnapshot['state'];\n  view?: {takenAt: number; counts: {components: number; roots: number}};\n  kernel?: {takenAt: number; thread: 'main' | 'worker'; counts: {entities: number; roots: number; shadowObjects: number}};\n  error?: {name: string; message: string};\n}\n\nexport const toEnvSummary = (s: EnvSnapshot): EnvSummary => {\n  const summary: EnvSummary = {namespace: s.namespace, isGlobalNamespace: s.isGlobalNamespace, kind: s.kind, state: s.state};\n  if (s.view !== undefined) summary.view = {takenAt: s.view.takenAt, counts: s.view.counts};\n  if (s.kernel !== undefined) summary.kernel = {takenAt: s.kernel.takenAt, thread: s.kernel.thread, counts: s.kernel.counts};\n  if (s.error !== undefined) summary.error = s.error;\n  return summary;\n};\n\nexport const createListEnvsTool = (ctx: ToolContext): ModelContextToolLike =>\n  defineTool(ctx, 'list-envs', {\n    title: 'List Shadow Environments',\n    description:\n      'Every Shadow Environment on the page: its namespace, kind (local, worker, custom, none), state, and the counts of View components and Kernel Entities. Carries no tree. The cheapest call and the one to make first; every other tool takes a namespace from this list.',\n    inputSchema: {type: 'object', properties: {}, additionalProperties: false},\n    execute: runTool(async (_input, signal) => {\n      // the counts are computed over the whole kernel regardless of the walk, so the walk is cut to nothing\n      const snapshots = await inspectEnvs(\n        undefined,\n        buildRequest(ctx.limits, {maxDepth: 0, maxNodes: 1, include: []}),\n        signal,\n        ctx,\n      );\n      const envs = snapshots.map(toEnvSummary);\n      const summary =\n        envs.length === 0\n          ? NoEnvironments\n          : `${envs.length} Shadow Environment${envs.length === 1 ? '' : 's'}: ${snapshots.map(describeEnv).join('; ')}`;\n      return textResult(summary, {envs});\n    }),\n  });\n"],
+  "mappings": "AAEA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEA;AAAA,OACK;AAaA,MAAM,eAAe,CAAC,MAA+B;AAC1D,QAAM,UAAsB,EAAC,WAAW,EAAE,WAAW,mBAAmB,EAAE,mBAAmB,MAAM,EAAE,MAAM,OAAO,EAAE,MAAK;AACzH,MAAI,EAAE,SAAS,OAAW,SAAQ,OAAO,EAAC,SAAS,EAAE,KAAK,SAAS,QAAQ,EAAE,KAAK,OAAM;AACxF,MAAI,EAAE,WAAW,OAAW,SAAQ,SAAS,EAAC,SAAS,EAAE,OAAO,SAAS,QAAQ,EAAE,OAAO,QAAQ,QAAQ,EAAE,OAAO,OAAM;AACzH,MAAI,EAAE,UAAU,OAAW,SAAQ,QAAQ,EAAE;AAC7C,SAAO;AACT;AAEO,MAAM,qBAAqB,CAAC,QACjC,WAAW,KAAK,aAAa;AAAA,EAC3B,OAAO;AAAA,EACP,aACE;AAAA,EACF,aAAa,EAAC,MAAM,UAAU,YAAY,CAAC,GAAG,sBAAsB,MAAK;AAAA,EACzE,SAAS,QAAQ,OAAO,QAAQ,WAAW;AAEzC,UAAM,YAAY,MAAM;AAAA,MACtB;AAAA,MACA,aAAa,IAAI,QAAQ,EAAC,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC,EAAC,CAAC;AAAA,MAChE;AAAA,MACA;AAAA,IACF;AACA,UAAM,OAAO,UAAU,IAAI,YAAY;AACvC,UAAM,UACJ,KAAK,WAAW,IACZ,iBACA,GAAG,KAAK,MAAM,sBAAsB,KAAK,WAAW,IAAI,KAAK,GAAG,KAAK,UAAU,IAAI,WAAW,EAAE,KAAK,IAAI,CAAC;AAChH,WAAO,WAAW,SAAS,EAAC,KAAI,CAAC;AAAA,EACnC,CAAC;AACH,CAAC;",
+  "names": []
+}

package/src/model-context.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The model-context layer of the inspection API: one function that registers five read-only
+ * tools on `document.modelContext` (WebMCP), the structural contract it talks to the platform
+ * through, and the types of both. A subpath rather than an `index.ts` export: this module
+ * touches `document` when called, and stays out of the worker bundle and out of every consumer
+ * that does not want it. Importing it throws nowhere -- the platform is read only inside a call.
+ */
+export { DefaultToolPrefix, type ExposeHandle, type ExposeOptions, exposeShadowEnvsToModelContext, } from './model-context/exposeShadowEnvsToModelContext.js';
+export { findModelContext, isModelContextLike, type ModelContextLike, type ModelContextRegisterOptions, type ModelContextToolAnnotations, type ModelContextToolLike, type ModelContextToolResult, } from './model-context/ModelContextLike.js';
+export type { RedactRule } from './model-context/redactProps.js';
+export type { NamespaceRule } from './model-context/toolSupport.js';
+export type { EntityMatchEntry, EnvSummary, FindEntitiesEntry, RegistryEntry } from './model-context/tools/index.js';
+//# sourceMappingURL=model-context.d.ts.map

package/src/model-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-context.d.ts","sourceRoot":"","sources":["../../src/model-context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,iBAAiB,EACjB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,8BAA8B,GAC/B,MAAM,mDAAmD,CAAC;AAC3D,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EAChC,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,GAC5B,MAAM,qCAAqC,CAAC;AAC7C,YAAY,EAAC,UAAU,EAAC,MAAM,gCAAgC,CAAC;AAC/D,YAAY,EAAC,aAAa,EAAC,MAAM,gCAAgC,CAAC;AAClE,YAAY,EAAC,gBAAgB,EAAE,UAAU,EAAE,iBAAiB,EAAE,aAAa,EAAC,MAAM,gCAAgC,CAAC"}

package/src/model-context.js

@@ -0,0 +1,15 @@
+import {
+  DefaultToolPrefix,
+  exposeShadowEnvsToModelContext
+} from "./model-context/exposeShadowEnvsToModelContext.js";
+import {
+  findModelContext,
+  isModelContextLike
+} from "./model-context/ModelContextLike.js";
+export {
+  DefaultToolPrefix,
+  exposeShadowEnvsToModelContext,
+  findModelContext,
+  isModelContextLike
+};
+//# sourceMappingURL=model-context.js.map

package/src/model-context.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/model-context.ts"],
+  "sourcesContent": ["/**\n * The model-context layer of the inspection API: one function that registers five read-only\n * tools on `document.modelContext` (WebMCP), the structural contract it talks to the platform\n * through, and the types of both. A subpath rather than an `index.ts` export: this module\n * touches `document` when called, and stays out of the worker bundle and out of every consumer\n * that does not want it. Importing it throws nowhere -- the platform is read only inside a call.\n */\nexport {\n  DefaultToolPrefix,\n  type ExposeHandle,\n  type ExposeOptions,\n  exposeShadowEnvsToModelContext,\n} from './model-context/exposeShadowEnvsToModelContext.js';\nexport {\n  findModelContext,\n  isModelContextLike,\n  type ModelContextLike,\n  type ModelContextRegisterOptions,\n  type ModelContextToolAnnotations,\n  type ModelContextToolLike,\n  type ModelContextToolResult,\n} from './model-context/ModelContextLike.js';\nexport type {RedactRule} from './model-context/redactProps.js';\nexport type {NamespaceRule} from './model-context/toolSupport.js';\nexport type {EntityMatchEntry, EnvSummary, FindEntitiesEntry, RegistryEntry} from './model-context/tools/index.js';\n"],
+  "mappings": "AAOA;AAAA,EACE;AAAA,EAGA;AAAA,OACK;AACP;AAAA,EACE;AAAA,EACA;AAAA,OAMK;",
+  "names": []
+}

package/src/shadow-objects.d.ts

@@ -5,5 +5,7 @@ export * from './in-the-dark/events.js';
 export * from './in-the-dark/Kernel.js';
 export * from './in-the-dark/Registry.js';
 export * from './in-the-dark/ShadowObject.js';
+export { createKernelSnapshot } from './inspect/createKernelSnapshot.js';
+export type * from './inspect/types.js';
 export type * from './types.js';
 //# sourceMappingURL=shadow-objects.d.ts.map

package/src/shadow-objects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shadow-objects.d.ts","sourceRoot":"","sources":["../../src/shadow-objects.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,mBAAmB,YAAY,CAAC"}
+{"version":3,"file":"shadow-objects.d.ts","sourceRoot":"","sources":["../../src/shadow-objects.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,OAAO,EAAC,oBAAoB,EAAC,MAAM,mCAAmC,CAAC;AACvE,mBAAmB,oBAAoB,CAAC;AACxC,mBAAmB,YAAY,CAAC"}

package/src/shadow-objects.js

@@ -5,4 +5,8 @@ export * from "./in-the-dark/events.js";
 export * from "./in-the-dark/Kernel.js";
 export * from "./in-the-dark/Registry.js";
 export * from "./in-the-dark/ShadowObject.js";
+import { createKernelSnapshot } from "./inspect/createKernelSnapshot.js";
+export {
+  createKernelSnapshot
+};
 //# sourceMappingURL=shadow-objects.js.map

package/src/shadow-objects.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/shadow-objects.ts"],
-  "sourcesContent": ["export * from './ChangeTrailRefusedError.js';\nexport * from './constants.js';\nexport * from './EntityUuidInUseError.js';\nexport * from './in-the-dark/events.js';\nexport * from './in-the-dark/Kernel.js';\nexport * from './in-the-dark/Registry.js';\nexport * from './in-the-dark/ShadowObject.js';\nexport type * from './types.js';\n"],
-  "mappings": "AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;",
+  "sourcesContent": ["export * from './ChangeTrailRefusedError.js';\nexport * from './constants.js';\nexport * from './EntityUuidInUseError.js';\nexport * from './in-the-dark/events.js';\nexport * from './in-the-dark/Kernel.js';\nexport * from './in-the-dark/Registry.js';\nexport * from './in-the-dark/ShadowObject.js';\nexport {createKernelSnapshot} from './inspect/createKernelSnapshot.js';\nexport type * from './inspect/types.js';\nexport type * from './types.js';\n"],
+  "mappings": "AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,SAAQ,4BAA2B;",
   "names": []
 }

package/src/testing/TestEntity.d.ts

@@ -0,0 +1,79 @@
+import type { Entity } from '../in-the-dark/Entity.js';
+import type { Kernel } from '../in-the-dark/Kernel.js';
+import type { ComponentPropertiesType, ShadowObjectDescription, ShadowObjectType } from '../types.js';
+import type { AnyShadowObjectConstructor, CreateEntityOptions, ShadowObjectInstance, TestEntity, ViewMessageRecord } from './types.js';
+/** What a `TestEntityImpl` needs from the test kernel that owns it. */
+export interface TestKernelInternals {
+    readonly kernel: Kernel;
+    createEntity(token: string, props?: Record<string, unknown>, options?: CreateEntityOptions): TestEntity;
+    /** What the test kernel recorded for a uuid. The log is its own, so a handle never holds one. */
+    viewMessagesOf(uuid: string): readonly ViewMessageRecord[];
+    clearViewMessagesOf(uuid: string): void;
+}
+/**
+ * Properties as a Kernel call wants them. `Object.entries()` drops symbol keys, which is right:
+ * an Entity property is string-keyed. A value of `undefined` is a removal, which is what
+ * `types.ts` says about a `ComponentPropertiesType` entry and what `removeProps()` relies on.
+ */
+export declare const toPropertyEntries: (props: Record<string, unknown>) => ComponentPropertiesType;
+export declare class TestEntityImpl implements TestEntity {
+    #private;
+    readonly uuid: string;
+    constructor(testKernel: TestKernelInternals, uuid: string, token: string);
+    get entity(): Entity;
+    get token(): string;
+    /**
+     * A view onto the test kernel's own log, the way `token` and `entity` are views onto the Kernel.
+     * The handle stores nothing: a message is recorded for a uuid whether or not a handle for it
+     * existed at the time, so a handle built later answers for everything that Entity already sent.
+     */
+    get viewMessages(): readonly ViewMessageRecord[];
+    createChild(token: string, props?: Record<string, unknown>, options?: Omit<CreateEntityOptions, 'parent'>): TestEntity;
+    /**
+     * Writes through the Kernel rather than through `Entity.setProperties()`: `changeProperties()`
+     * re-resolves the constructor set afterwards, which is how a property route -- `token@prop` in a
+     * module's `routes` -- puts a Shadow Object on an Entity or takes it off again.
+     */
+    setProps(props: Record<string, unknown>): void;
+    /** A property set to `undefined` is a removal; see `ComponentPropertiesType` in `src/types.ts`. */
+    removeProps(...names: string[]): void;
+    readProp<T = unknown>(name: string): T | undefined;
+    /**
+     * The effective value of an Entity Context, the one `useContext()` reads. It arrives a microtask
+     * after a provider wrote it -- `Entity` runs every context value through a `MicrotaskCollector` --
+     * so a test reads it after `settle()`.
+     */
+    readContext<T = unknown>(name: string | symbol): T | undefined;
+    setToken(token: string): void;
+    setParent(parent: TestEntity | undefined, order?: number): void;
+    /**
+     * Delivery is synchronous, the way `Kernel.dispatchEventsToEntity()` is: a View event carries no
+     * structure, so nothing has to settle before a Shadow Object hears it.
+     */
+    sendViewEvent(type: string, data?: unknown): void;
+    /**
+     * Emits on the Entity's own event bus. Every Shadow Object of this Entity is attached there as an
+     * eventize listener object, so a method named like the event is what receives it.
+     */
+    emit(eventName: string | symbol, ...args: unknown[]): void;
+    shadowObjects(): ShadowObjectType[];
+    /**
+     * The one Shadow Object on this Entity that came out of `constructa`.
+     *
+     * Two rules in order, because one does not cover both constructor shapes, and because the second
+     * one is not exact. A class instance answers `instanceof` -- the `@ShadowObject` decorator wraps
+     * the class in a subclass, which still does -- and so does an object from a function constructor
+     * that returns nothing. Identity is asked first and, where anything answers it, alone.
+     *
+     * A function constructor that returns an object answers nothing: `new fn()` hands back that
+     * object, and it carries none of `fn`'s prototype. Only there does the display name decide, and
+     * only then, because a name is not an identity. `findShadowObjects()` and
+     * `describeShadowObjects()` walk the same bookkeeping in the same order, so the two lists line up
+     * index by index.
+     */
+    shadowObjectOf<C extends AnyShadowObjectConstructor>(constructa: C): ShadowObjectInstance<C>;
+    describe(): ShadowObjectDescription[];
+    clearViewMessages(): void;
+    destroy(): void;
+}
+//# sourceMappingURL=TestEntity.d.ts.map

package/src/testing/TestEntity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestEntity.d.ts","sourceRoot":"","sources":["../../../src/testing/TestEntity.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,0BAA0B,CAAC;AACrD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,0BAA0B,CAAC;AACrD,OAAO,KAAK,EAAC,uBAAuB,EAA2B,uBAAuB,EAAE,gBAAgB,EAAC,MAAM,aAAa,CAAC;AAC7H,OAAO,KAAK,EACV,0BAA0B,EAC1B,mBAAmB,EACnB,oBAAoB,EACpB,UAAU,EACV,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,UAAU,CAAC;IACxG,iGAAiG;IACjG,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,iBAAiB,EAAE,CAAC;IAC3D,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,UAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,uBACS,CAAC;AAE7E,qBAAa,cAAe,YAAW,UAAU;;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAStB,YAAY,UAAU,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAIvE;IAMD,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,KAAK,IAAI,MAAM,CAMlB;IAED;;;;OAIG;IACH,IAAI,YAAY,IAAI,SAAS,iBAAiB,EAAE,CAE/C;IAED,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,QAAQ,CAAC,GAAG,UAAU,CAErH;IAED;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE7C;IAED,mGAAmG;IACnG,WAAW,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAKpC;IAED,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAEjD;IAED;;;;OAIG;IACH,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,GAAG,SAAS,CAE7D;IAED,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE5B;IAED,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAE9D;IAED;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAEhD;IAED;;;OAGG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAEzD;IAED,aAAa,IAAI,gBAAgB,EAAE,CAElC;IAED;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,CAAC,SAAS,0BAA0B,EAAE,UAAU,EAAE,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CA6B3F;IAED,QAAQ,IAAI,uBAAuB,EAAE,CAEpC;IAED,iBAAiB,IAAI,IAAI,CAExB;IAED,OAAO,IAAI,IAAI,CAEd;CACF"}