@collegium/sdk 0.0.1-beta.7 → 0.0.1-beta.9

package/README.md

@@ -38,10 +38,10 @@ export default defineTool({
   approval: (args) => ({ body: `save contact "${args.id}": ${args.name}`, presentation: 'verbatim' }),
   description: 'Save or update a contact.',
   execute: async (args, { err, settings, storage }) => {
-    if ((await storage.contacts.list()).length >= settings.maxContacts) {
+    if ((await storage.contacts.findMany()).length >= settings.maxContacts) {
       err.invalidArguments('contact limit reached; delete one first');
     }
-    await storage.contacts.put(args.id, { email: args.email, name: args.name });
+    await storage.contacts.create({ email: args.email, id: args.id, name: args.name });
     return `contact ${args.id} saved`;
   },
   parameters: z.object({ email: z.email(), id: z.string().min(1), name: z.string().min(1) })
@@ -50,6 +50,20 @@ export default defineTool({
 
 A tool with `approval` always stops for a human, who sees the full payload before it runs; one without never gates. The channel and the trace disclose both, line by line. `execute` returns the text the model reads, and raises the two failures a tool controls through `err`: `invalidArguments` continues the turn, `unresolved` ends it as an unconfirmed side effect.
 
+**Storage.** Each declared collection is a set of records: the schema's output plus `id`, `createdAt`, and `updatedAt`, which the store stamps. The handle has `create`, `findMany`, `findById`, `updateById`, and `deleteById`. `create` takes the schema's input with an optional `id`, minting a cuid2 when none is given. `findMany` with no argument lists everything; with a `where` over the schema's top-level scalar fields and `id` — a value for equality, `{ in: [...] }` for membership, `{ contains: text }` for a case-insensitive substring on a string — and an optional `limit`, it filters. Field names and value types come from the schema, so a bad query does not compile.
+
+**Testing.** `@collegium/sdk/testing` builds the context `execute` receives, over in-memory storage that validates and parses as the deployment's store does. Pass your config; settings go through your schema, so defaults apply.
+
+```ts
+import { createTestContext, PluginToolFailureError } from '@collegium/sdk/testing';
+
+const context = createTestContext(config, { settings: { maxContacts: 1 } });
+await save.execute({ email: 'ana@example.com', id: 'ana', name: 'Ana' }, context);
+await expect(save.execute({ email: 'ben@example.com', id: 'ben', name: 'Ben' }, context)).rejects.toThrow(
+  PluginToolFailureError
+);
+```
+
 **zod is a peer dependency.** Install it beside the SDK and import it directly. A plugin may import `@collegium/sdk`, `zod`, and `node:` builtins; the compiler refuses every other bare specifier at boot.
 
 **Your installed copies are for development.** The deployment compiles a mounted plugin against the SDK and zod its image carries, not the copies in your `node_modules` — those serve your editor, `tsc`, and your tests. Exactly one zod runs in the process.

package/dist/index.d.ts

@@ -1,151 +1,2 @@
-import { z } from "zod";
-import { Promisable } from "type-fest";
-//#region src/config.d.ts
-type CollectionsDeclaration$1 = {
-  readonly [key: string]: z.ZodType;
-};
-/**
- * The config file's default export: the settings schema agents are configured by, and the storage
- * collections the plugin owns. Its generics are what carry the settings and storage types to every
- * tool, through `Register`.
- */
-type PluginConfig<TSettings extends undefined | z.ZodType = undefined | z.ZodType, TCollections extends CollectionsDeclaration$1 = CollectionsDeclaration$1> = {
-  readonly settings: TSettings;
-  readonly storage: TCollections;
-};
-/**
- * The augmentation point. `src/config.ts` declares its config here, and every tool file receives
- * the declared settings and storage types without importing the config:
- *
- * ```ts
- * declare module '@collegium/sdk' {
- *   interface Register { config: typeof config }
- * }
- * ```
- */
-interface Register {}
-type RegisteredConfig = Register extends {
-  readonly config: infer TConfig extends PluginConfig;
-} ? TConfig : PluginConfig;
-declare function defineConfig<TSettings extends undefined | z.ZodType = undefined, const TCollections extends CollectionsDeclaration$1 = {}>(config: {
-  readonly settings?: TSettings;
-  readonly storage?: TCollections;
-}): PluginConfig<TSettings, TCollections>;
-//#endregion
-//#region ../core/src/approvals/approvals.types.d.ts
-/** how a gated tool's approval payload is presented (§6.2): collapsed behind a control, or verbatim */
-type ApprovalPayloadPresentation = 'collapse' | 'verbatim';
-//#endregion
-//#region ../core/src/utils/token.utils.d.ts
-declare const SERVICE_INSTANCE: unique symbol;
-/**
- * A NestJS-compatible injection token branded with the instance type it resolves to. Declared in a
- * leaf `<module>.tokens.ts` beside `import type` of the service alone, which is what keeps a
- * toolset declaration inert (§2): the entrypoint and provisioning import one without pulling the
- * service's runtime module into their graphs.
- */
-type ServiceToken<TInstance> = {
-  readonly [SERVICE_INSTANCE]?: TInstance;
-} & symbol;
-//#endregion
-//#region ../core/src/tools/tools.types.d.ts
-/** the four facts of the running turn (§4) — everything else a tool needs, its toolset declares */
-type ToolTurnScope = {
-  readonly agentUsername: string;
-  readonly channelId: string;
-  /** provenance for anything a tool records; null on a turn no post triggered */
-  readonly triggeringPostId: null | string;
-  readonly turnId: string;
-};
-/** §6.2 — the full payload the approver reads; presence of the `approval` hook is what gates a tool (§5) */
-type ToolApprovalPayload = {
-  body: string;
-  presentation: ApprovalPayloadPresentation;
-};
-/**
- * A durable record's disclosure (§3.6), returned by the tool that created it; the turn writes the
- * event and the trace lines. `reference` names the record for later reads, e.g. a memory id.
- */
-type ToolDisclosure = {
-  readonly body: string;
-  readonly description: string;
-  readonly reference: string;
-  readonly supersededDescriptions?: readonly string[];
-};
-//#endregion
-//#region ../core/src/plugins/plugins.types.d.ts
-/** what a plugin tool body may return: the text alone, or the text beside a durable record's disclosure (§3.4) */
-type PluginToolOutput = string | {
-  readonly disclosure?: ToolDisclosure;
-  readonly text: string;
-};
-/**
- * The two failures a tool body may raise itself — the rest of the taxonomy (§7.1) is the
- * framework's to raise. Each throws; the perimeter wrapper maps the throw into the taxonomy.
- */
-type PluginToolErr = {
-  /** the arguments were rejected — returned to the model as the tool result; the turn continues */
-  invalidArguments(message: string): never;
-  /** a committed side effect whose outcome cannot be established; the turn ends stating the ambiguity */
-  unresolved(message: string): never;
-};
-/** one tool as a plugin declares it: the framework's tool minus `budgetExempt`, returning plain output */
-type PluginToolDeclaration<TContext, TParams extends z.ZodType> = {
-  /** present ⇒ the tool always gates (§5); renders the payload the approver reads and cannot decline */
-  approval?(args: z.infer<TParams>): ToolApprovalPayload;
-  readonly description: string;
-  execute(args: z.infer<TParams>, context: TContext): Promisable<PluginToolOutput>;
-  readonly parameters: TParams;
-  /** §7.2 — whether a timed-out call may be reported to the model as a plain failure; false ends the turn as unconfirmable */
-  readonly retryable?: boolean;
-  readonly timeoutMs?: number;
-  /** §8.1 — the one-line summary beside the name in the status post; absent shows the name alone */
-  traceDetail?(args: z.infer<TParams>): string;
-};
-//#endregion
-//#region ../core/src/toolsets/toolsets.types.d.ts
-/** `settings`, `storage`, and `turn` are the context's own keys, so a service may not claim them */
-type ServicesDeclaration = {
-  readonly [key: string]: ServiceToken<unknown>;
-} & {
-  readonly settings?: never;
-  readonly storage?: never;
-  readonly turn?: never;
-};
-type CollectionsDeclaration = {
-  readonly [key: string]: z.ZodType;
-};
-type EmptyDeclaration = {};
-/** a toolset-scoped handle over one declared storage collection; rows are validated on write and parsed on read */
-type ToolsetCollection<TValue> = {
-  delete(key: string): Promise<boolean>;
-  get(key: string): Promise<null | TValue>;
-  list(): Promise<{
-    key: string;
-    value: TValue;
-  }[]>;
-  put(key: string, value: TValue): Promise<void>;
-};
-/**
- * What `execute` receives, assembled from exactly what the toolset declared (§4): each service
- * under its own name, `settings` and `storage` only when declared, and always the turn. Reaching
- * anything undeclared is a compile error.
- */
-type ToolsetContext<TServices extends ServicesDeclaration = EmptyDeclaration, TSettings extends undefined | z.ZodType = undefined, TCollections extends CollectionsDeclaration = EmptyDeclaration> = { readonly [K in keyof TServices]: TServices[K] extends ServiceToken<infer TInstance> ? TInstance : never; } & {
-  readonly turn: ToolTurnScope;
-} & (keyof TCollections extends never ? unknown : {
-  readonly storage: { readonly [K in keyof TCollections]: ToolsetCollection<z.infer<TCollections[K]>>; };
-}) & (TSettings extends z.ZodType ? {
-  readonly settings: z.infer<TSettings>;
-} : unknown);
-//#endregion
-//#region src/tool.d.ts
-/** what `execute` receives: the registered config's settings and storage, the failure raisers, and the four facts of the turn */
-type ToolContext = ToolsetContext<EmptyDeclaration, RegisteredConfig['settings'], RegisteredConfig['storage']> & {
-  readonly err: PluginToolErr;
-};
-type PluginTool<TParams extends z.ZodType> = PluginToolDeclaration<ToolContext, TParams>;
-/** identity at runtime; what it is for is typing `args` from `parameters` across the whole declaration */
-declare function defineTool<TParams extends z.ZodType>(tool: PluginTool<TParams>): PluginTool<TParams>;
-//#endregion
+import { c as ToolTurnScope, d as defineConfig, i as defineTool, n as ToolContext, o as ToolApprovalPayload, s as ToolDisclosure, t as PluginTool, u as Register } from "./tool-Vqe6D48m.js";
 export { type PluginTool, type Register, type ToolApprovalPayload, type ToolContext, type ToolDisclosure, type ToolTurnScope, defineConfig, defineTool };

package/dist/testing.d.ts

@@ -0,0 +1,16 @@
+import { a as PluginToolFailureError, c as ToolTurnScope, l as PluginConfig, r as ToolContextFor } from "./tool-Vqe6D48m.js";
+import { z } from "zod";
+//#region src/testing.d.ts
+/** `settings` as the declared schema accepts them, so defaults apply as they do at boot; `turn` overrides the four facts */
+type TestContextOptions<TConfig extends PluginConfig> = {
+  readonly settings?: TConfig['settings'] extends z.ZodType ? z.input<TConfig['settings']> : never;
+  readonly turn?: Partial<ToolTurnScope>;
+};
+/**
+ * The context a deployment hands `execute`, over in-memory storage: each declared collection
+ * validates on write and parses on read as the real store does, settings pass through the declared
+ * schema so defaults apply, and `err` raises exactly what the framework's wrapper catches.
+ */
+declare function createTestContext<TConfig extends PluginConfig>(config: TConfig, options?: TestContextOptions<TConfig>): ToolContextFor<TConfig>;
+//#endregion
+export { PluginToolFailureError, TestContextOptions, createTestContext };

package/dist/testing.js

@@ -0,0 +1,174 @@
+//#region ../core/dist/plugins/plugins.errors.js
+/** what `err.invalidArguments` and `err.unresolved` throw; the perimeter wrapper catches it and nothing else */
+var PluginToolFailureError = class extends Error {
+	failure;
+	constructor(failure) {
+		super(failure.message);
+		this.failure = failure;
+	}
+};
+//#endregion
+//#region ../../node_modules/.pnpm/es-toolkit@1.50.0/node_modules/es-toolkit/dist/predicate/isPlainObject.mjs
+/**
+* Checks if a given value is a plain object.
+*
+* @param value - The value to check.
+* @returns True if the value is a plain object, otherwise false.
+*
+* @example
+* ```typescript
+* // ✅👇 True
+*
+* isPlainObject({ });                       // ✅
+* isPlainObject({ key: 'value' });          // ✅
+* isPlainObject({ key: new Date() });       // ✅
+* isPlainObject(new Object());              // ✅
+* isPlainObject(Object.create(null));       // ✅
+* isPlainObject({ nested: { key: true} });  // ✅
+* isPlainObject(new Proxy({}, {}));         // ✅
+* isPlainObject({ [Symbol('tag')]: 'A' });  // ✅
+*
+* // ✅👇 (cross-realms, node context, workers, ...)
+* const runInNewContext = await import('node:vm').then(
+*     (mod) => mod.runInNewContext
+* );
+* isPlainObject(runInNewContext('({})'));   // ✅
+*
+* // ❌👇 False
+*
+* class Test { };
+* isPlainObject(new Test())           // ❌
+* isPlainObject(10);                  // ❌
+* isPlainObject(null);                // ❌
+* isPlainObject('hello');             // ❌
+* isPlainObject([]);                  // ❌
+* isPlainObject(new Date());          // ❌
+* isPlainObject(new Uint8Array([1])); // ❌
+* isPlainObject(Buffer.from('ABC'));  // ❌
+* isPlainObject(Promise.resolve({})); // ❌
+* isPlainObject(Object.create({}));   // ❌
+* isPlainObject(new (class Cls {}));  // ❌
+* isPlainObject(globalThis);          // ❌,
+* ```
+*/
+function isPlainObject(value) {
+	if (!value || typeof value !== "object") return false;
+	const proto = Object.getPrototypeOf(value);
+	if (!(proto === null || proto === Object.prototype || Object.getPrototypeOf(proto) === null)) return false;
+	return Object.prototype.toString.call(value) === "[object Object]";
+}
+//#endregion
+//#region ../core/dist/toolsets/storage/collection-query.utils.js
+/** folds ASCII letters only, matching SQLite's `lower()` without ICU, so the store and this evaluator agree on every string */
+const foldAsciiCase = (text) => text.replace(/[A-Z]+/g, (upper) => upper.toLowerCase());
+const readField = (record, field) => isPlainObject(record) ? record[field] : void 0;
+const matchesScalar = (actual, expected) => expected === null ? actual === null || actual === void 0 : actual === expected;
+const matchesCondition = (actual, condition) => {
+	if (condition === null || typeof condition !== "object") return matchesScalar(actual, condition);
+	if ("in" in condition) return condition.in.some((candidate) => matchesScalar(actual, candidate));
+	return typeof actual === "string" && foldAsciiCase(actual).includes(foldAsciiCase(condition.contains));
+};
+const readConditions = (where) => {
+	const conditions = [];
+	for (const [field, condition] of Object.entries(where ?? {})) if (condition !== void 0) conditions.push([field, condition]);
+	return conditions;
+};
+/** the stated conditions of a query, by field, an undefined one dropped as unstated */
+function collectionQueryConditions(query) {
+	return readConditions(query.where);
+}
+/** the query over records already in memory, in their own order — the semantics the store's compiled form must reproduce */
+function applyCollectionQuery(records, query) {
+	const conditions = collectionQueryConditions(query);
+	const matching = records.filter((record) => conditions.every(([field, condition]) => matchesCondition(readField(record, field), condition)));
+	return query.limit === void 0 ? matching : matching.slice(0, query.limit);
+}
+//#endregion
+//#region ../core/dist/plugins/plugins.utils.js
+/** what a plugin tool receives as `err`; shared with the SDK's testing entry, so a test raises the failure a deployment would */
+const PLUGIN_TOOL_ERR = {
+	invalidArguments(message) {
+		throw new PluginToolFailureError({
+			kind: "invalid-arguments",
+			message
+		});
+	},
+	unresolved(message) {
+		throw new PluginToolFailureError({
+			kind: "unresolved",
+			message
+		});
+	}
+};
+//#endregion
+//#region src/testing.ts
+const DEFAULT_TURN = {
+	agentUsername: "tester",
+	channelId: "test-channel",
+	triggeringPostId: null,
+	turnId: "test-turn"
+};
+/** the deployment's store mints a cuid2; here any unique string serves, and a test that needs a known id passes one */
+function createCollection(schema) {
+	const rows = /* @__PURE__ */ new Map();
+	const toRecord = ({ createdAt, id, updatedAt, ...value }) => ({
+		...schema.parse(value),
+		createdAt,
+		id,
+		updatedAt
+	});
+	return {
+		create: ({ id = crypto.randomUUID(), ...data }) => Promise.try(() => {
+			if (rows.has(id)) throw new Error(`storage collection already holds a record with id "${id}"`);
+			const now = /* @__PURE__ */ new Date();
+			rows.set(id, {
+				...schema.parse(data),
+				createdAt: now,
+				id,
+				updatedAt: now
+			});
+			return toRecord(rows.get(id));
+		}),
+		deleteById: (id) => Promise.try(() => rows.delete(id)),
+		findById: (id) => Promise.try(() => rows.has(id) ? toRecord(rows.get(id)) : null),
+		findMany: (query = {}) => Promise.try(() => applyCollectionQuery([...rows.values()].map(toRecord), query)),
+		updateById: (id, patch) => Promise.try(() => {
+			const row = rows.get(id);
+			if (row === void 0) return null;
+			const { createdAt, id: _id, updatedAt: _updatedAt, ...value } = row;
+			rows.set(id, {
+				...schema.parse({
+					...schema.parse(value),
+					...patch
+				}),
+				createdAt,
+				id,
+				updatedAt: /* @__PURE__ */ new Date()
+			});
+			return toRecord(rows.get(id));
+		})
+	};
+}
+/**
+* The context a deployment hands `execute`, over in-memory storage: each declared collection
+* validates on write and parses on read as the real store does, settings pass through the declared
+* schema so defaults apply, and `err` raises exactly what the framework's wrapper catches.
+*/
+function createTestContext(config, options = {}) {
+	const storage = Object.fromEntries(Object.entries(config.storage).map(([name, schema]) => [name, createCollection(schema)]));
+	const context = {
+		err: PLUGIN_TOOL_ERR,
+		storage,
+		turn: {
+			...DEFAULT_TURN,
+			...options.turn
+		}
+	};
+	const settings = config.settings === void 0 ? {} : { settings: config.settings.parse(options.settings ?? {}) };
+	return {
+		...context,
+		...settings
+	};
+}
+//#endregion
+export { PluginToolFailureError, createTestContext };

package/dist/tool-Vqe6D48m.d.ts

@@ -0,0 +1,231 @@
+import { z } from "zod";
+import { Promisable } from "type-fest";
+//#region src/config.d.ts
+type CollectionsDeclaration$1 = {
+  readonly [key: string]: z.ZodObject;
+};
+/**
+ * The config file's default export: the settings schema agents are configured by, and the storage
+ * collections the plugin owns. Its generics are what carry the settings and storage types to every
+ * tool, through `Register`.
+ */
+type PluginConfig<TSettings extends undefined | z.ZodType = undefined | z.ZodType, TCollections extends CollectionsDeclaration$1 = CollectionsDeclaration$1> = {
+  readonly settings: TSettings;
+  readonly storage: TCollections;
+};
+/**
+ * The augmentation point. `src/config.ts` declares its config here, and every tool file receives
+ * the declared settings and storage types without importing the config:
+ *
+ * ```ts
+ * declare module '@collegium/sdk' {
+ *   interface Register { config: typeof config }
+ * }
+ * ```
+ */
+interface Register {}
+type RegisteredConfig = Register extends {
+  readonly config: infer TConfig extends PluginConfig;
+} ? TConfig : PluginConfig;
+declare function defineConfig<TSettings extends undefined | z.ZodType = undefined, const TCollections extends CollectionsDeclaration$1 = {}>(config: {
+  readonly settings?: TSettings;
+  readonly storage?: TCollections;
+}): PluginConfig<TSettings, TCollections>;
+//#endregion
+//#region ../core/src/approvals/approvals.types.d.ts
+/** how a gated tool's approval payload is presented (§6.2): collapsed behind a control, or verbatim */
+type ApprovalPayloadPresentation = 'collapse' | 'verbatim';
+//#endregion
+//#region ../core/src/utils/token.utils.d.ts
+declare const SERVICE_INSTANCE: unique symbol;
+/**
+ * A NestJS-compatible injection token branded with the instance type it resolves to. Declared in a
+ * leaf `<module>.tokens.ts` beside `import type` of the service alone, which is what keeps a
+ * toolset declaration inert (§2): the entrypoint and provisioning import one without pulling the
+ * service's runtime module into their graphs.
+ */
+type ServiceToken<TInstance> = {
+  readonly [SERVICE_INSTANCE]?: TInstance;
+} & symbol;
+//#endregion
+//#region ../core/src/tools/tools.types.d.ts
+/** the four facts of the running turn (§4) — everything else a tool needs, its toolset declares */
+type ToolTurnScope = {
+  readonly agentUsername: string;
+  readonly channelId: string;
+  /** provenance for anything a tool records; null on a turn no post triggered */
+  readonly triggeringPostId: null | string;
+  readonly turnId: string;
+};
+/** §6.2 — the full payload the approver reads; presence of the `approval` hook is what gates a tool (§5) */
+type ToolApprovalPayload = {
+  body: string;
+  presentation: ApprovalPayloadPresentation;
+};
+/**
+ * A durable record's disclosure (§3.6), returned by the tool that created it; the turn writes the
+ * event and the trace lines. `reference` names the record for later reads, e.g. a memory id.
+ */
+type ToolDisclosure = {
+  readonly body: string;
+  readonly description: string;
+  readonly reference: string;
+  readonly supersededDescriptions?: readonly string[];
+};
+declare namespace ToolFailure {
+  /** the tool body threw — a semantic failure that terminates the turn (§7.1, §7.2) */
+  type Exception = {
+    kind: 'exception';
+    message: string;
+  };
+  /** the arguments were rejected — returned to the model as the tool result; the turn continues */
+  type InvalidArguments = {
+    kind: 'invalid-arguments';
+    message: string;
+  };
+  /** execution outlived `timeoutMs` — for a mutation the side effect is unconfirmed (§7.1, §7.2) */
+  type Timeout = {
+    kind: 'timeout';
+    timeoutMs: number;
+  };
+  /**
+   * The tool committed something whose outcome cannot be established — a send that may or may not
+   * have left. The turn ends stating the ambiguity (§7.1); it is never returned to the model,
+   * because a model told "unresolved" will try again, which is precisely what must not happen.
+   */
+  type Unresolved = {
+    kind: 'unresolved';
+    message: string;
+  };
+  /** the model named a tool that does not exist or sits outside its configured set (§6.1, §7.2) */
+  type UnknownTool = {
+    kind: 'unknown-tool';
+    message: string;
+  };
+  type Any = Exception | InvalidArguments | Timeout | UnknownTool | Unresolved;
+}
+type ToolFailure = ToolFailure.Any;
+//#endregion
+//#region ../core/src/plugins/plugins.errors.d.ts
+/** what `err.invalidArguments` and `err.unresolved` throw; the perimeter wrapper catches it and nothing else */
+declare class PluginToolFailureError extends Error {
+  readonly failure: ToolFailure.InvalidArguments | ToolFailure.Unresolved;
+  constructor(failure: ToolFailure.InvalidArguments | ToolFailure.Unresolved);
+}
+//#endregion
+//#region ../core/src/plugins/plugins.types.d.ts
+/** what a plugin tool body may return: the text alone, or the text beside a durable record's disclosure (§3.4) */
+type PluginToolOutput = string | {
+  readonly disclosure?: ToolDisclosure;
+  readonly text: string;
+};
+/**
+ * The two failures a tool body may raise itself — the rest of the taxonomy (§7.1) is the
+ * framework's to raise. Each throws; the perimeter wrapper maps the throw into the taxonomy.
+ */
+type PluginToolErr = {
+  /** the arguments were rejected — returned to the model as the tool result; the turn continues */
+  invalidArguments(message: string): never;
+  /** a committed side effect whose outcome cannot be established; the turn ends stating the ambiguity */
+  unresolved(message: string): never;
+};
+/** one tool as a plugin declares it: the framework's tool minus `budgetExempt`, returning plain output */
+type PluginToolDeclaration<TContext, TParams extends z.ZodType> = {
+  /** present ⇒ the tool always gates (§5); renders the payload the approver reads and cannot decline */
+  approval?(args: z.infer<TParams>): ToolApprovalPayload;
+  readonly description: string;
+  execute(args: z.infer<TParams>, context: TContext): Promisable<PluginToolOutput>;
+  readonly parameters: TParams;
+  /** §7.2 — whether a timed-out call may be reported to the model as a plain failure; false ends the turn as unconfirmable */
+  readonly retryable?: boolean;
+  readonly timeoutMs?: number;
+  /** §8.1 — the one-line summary beside the name in the status post; absent shows the name alone */
+  traceDetail?(args: z.infer<TParams>): string;
+};
+//#endregion
+//#region ../core/src/toolsets/storage/collection-query.types.d.ts
+/** the JSON scalars a query may compare; an object, array, or date field is not queryable */
+type Scalar = boolean | null | number | string;
+/**
+ * The top-level scalar fields of a record, each stripped of the undefined an optional field
+ * carries. The intersection with the scalar union changes nothing for a concrete record and is what
+ * lets the compiler see, over a generic one, that every condition is a scalar condition.
+ */
+type QueryableFields<TRecord> = { readonly [K in keyof TRecord as Exclude<TRecord[K], undefined> extends Scalar ? K : never]-?: Exclude<TRecord[K], undefined> & Scalar; };
+/** one field's condition: equality, membership, or — on a string field — a case-insensitive substring */
+type CollectionFieldCondition<TField> = ([Extract<TField, string>] extends [never] ? never : {
+  readonly contains: string;
+}) | TField | {
+  readonly in: readonly TField[];
+};
+/** an AND over field conditions, keyed by the record's own scalar fields */
+type CollectionWhere<TRecord> = { readonly [K in keyof QueryableFields<TRecord>]?: CollectionFieldCondition<QueryableFields<TRecord>[K]>; };
+type CollectionQuery<TRecord> = {
+  readonly limit?: number;
+  readonly where?: CollectionWhere<TRecord>;
+};
+//#endregion
+//#region ../core/src/toolsets/storage/collection.types.d.ts
+/** what the store stamps on every record beside the declared fields; a schema may not declare any of these */
+type CollectionRecordStamp = {
+  readonly createdAt: Date;
+  readonly id: string;
+  readonly updatedAt: Date;
+};
+type CollectionRecord<TValue> = CollectionRecordStamp & TValue;
+/**
+ * A toolset-scoped handle over one declared storage collection. Every record is the schema's
+ * output plus the stamp; `create` parses through the schema, so defaults apply, and mints a
+ * cuid2 unless an id is given. Reads parse each stored value, so a row an older schema wrote
+ * fails loudly rather than leaking a stale shape into the tool.
+ */
+type ToolsetCollection<TSchema extends z.ZodObject> = {
+  create(data: z.input<TSchema> & {
+    readonly id?: string;
+  }): Promise<CollectionRecord<z.output<TSchema>>>;
+  deleteById(id: string): Promise<boolean>;
+  findById(id: string): Promise<CollectionRecord<z.output<TSchema>> | null>;
+  /** without a query, every record in insertion order */
+  findMany(query?: CollectionQuery<CollectionRecord<z.output<TSchema>>>): Promise<CollectionRecord<z.output<TSchema>>[]>;
+  /** the patch merged over the stored fields and the whole parsed again, so a patch cannot leave an invalid record */
+  updateById(id: string, patch: Partial<z.input<TSchema>>): Promise<CollectionRecord<z.output<TSchema>> | null>;
+};
+//#endregion
+//#region ../core/src/toolsets/toolsets.types.d.ts
+/** `settings`, `storage`, and `turn` are the context's own keys, so a service may not claim them */
+type ServicesDeclaration = {
+  readonly [key: string]: ServiceToken<unknown>;
+} & {
+  readonly settings?: never;
+  readonly storage?: never;
+  readonly turn?: never;
+};
+type CollectionsDeclaration = {
+  readonly [key: string]: z.ZodObject;
+};
+type EmptyDeclaration = {};
+/**
+ * What `execute` receives, assembled from exactly what the toolset declared (§4): each service
+ * under its own name, `settings` and `storage` only when declared, and always the turn. Reaching
+ * anything undeclared is a compile error.
+ */
+type ToolsetContext<TServices extends ServicesDeclaration = EmptyDeclaration, TSettings extends undefined | z.ZodType = undefined, TCollections extends CollectionsDeclaration = EmptyDeclaration> = { readonly [K in keyof TServices]: TServices[K] extends ServiceToken<infer TInstance> ? TInstance : never; } & {
+  readonly turn: ToolTurnScope;
+} & (keyof TCollections extends never ? unknown : {
+  readonly storage: { readonly [K in keyof TCollections]: ToolsetCollection<TCollections[K]>; };
+}) & (TSettings extends z.ZodType ? {
+  readonly settings: z.infer<TSettings>;
+} : unknown);
+//#endregion
+//#region src/tool.d.ts
+/** what `execute` receives under a config: its settings and storage, the failure raisers, and the four facts of the turn */
+type ToolContextFor<TConfig extends PluginConfig> = ToolsetContext<EmptyDeclaration, TConfig['settings'], TConfig['storage']> & {
+  readonly err: PluginToolErr;
+};
+/** the context under the registered config: what every tool file's `execute` receives */
+type ToolContext = ToolContextFor<RegisteredConfig>;
+type PluginTool<TParams extends z.ZodType> = PluginToolDeclaration<ToolContext, TParams>;
+/** identity at runtime; what it is for is typing `args` from `parameters` across the whole declaration */
+declare function defineTool<TParams extends z.ZodType>(tool: PluginTool<TParams>): PluginTool<TParams>;
+//#endregion
+export { PluginToolFailureError as a, ToolTurnScope as c, defineConfig as d, defineTool as i, PluginConfig as l, ToolContext as n, ToolApprovalPayload as o, ToolContextFor as r, ToolDisclosure as s, PluginTool as t, Register as u };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@collegium/sdk",
   "type": "module",
-  "version": "0.0.1-beta.7",
+  "version": "0.0.1-beta.9",
   "description": "Write a Collegium plugin: declare a toolset with its tools, settings, storage, and skills.",
   "license": "AGPL-3.0-only",
   "homepage": "https://collegium.sh",
@@ -21,7 +21,11 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
   },
   "files": [
     "dist"