@shardworks/nexus-core 0.1.100 → 0.1.102

package/README.md

@@ -1,243 +1,172 @@
 # `@shardworks/nexus-core`
 
-The public SDK for Nexus Mk 2.1. Rig authors import from this package to define tools, declare books, and read guild configuration.
+The public SDK surface for Nexus Mk 2.1. Every plugin — kit or apparatus — depends on this package for the guild singleton, plugin lifecycle types, guild configuration, and package resolution utilities.
 
-This package is a dependency of every rig. It does not depend on mainspring or the CLI — the dependency graph runs one way: rigs → core.
+This package has zero runtime dependencies. The dependency graph runs one way: plugins → core.
 
 ---
 
-## `tool()` — Tool SDK
+## `Guild` — Process-Level Singleton
 
-Define a Nexus tool. This is the primary authoring entry point for rig packages.
+The central access point for guild infrastructure at runtime. All plugin code (apparatus `start()`, tool handlers, engine handlers) imports `guild()` to access apparatus APIs, plugin config, and the guild root path.
 
 ```typescript
-import { tool } from '@shardworks/nexus-core';
-import { z } from 'zod';
-
-export default tool({
-  name: 'greet',
-  description: 'Greet an anima by name',
-  params: {
-    name: z.string().describe('Anima name'),
-  },
-  handler: async ({ name }, ctx) => {
-    return `Hello, ${name}! Guild root: ${ctx.home}`;
-  },
-});
-```
-
-A rig package exports a `Rig` object, a single tool, or an array of tools as its default export. Mainspring discovers them automatically at install time.
-
-### `ToolDefinition`
-
-The return type of `tool()`. MCP, CLI, and engines all consume this shape.
-
-### `ToolCaller`
-
-`'cli' | 'mcp'` — controls which surfaces a tool appears on. Set via `callableFrom`:
+import { guild } from '@shardworks/nexus-core';
 
-```typescript
-tool({
-  name: 'rig-install',
-  callableFrom: ['cli'],   // CLI only — not exposed to animas via MCP
-  ...
-});
+const home = guild().home;
+const stacks = guild().apparatus<StacksApi>('stacks');
+const config = guild().config<MyConfig>('my-plugin');
 ```
 
-Defaults to all callers if omitted.
-
-### Resolution helpers
-
-```typescript
-// Find one tool from a module's default export
-resolveToolFromExport(moduleDefault, toolName?)
+| Member | Returns | Description |
+|---|---|---|
+| `home` | `string` | Absolute path to the guild root |
+| `apparatus<T>(name)` | `T` | Retrieve a started apparatus's `provides` object by plugin id |
+| `config<T>(pluginId)` | `T` | Read a plugin's configuration section from guild.json |
+| `writeConfig<T>(pluginId, value)` | `void` | Write a plugin's configuration section to guild.json (updates in-memory + disk) |
+| `guildConfig()` | `GuildConfig` | Read the full parsed guild.json |
+| `kits()` | `LoadedKit[]` | Snapshot of all loaded kits (including apparatus supportKits) |
+| `apparatuses()` | `LoadedApparatus[]` | Snapshot of all started apparatuses |
 
-// Find all tools from a module's default export
-resolveAllToolsFromExport(moduleDefault)
+Framework functions (not for plugin use):
 
-// Type guard
-isToolDefinition(obj)
-```
+| Function | Description |
+|---|---|
+| `setGuild(g)` | Register the guild instance — called by Arbor at startup |
+| `clearGuild()` | Clear the guild instance — called by Arbor at shutdown or in tests |
 
 ---
 
-## `Rig` — Rig Export Type
+## Plugin System — `Kit`, `Apparatus`, `Plugin`
+
+Core types for the Kit/Apparatus model. Plugins come in two kinds:
 
-The author-facing export type for a rig package. Rig packages export this as their default export. Mainspring reads it at load time to discover the rig's contributions.
+- **Kit** — passive package contributing capabilities. No lifecycle, no running state. Read at load time.
+- **Apparatus** — package contributing persistent infrastructure. Has a `start`/`stop` lifecycle.
 
 ```typescript
-import { type Rig, tool } from '@shardworks/nexus-core';
+import type { Kit, Apparatus, Plugin } from '@shardworks/nexus-core';
 
-const myTool = tool({ ... });
+// Kit example
+export default { kit: { tools: [myTool] } } satisfies Plugin;
 
+// Apparatus example
 export default {
-  tools: [myTool],
-  books: {
-    writs: { indexes: ['status', 'createdAt', 'parent.id'] },
+  apparatus: {
+    requires: ['stacks'],
+    provides: myApi,
+    start: async (ctx) => { /* ... */ },
   },
-} satisfies Rig;
-```
-
-| Field | Type | Description |
-|---|---|---|
-| `tools?` | `ToolDefinition[]` | Tools this rig contributes to the guild |
-| `books?` | `Record<string, BookOptions>` | Named document collections — mainspring creates SQLite tables and indexes at startup |
-
-Backward-compatible: rigs may still export a bare `ToolDefinition` or `ToolDefinition[]` directly.
-
-### `BookOptions`
-
-Schema declaration for a single book:
-
-```typescript
-interface BookOptions {
-  indexes?: string[];  // field names to index (plain or dot-notation)
-}
-```
-
-### `isRig(obj)`
-
-Type guard distinguishing a `Rig` export from a bare tool or array.
-
----
-
-## `RigContext` — Handler Context
-
-Injected into every tool and engine handler. Scoped to the rig that owns the handler.
-
-```typescript
-interface RigContext {
-  home: string;
-
-  book<T extends { id: string }>(name: string): Book<T>;
-  rigBook<T extends { id: string }>(rigId: string, name: string): ReadOnlyBook<T>;
-}
+} satisfies Plugin;
 ```
 
-| Member | Returns | Description |
-|---|---|---|
-| `home` | `string` | Absolute path to the guild root |
-| `book(name)` | `Book<T>` | Read-write handle to one of this rig's declared books |
-| `rigBook(rigId, name)` | `ReadOnlyBook<T>` | Read-only handle to another rig's book |
-
-`ToolContext` is a deprecated alias for `RigContext`, re-exported from legacy for backward compatibility.
-
----
-
-## `Book<T>` — Document Store
+### Types
 
-The NoSQL document store primitive for rig authors. `T` must extend `{ id: string }` — rig authors own ID generation.
-
-| Method | Description |
+| Type | Description |
 |---|---|
-| `put(content)` | Upsert a document (creates or replaces entirely by `content.id`) |
-| `get(id)` | Retrieve by id, or `null` |
-| `delete(id)` | Remove by id (silent no-op if absent) |
-| `find(query)` | Query with `where`, `orderBy`, `order`, `limit`, `offset` |
-| `list(options?)` | List all documents, optionally paginated and sorted |
-| `count(where?)` | Count documents matching an optional filter |
-
-### `BookQuery`
-
-```typescript
-type BookQuery = {
-  where?: Record<string, unknown>;  // field equality filters, ANDed
-  orderBy?: string;                 // plain name or dot-notation
-  order?: 'asc' | 'desc';
-  limit?: number;
-  offset?: number;                  // requires limit
-}
-```
+| `Kit` | Open record with optional `requires` and `recommends` arrays. Contribution fields are defined by consuming apparatuses. |
+| `Apparatus` | Record with `start(ctx)`, optional `stop()`, optional `provides`, `requires`, `supportKit`, `consumes`. |
+| `Plugin` | Discriminated union: `{ kit: Kit }` or `{ apparatus: Apparatus }` |
+| `LoadedKit` | A kit as tracked by Arbor: `packageName`, `id`, `version`, `kit` |
+| `LoadedApparatus` | An apparatus as tracked by Arbor: `packageName`, `id`, `version`, `apparatus` |
+| `LoadedPlugin` | Union of `LoadedKit` and `LoadedApparatus` |
+| `StartupContext` | Passed to `apparatus.start()`. Provides `on(event, handler)` for lifecycle subscriptions. |
 
-### `ReadOnlyBook<T>`
+### Type Guards
 
-Returned by `rigBook()` for cross-rig access. Same as `Book<T>` minus `put` and `delete`.
+| Function | Description |
+|---|---|
+| `isKit(obj)` | Narrows to `{ kit: Kit }` |
+| `isApparatus(obj)` | Narrows to `{ apparatus: Apparatus }` |
+| `isLoadedKit(p)` | Narrows `LoadedPlugin` to `LoadedKit` |
+| `isLoadedApparatus(p)` | Narrows `LoadedPlugin` to `LoadedApparatus` |
 
 ---
 
-## `guild-config` — Guild Configuration
+## Guild Configuration
 
 Read and write `guild.json`, the guild's central configuration file.
 
 ```typescript
-import { readGuildConfigV2, writeGuildConfigV2 } from '@shardworks/nexus-core';
+import { readGuildConfig, writeGuildConfig } from '@shardworks/nexus-core';
 
-const config = readGuildConfigV2(home);
-config.baseTools.push('my-tool');
-writeGuildConfigV2(home, config);
+const config = readGuildConfig(home);
+writeGuildConfig(home, config);
 ```
 
-### `GuildConfigV2`
-
-The shape of `guild.json` for V2 guilds:
+### `GuildConfig`
 
 | Field | Type | Description |
 |---|---|---|
 | `name` | `string` | Guild name |
 | `nexus` | `string` | Framework version at last init/upgrade |
-| `rigs` | `string[]` | Installed rig keys (derived from npm package names) |
-| `baseTools` | `string[]` | Tools available to all animas |
-| `roles` | `Record<string, RoleDefinition>` | Guild roles with seats, tools, instructions |
-| `workshops` | `Record<string, WorkshopEntry>` | Registered workshops |
+| `plugins` | `string[]` | Installed plugin ids |
+| `clockworks?` | `ClockworksConfig` | Events and standing orders |
+| `writTypes?` | `Record<string, WritTypeDeclaration>` | Guild-declared writ types |
 | `settings?` | `GuildSettings` | Operational flags including default `model` |
-| `clockworks?` | `ClockworksConfig` | Standing orders and custom events |
-| `writTypes?` | `Record<string, WritTypeDeclaration>` | Custom writ type declarations |
 
-### Other exports
+All other top-level keys are plugin configuration sections, keyed by derived plugin id.
 
-```typescript
-guildConfigPath(home)              // path to guild.json
-createInitialGuildConfigV2(...)    // default config for nsg init
-```
+### Other Exports
+
+| Function / Type | Description |
+|---|---|
+| `createInitialGuildConfig(name, version, model)` | Default config for `nsg init` |
+| `guildConfigPath(home)` | Resolve path to `guild.json` |
+| `EventDeclaration` | Custom event: `description`, optional `schema` |
+| `StandingOrder` | Event → action mapping (run / summon / brief) |
+| `ClockworksConfig` | Container for events and standing orders |
+| `WritTypeDeclaration` | Writ type: `description` |
+| `GuildSettings` | Settings: `model`, `autoMigrate` |
 
 ---
 
-## `nexus-home` — Path Resolution
+## Path Resolution — `nexus-home`
 
 Resolve standard paths within a guild's `.nexus/` directory.
 
 ```typescript
 import { findGuildRoot, nexusDir } from '@shardworks/nexus-core';
 
-const home = findGuildRoot();          // walks up from cwd to find guild.json
-const dir  = nexusDir(home);           // .nexus/
+const home = findGuildRoot();   // walks up from cwd to find guild.json
+const dir  = nexusDir(home);    // .nexus/
 ```
 
-### All path helpers
-
 | Function | Returns |
 |---|---|
 | `findGuildRoot(startDir?)` | Guild root (walks up from cwd, throws if not found) |
 | `nexusDir(home)` | `.nexus/` |
 | `worktreesPath(home)` | `.nexus/worktrees/` |
-| `workshopsPath(home)` | `.nexus/workshops/` |
-| `workshopBarePath(home, name)` | `.nexus/workshops/<name>.git` |
 | `clockPidPath(home)` | `.nexus/clock.pid` |
 | `clockLogPath(home)` | `.nexus/clock.log` |
 
 ---
 
-## `rig-descriptor` — Rig Descriptor Types
+## Package Resolution
 
-Types for `rig.json`, the optional descriptor a rig package can include at its root to declare dependencies on other rigs.
+Utilities for resolving guild-installed npm packages and deriving plugin ids.
 
 ```typescript
-import type { RigDescriptor } from '@shardworks/nexus-core';
+import { derivePluginId, resolveGuildPackageEntry } from '@shardworks/nexus-core';
+
+derivePluginId('@shardworks/books-apparatus');  // → 'books'
+derivePluginId('@acme/my-plugin');              // → 'acme/my-plugin'
+derivePluginId('my-relay-kit');                 // → 'my-relay'
 ```
 
-### `RigDescriptor`
+| Function | Description |
+|---|---|
+| `derivePluginId(packageName)` | Canonical npm package name → plugin id. Strips `@shardworks/` scope and `-plugin`/`-apparatus`/`-kit` suffixes. |
+| `readGuildPackageJson(guildRoot, pkgName)` | Read a package's `package.json` from the guild's `node_modules` |
+| `resolvePackageNameForPluginId(guildRoot, pluginId)` | Reverse lookup: find the npm package name for a plugin id |
+| `resolveGuildPackageEntry(guildRoot, pkgName)` | Resolve the ESM entry point for a guild-installed package |
 
-```typescript
-interface RigDescriptor {
-  description?: string;
-  dependencies?: RigDependency[];
-}
-
-interface RigDependency {
-  rig: string;   // rig key, e.g. 'nexus-stdlib'
-}
-```
+---
+
+## `VERSION`
 
-Mainspring reads `rig.json` at install time. If declared dependencies aren't installed, `nsg rig install` fails with a clear error.
+The package version, read from `package.json` at runtime.
 
-A rig with no dependencies needs no `rig.json` at all.
+```typescript
+import { VERSION } from '@shardworks/nexus-core';
+```

package/dist/guild-config.d.ts

@@ -1,18 +1,3 @@
-/** Definition of a guild role — a structural position in the guild. */
-export interface RoleDefinition {
-    /**
-     * Maximum number of animas that can hold this role simultaneously.
-     * `null` means unbounded.
-     */
-    seats: number | null;
-    /** Tools available to animas in this role (additive with baseTools). */
-    tools: string[];
-    /**
-     * Path to role-specific instructions markdown, relative to guild root.
-     * Read fresh at manifest time and delivered to animas holding this role.
-     */
-    instructions?: string;
-}
 /** A custom event declaration in guild.json clockworks.events. */
 export interface EventDeclaration {
     /** Human-readable description of what this event means. */
@@ -20,11 +5,6 @@ export interface EventDeclaration {
     /** Optional payload schema hint (not enforced in Phase 1). */
     schema?: Record<string, string>;
 }
-/** A writ type declaration in guild.json. */
-export interface WritTypeDeclaration {
-    /** Human-readable description of this writ type. */
-    description: string;
-}
 /** A standing order — a registered response to an event. */
 export type StandingOrder = {
     on: string;
@@ -44,13 +24,6 @@ export interface ClockworksConfig {
     /** Standing orders — event → action mappings. */
     standingOrders?: StandingOrder[];
 }
-/** A registered workshop — a repository where the guild does its work. */
-export interface WorkshopEntry {
-    /** Git remote URL (the clone source). */
-    remoteUrl: string;
-    /** ISO-8601 timestamp of when the workshop was added. */
-    addedAt: string;
-}
 /** Guild-level settings — operational flags and preferences. */
 export interface GuildSettings {
     /**
@@ -66,45 +39,34 @@ export interface GuildSettings {
     autoMigrate?: boolean;
 }
 /**
- * Guild configuration — V2.
- *
- * The rig-centric model: rigs are npm packages; capabilities (tools, engines,
- * training content) are declared by rigs and discovered dynamically at runtime.
- * No per-capability registries — `config.rigs` + `node_modules` is the source
- * of truth. The default model moves into `settings`.
+ * Guild configuration.
  *
- * Breaking change from GuildConfig (V1): drops `tools`, `engines`, `curricula`,
- * `temperaments`, and top-level `model`. Requires `rigs` (was optional).
+ * The plugin-centric model: plugins are npm packages; capabilities (tools, engines,
+ * training content) are declared by plugins and discovered dynamically at runtime.
+ * Framework-level keys (`name`, `nexus`, `plugins`, `settings`) are defined here;
+ * all other top-level keys are plugin configuration sections, keyed by plugin id.
  */
-export interface GuildConfigV2 {
+export interface GuildConfig {
     /** Guild name — used as the guildhall npm package name. */
     name: string;
     /** Installed Nexus framework version. */
     nexus: string;
-    /** Registered workshops indexed by name. */
-    workshops: Record<string, WorkshopEntry>;
-    /** Guild roles — structural positions that animas fill. */
-    roles: Record<string, RoleDefinition>;
-    /** Tool names available to all animas regardless of role. */
-    baseTools: string[];
-    /** Installed rig keys (derived from npm package names). Always present; starts empty. */
-    rigs: string[];
+    /** Installed plugin ids (derived from npm package names). Always present; starts empty. */
+    plugins: string[];
     /** Clockworks configuration — events, standing orders. */
     clockworks?: ClockworksConfig;
-    /** Writ types declared by this guild. Built-in types (mandate, summon) are implicit. */
-    writTypes?: Record<string, WritTypeDeclaration>;
     /** Guild-level settings — operational flags and preferences. Includes default model. */
     settings?: GuildSettings;
 }
 /**
- * Create the default guild.json content for a new V2 guild.
+ * Create the default guild.json content for a new guild.
  * All collections start empty. The default model is stored in settings.
  */
-export declare function createInitialGuildConfigV2(name: string, nexusVersion: string, model: string): GuildConfigV2;
-/** Read and parse a V2 guild.json from the guild root. */
-export declare function readGuildConfigV2(home: string): GuildConfigV2;
-/** Write a V2 guild.json to the guild root. */
-export declare function writeGuildConfigV2(home: string, config: GuildConfigV2): void;
+export declare function createInitialGuildConfig(name: string, nexusVersion: string, model: string): GuildConfig;
+/** Read and parse guild.json from the guild root. */
+export declare function readGuildConfig(home: string): GuildConfig;
+/** Write guild.json to the guild root. */
+export declare function writeGuildConfig(home: string, config: GuildConfig): void;
 /** Resolve the path to guild.json in the guild root. */
 export declare function guildConfigPath(home: string): string;
 //# sourceMappingURL=guild-config.d.ts.map

package/dist/guild-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guild-config.d.ts","sourceRoot":"","sources":["../src/guild-config.ts"],"names":[],"mappings":"AAGA,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,wEAAwE;IACxE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC1C,iDAAiD;IACjD,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;CAClC;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACzC,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACtC,6DAA6D;IAC7D,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,yFAAyF;IACzF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0DAA0D;IAC1D,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAChD,wFAAwF;IACxF,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAU3G;AAED,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAG7D;AAED,+CAA+C;AAC/C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CAG5E;AAED,wDAAwD;AACxD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD"}
+{"version":3,"file":"guild-config.d.ts","sourceRoot":"","sources":["../src/guild-config.ts"],"names":[],"mappings":"AAGA,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAGD,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC1C,iDAAiD;IACjD,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;CAClC;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,wFAAwF;IACxF,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAOvG;AAED,qDAAqD;AACrD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAGzD;AAED,0CAA0C;AAC1C,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAGxE;AAED,wDAAwD;AACxD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/guild-config.js

@@ -1,27 +1,24 @@
 import fs from 'node:fs';
 import path from 'node:path';
 /**
- * Create the default guild.json content for a new V2 guild.
+ * Create the default guild.json content for a new guild.
  * All collections start empty. The default model is stored in settings.
  */
-export function createInitialGuildConfigV2(name, nexusVersion, model) {
+export function createInitialGuildConfig(name, nexusVersion, model) {
     return {
         name,
         nexus: nexusVersion,
-        workshops: {},
-        roles: {},
-        baseTools: [],
-        rigs: [],
+        plugins: [],
         settings: { model },
     };
 }
-/** Read and parse a V2 guild.json from the guild root. */
-export function readGuildConfigV2(home) {
+/** Read and parse guild.json from the guild root. */
+export function readGuildConfig(home) {
     const configFile = guildConfigPath(home);
     return JSON.parse(fs.readFileSync(configFile, 'utf-8'));
 }
-/** Write a V2 guild.json to the guild root. */
-export function writeGuildConfigV2(home, config) {
+/** Write guild.json to the guild root. */
+export function writeGuildConfig(home, config) {
     const configFile = guildConfigPath(home);
     fs.writeFileSync(configFile, JSON.stringify(config, null, 2) + '\n');
 }

package/dist/guild-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"guild-config.js","sourceRoot":"","sources":["../src/guild-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAqG7B;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAAY,EAAE,YAAoB,EAAE,KAAa;IAC1F,OAAO;QACL,IAAI;QACJ,KAAK,EAAE,YAAY;QACnB,SAAS,EAAE,EAAE;QACb,KAAK,EAAE,EAAE;QACT,SAAS,EAAE,EAAE;QACb,IAAI,EAAE,EAAE;QACR,QAAQ,EAAE,EAAE,KAAK,EAAE;KACpB,CAAC;AACJ,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,UAAU,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACzC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAkB,CAAC;AAC3E,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,MAAqB;IACpE,MAAM,UAAU,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACzC,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AACvE,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AACvC,CAAC"}
+{"version":3,"file":"guild-config.js","sourceRoot":"","sources":["../src/guild-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AA6D7B;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAY,EAAE,YAAoB,EAAE,KAAa;IACxF,OAAO;QACL,IAAI;QACJ,KAAK,EAAE,YAAY;QACnB,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE,EAAE,KAAK,EAAE;KACpB,CAAC;AACJ,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,UAAU,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACzC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAgB,CAAC;AACzE,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,MAAmB;IAChE,MAAM,UAAU,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACzC,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AACvE,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AACvC,CAAC"}

package/dist/guild.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Guild — the process-level singleton for accessing guild infrastructure.
+ *
+ * All plugin code — apparatus start(), tool handlers, engine handlers,
+ * relay handlers, CDC handlers — imports `guild()` to access apparatus APIs,
+ * plugin config, the guild root path, and the loaded plugin graph.
+ *
+ * Arbor creates the Guild instance before starting apparatus and registers
+ * it via `setGuild()`. The instance is backed by live data structures
+ * (e.g. the provides Map) that are populated progressively as apparatus start.
+ *
+ * See: docs/architecture/plugins.md
+ */
+import type { GuildConfig } from './guild-config.ts';
+import type { LoadedKit, LoadedApparatus } from './plugin.ts';
+/**
+ * Runtime access to guild infrastructure.
+ *
+ * Available after Arbor creates the instance (before apparatus start).
+ * One instance per process.
+ */
+export interface Guild {
+    /** Absolute path to the guild root (contains guild.json). */
+    readonly home: string;
+    /**
+     * Retrieve a started apparatus's provides object by plugin id.
+     *
+     * Throws if the apparatus is not installed or has no `provides`.
+     * During startup, only apparatus that have already started are visible
+     * (dependency ordering guarantees declared deps are started first).
+     */
+    apparatus<T>(name: string): T;
+    /**
+     * Read a plugin's configuration section from guild.json.
+     *
+     * Returns `guild.json[pluginId]` cast to `T`. Returns `{}` if no
+     * section exists. The generic parameter is a cast — the framework
+     * does not validate config shape.
+     */
+    config<T = Record<string, unknown>>(pluginId: string): T;
+    /**
+     * Write a plugin's configuration section to guild.json.
+     *
+     * Updates `guild.json[pluginId]` with `value` and writes the file
+     * to disk. Also updates the in-memory config so subsequent reads
+     * reflect the change.
+     *
+     * For framework-level keys (name, nexus, plugins, settings), use
+     * the standalone `writeGuildConfig()` function instead.
+     */
+    writeConfig<T = Record<string, unknown>>(pluginId: string, value: T): void;
+    /**
+     * Read the full parsed guild.json.
+     *
+     * Escape hatch for framework-level fields (name, nexus, plugins,
+     * settings) that don't belong to any specific plugin.
+     */
+    guildConfig(): GuildConfig;
+    /** Snapshot of all loaded kits (including apparatus supportKits). */
+    kits(): LoadedKit[];
+    /** Snapshot of all started apparatuses. */
+    apparatuses(): LoadedApparatus[];
+}
+/**
+ * Get the active guild instance.
+ *
+ * Throws with a clear message if called before Arbor has initialized
+ * the guild (e.g. at module import time, before startup begins).
+ */
+export declare function guild(): Guild;
+/**
+ * Set the guild instance. Called by Arbor before starting apparatus.
+ *
+ * Not for plugin use — this is framework infrastructure.
+ */
+export declare function setGuild(g: Guild): void;
+/**
+ * Clear the guild instance. Called by Arbor at shutdown or in tests.
+ *
+ * Not for plugin use — this is framework infrastructure.
+ */
+export declare function clearGuild(): void;
+//# sourceMappingURL=guild.d.ts.map

package/dist/guild.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guild.d.ts","sourceRoot":"","sources":["../src/guild.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAI9D;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IACpB,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAA;IAE7B;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAA;IAExD;;;;;;;;;OASG;IACH,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAA;IAE1E;;;;;OAKG;IACH,WAAW,IAAI,WAAW,CAAA;IAE1B,qEAAqE;IACrE,IAAI,IAAI,SAAS,EAAE,CAAA;IAEnB,2CAA2C;IAC3C,WAAW,IAAI,eAAe,EAAE,CAAA;CACjC;AAMD;;;;;GAKG;AACH,wBAAgB,KAAK,IAAI,KAAK,CAQ7B;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}

package/dist/guild.js

@@ -0,0 +1,45 @@
+/**
+ * Guild — the process-level singleton for accessing guild infrastructure.
+ *
+ * All plugin code — apparatus start(), tool handlers, engine handlers,
+ * relay handlers, CDC handlers — imports `guild()` to access apparatus APIs,
+ * plugin config, the guild root path, and the loaded plugin graph.
+ *
+ * Arbor creates the Guild instance before starting apparatus and registers
+ * it via `setGuild()`. The instance is backed by live data structures
+ * (e.g. the provides Map) that are populated progressively as apparatus start.
+ *
+ * See: docs/architecture/plugins.md
+ */
+// ── Singleton ──────────────────────────────────────────────────────────
+let _guild = null;
+/**
+ * Get the active guild instance.
+ *
+ * Throws with a clear message if called before Arbor has initialized
+ * the guild (e.g. at module import time, before startup begins).
+ */
+export function guild() {
+    if (!_guild) {
+        throw new Error('Guild not initialized — guild() called before Arbor startup. ' +
+            'Ensure guild() is called inside a handler or start(), not at module scope.');
+    }
+    return _guild;
+}
+/**
+ * Set the guild instance. Called by Arbor before starting apparatus.
+ *
+ * Not for plugin use — this is framework infrastructure.
+ */
+export function setGuild(g) {
+    _guild = g;
+}
+/**
+ * Clear the guild instance. Called by Arbor at shutdown or in tests.
+ *
+ * Not for plugin use — this is framework infrastructure.
+ */
+export function clearGuild() {
+    _guild = null;
+}
+//# sourceMappingURL=guild.js.map

package/dist/guild.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guild.js","sourceRoot":"","sources":["../src/guild.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA8DH,0EAA0E;AAE1E,IAAI,MAAM,GAAiB,IAAI,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,UAAU,KAAK;IACnB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,+DAA+D;YAC/D,4EAA4E,CAC7E,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,CAAQ;IAC/B,MAAM,GAAG,CAAC,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC"}

package/dist/id.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Generate a sortable, prefixed ID.
+ *
+ * Format: `{prefix}-{base36_timestamp}-{hex_random}`
+ *
+ * The timestamp component (Date.now() in base36) gives lexicographic sort
+ * order by creation time. The random suffix prevents collisions without
+ * coordination.
+ *
+ * @param prefix     Short, type-identifying string (e.g. `w`, `ses`, `turn`)
+ * @param randomByteCount  Number of random bytes; produces 2× hex digits (default 6 → 12 hex chars)
+ */
+export declare function generateId(prefix: string, randomByteCount?: number): string;
+//# sourceMappingURL=id.d.ts.map

package/dist/id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../src/id.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,GAAE,MAAU,GAAG,MAAM,CAI9E"}