@shardworks/nexus-arbor 0.1.101

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Sean Boots
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# `@shardworks/nexus-arbor`
+
+The guild runtime host for Nexus Mk 2.1. The arbor reads `guild.json`, loads all declared plugins, validates the dependency graph, starts each apparatus in dependency order, and wires the `guild()` singleton. It is the bootstrap layer — every entry point (the CLI, the MCP server, the Clockworks daemon) calls `createGuild()` once at startup.
+
+```
+@shardworks/nexus-core   — public SDK, types, guild() singleton
+@shardworks/nexus-arbor  — guild host, createGuild(), Guild object
+@shardworks/nexus (cli)  — nsg binary, framework commands + Instrumentarium tools
+plugins                  — import from nexus-core only
+```
+
+Plugin authors import from `@shardworks/nexus-core`. The arbor is an internal concern of the CLI and session provider — plugins never depend on it directly.
+
+---
+
+## Installation
+
+```json
+{
+  "dependencies": {
+    "@shardworks/nexus-arbor": "workspace:*"
+  }
+}
+```
+
+---
+
+## API
+
+### `createGuild(root?)`
+
+The single entry point. Creates and starts a guild, returning the `Guild` object.
+
+```typescript
+import { createGuild } from '@shardworks/nexus-arbor';
+
+const guild = await createGuild('/path/to/guild');
+```
+
+If `root` is omitted, auto-detects by walking up from cwd until `guild.json` is found.
+
+`createGuild()` also sets the `guild()` singleton from `@shardworks/nexus-core`, so apparatus code can call `guild()` immediately after startup.
+
+### `Guild`
+
+The object returned by `createGuild()` — also accessible via `guild()` from `@shardworks/nexus-core`.
+
+| Method | Returns | Description |
+|---|---|---|
+| `home` | `string` | Absolute path to the guild root |
+| `apparatus<T>(name)` | `T` | Retrieve a started apparatus's `provides` API by plugin id. Throws if the apparatus has no `provides` |
+| `config<T>(pluginId)` | `T` | Read the plugin-specific configuration section from `guild.json` |
+| `guildConfig()` | `GuildConfig` | The full parsed `guild.json` |
+| `kits()` | `LoadedKit[]` | All loaded kits (snapshot copy) |
+| `apparatuses()` | `LoadedApparatus[]` | All loaded apparatus in start order (snapshot copy) |
+
+### `LoadedKit` and `LoadedApparatus`
+
+Installed plugin packages as seen by the runtime:
+
+```typescript
+interface LoadedKit {
+  packageName: string;  // full npm name, e.g. '@shardworks/nexus-stdlib'
+  id:          string;  // derived plugin id, e.g. 'nexus-stdlib'
+  version:     string;
+  kit:         Kit;     // the package's Kit object
+}
+
+interface LoadedApparatus {
+  packageName: string;
+  id:          string;
+  version:     string;
+  apparatus:   Apparatus;  // the package's Apparatus object
+}
+
+type LoadedPlugin = LoadedKit | LoadedApparatus;
+```
+
+Type guards: `isLoadedKit(p)` and `isLoadedApparatus(p)` from `@shardworks/nexus-core`.
+
+---
+
+## Plugin Lifecycle
+
+`createGuild()` runs the full plugin lifecycle on each call:
+
+1. **Load** — imports all declared plugin packages from `node_modules`, discriminates kit vs. apparatus.
+2. **Validate** — checks `requires` declarations (apparatus and kit), detects circular apparatus dependencies. Fails loudly before any apparatus starts.
+3. **Warn** — advisory warnings for kit contributions that no apparatus `consumes`, and for missing `recommends`.
+4. **Wire** — sets the `guild()` singleton. The `provides` map is populated progressively as each apparatus starts; dependency ordering guarantees declared deps are available.
+5. **Start** — fires `plugin:initialized` for all kits, then calls `start(ctx)` on each apparatus in dependency-resolved order, firing `plugin:initialized` after each.
+
+Apparatus start order is determined by topological sort on `apparatus.requires`. Circular dependencies throw with a descriptive error. Kit `requires` validate that the named apparatus is installed but do not affect start order (kits have no lifecycle).
+
+---
+
+## Guild Lifecycle Internals
+
+Pure validation and ordering logic lives in `guild-lifecycle.ts`, separated from I/O:
+
+| Function | Description |
+|---|---|
+| `validateRequires(kits, apparatuses)` | Validates all `requires` declarations and detects circular dependencies |
+| `topoSort(apparatuses)` | Topological sort by `requires` — determines apparatus start order |
+| `collectStartupWarnings(kits, apparatuses)` | Advisory warnings for unconsumed contributions and missing recommends |
+| `buildStartupContext(eventHandlers)` | Creates the `StartupContext` passed to `apparatus.start()` |
+| `fireEvent(eventHandlers, event, ...args)` | Fires lifecycle events to registered handlers |
+
+These are exported for testing but are not part of the consumer-facing API.
+
+---
+
+## Lazy Startup
+
+The arbor does no work at import time. `createGuild()` is async and performs all plugin loading, validation, and startup in a single call. There is no background process or persistent state — the `Guild` object is alive for the lifetime of the process that created it.

package/dist/arbor.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Arbor — the guild runtime.
+ *
+ * `createGuild()` is the single entry point. It reads guild.json, loads all
+ * declared plugins, validates dependencies, starts apparatus in order, wires
+ * the guild() singleton, and returns the Guild object.
+ *
+ * The full plugin lifecycle:
+ *   1. Load    — imports all declared plugin packages, discriminates kit vs apparatus
+ *   2. Validate — checks `requires` declarations, detects circular dependencies
+ *   3. Start   — calls start(ctx) on each apparatus in dependency-resolved order
+ *   4. Events  — fires `plugin:initialized` after each plugin loads
+ *   5. Warn    — advisory warnings for mismatched kit contributions / recommends
+ *
+ * Pure logic (validation, ordering, events) lives in guild-lifecycle.ts.
+ * This file handles I/O and orchestration.
+ */
+import type { Guild } from '@shardworks/nexus-core';
+/**
+ * Create and start a guild.
+ *
+ * Reads guild.json, loads all declared plugins, validates dependencies,
+ * starts apparatus in dependency order, and returns the Guild object.
+ * Also sets the guild() singleton so apparatus code can access it.
+ *
+ * @param root - Absolute path to the guild root. Defaults to auto-detection
+ *               by walking up from cwd until guild.json is found.
+ * @returns The initialized Guild — the same object guild() returns.
+ */
+export declare function createGuild(root?: string): Promise<Guild>;
+//# sourceMappingURL=arbor.d.ts.map

package/dist/arbor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arbor.d.ts","sourceRoot":"","sources":["../src/arbor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAaH,OAAO,KAAK,EACV,KAAK,EAGN,MAAM,wBAAwB,CAAC;AAahC;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAgI/D"}

package/dist/arbor.js

@@ -0,0 +1,143 @@
+/**
+ * Arbor — the guild runtime.
+ *
+ * `createGuild()` is the single entry point. It reads guild.json, loads all
+ * declared plugins, validates dependencies, starts apparatus in order, wires
+ * the guild() singleton, and returns the Guild object.
+ *
+ * The full plugin lifecycle:
+ *   1. Load    — imports all declared plugin packages, discriminates kit vs apparatus
+ *   2. Validate — checks `requires` declarations, detects circular dependencies
+ *   3. Start   — calls start(ctx) on each apparatus in dependency-resolved order
+ *   4. Events  — fires `plugin:initialized` after each plugin loads
+ *   5. Warn    — advisory warnings for mismatched kit contributions / recommends
+ *
+ * Pure logic (validation, ordering, events) lives in guild-lifecycle.ts.
+ * This file handles I/O and orchestration.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readGuildConfig, writeGuildConfig, findGuildRoot, isKit, isApparatus, setGuild, resolveGuildPackageEntry, resolvePackageNameForPluginId, readGuildPackageJson, } from '@shardworks/nexus-core';
+import { validateRequires, topoSort, collectStartupWarnings, buildStartupContext, fireEvent, } from "./guild-lifecycle.js";
+// ── Public API ────────────────────────────────────────────────────────
+/**
+ * Create and start a guild.
+ *
+ * Reads guild.json, loads all declared plugins, validates dependencies,
+ * starts apparatus in dependency order, and returns the Guild object.
+ * Also sets the guild() singleton so apparatus code can access it.
+ *
+ * @param root - Absolute path to the guild root. Defaults to auto-detection
+ *               by walking up from cwd until guild.json is found.
+ * @returns The initialized Guild — the same object guild() returns.
+ */
+export async function createGuild(root) {
+    const guildRoot = root ?? findGuildRoot();
+    const config = readGuildConfig(guildRoot);
+    const kits = [];
+    const apparatuses = [];
+    const eventHandlers = new Map();
+    // ── Load phase ─────────────────────────────────────────────────────
+    for (const pluginId of config.plugins) {
+        const packageName = resolvePackageNameForPluginId(guildRoot, pluginId);
+        if (!packageName) {
+            console.warn(`[arbor] No package found in package.json for plugin "${pluginId}" — skipping`);
+            continue;
+        }
+        const { version } = readGuildPackageJson(guildRoot, packageName);
+        try {
+            const entryPath = resolveGuildPackageEntry(guildRoot, packageName);
+            const mod = await import(__rewriteRelativeImportExtension(entryPath));
+            const raw = mod.default;
+            if (isApparatus(raw)) {
+                apparatuses.push({ packageName, id: pluginId, version, apparatus: raw.apparatus });
+            }
+            else if (isKit(raw)) {
+                kits.push({ packageName, id: pluginId, version, kit: raw.kit });
+            }
+            else {
+                console.warn(`[arbor] Plugin "${packageName}" does not export a kit or apparatus — skipping. ` +
+                    `Plugins must export { kit: ... } or { apparatus: ... }.`);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`[arbor] Failed to load plugin "${packageName}": ${message}`);
+        }
+    }
+    // ── Validation phase ───────────────────────────────────────────────
+    validateRequires(kits, apparatuses);
+    // ── Startup warnings ───────────────────────────────────────────────
+    for (const warning of collectStartupWarnings(kits, apparatuses)) {
+        console.warn(warning);
+    }
+    // ── Start phase ────────────────────────────────────────────────────
+    const orderedApparatuses = topoSort(apparatuses);
+    const provides = new Map();
+    // Wire guild singleton before any apparatus starts so start() methods
+    // can call guild(). The provides Map is populated progressively as each
+    // apparatus starts; dependency ordering guarantees declared deps are
+    // available.
+    const guildInstance = {
+        home: guildRoot,
+        apparatus(name) {
+            const p = provides.get(name);
+            if (p === undefined) {
+                throw new Error(`[guild] apparatus("${name}") is not available. ` +
+                    `No loaded apparatus provides this id. Check guild.json plugins list.`);
+            }
+            return p;
+        },
+        config(pluginId) {
+            // GuildConfig types only the framework-level keys (name, nexus, plugins, etc.).
+            // Plugin-specific config sections (e.g. "animator", "stacks") are additional
+            // top-level keys in guild.json that GuildConfig doesn't model. The cast is safe
+            // because guild.json is a plain JSON object — all keys are accessible at runtime.
+            // Plugins can use module augmentation on GuildConfig to get typed access; this
+            // generic path remains the untyped fallback.
+            const cfg = config;
+            return (cfg[pluginId] ?? {});
+        },
+        writeConfig(pluginId, value) {
+            // Update the in-memory config so subsequent reads reflect the change,
+            // then persist to disk. The cast is the same pattern as config() above.
+            const cfg = config;
+            cfg[pluginId] = value;
+            writeGuildConfig(guildRoot, config);
+        },
+        guildConfig() {
+            return config;
+        },
+        kits() { return [...kits]; },
+        apparatuses() { return [...orderedApparatuses]; },
+    };
+    setGuild(guildInstance);
+    // Fire plugin:initialized for all kits before starting any apparatus
+    for (const kit of kits) {
+        await fireEvent(eventHandlers, 'plugin:initialized', kit);
+    }
+    // Start each apparatus in dependency order
+    const startupCtx = buildStartupContext(eventHandlers);
+    for (const app of orderedApparatuses) {
+        // Register provides before start() so apparatuses with eager provides are
+        // visible to later startups that run during this loop.
+        if (app.apparatus.provides !== undefined) {
+            provides.set(app.id, app.apparatus.provides);
+        }
+        await app.apparatus.start(startupCtx);
+        // Re-check after start() for deferred provides (e.g. Stacks uses a getter
+        // that returns undefined until start() populates the backing variable).
+        if (!provides.has(app.id) && app.apparatus.provides !== undefined) {
+            provides.set(app.id, app.apparatus.provides);
+        }
+        await fireEvent(eventHandlers, 'plugin:initialized', app);
+    }
+    return guildInstance;
+}
+//# sourceMappingURL=arbor.js.map

package/dist/arbor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arbor.js","sourceRoot":"","sources":["../src/arbor.ts"],"names":[],"mappings":"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"}

package/dist/guild-lifecycle.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Guild lifecycle — pure logic for plugin validation, ordering, and events.
+ *
+ * All functions here operate on in-memory data structures (LoadedKit[],
+ * LoadedApparatus[], Maps) with no I/O. This makes them independently
+ * testable with synthetic fixtures.
+ *
+ * `createGuild()` in arbor.ts is the orchestrator that performs I/O
+ * (config reading, dynamic imports) then delegates to these functions.
+ */
+import type { StartupContext, LoadedKit, LoadedApparatus } from '@shardworks/nexus-core';
+export type EventHandlerMap = Map<string, Array<(...args: unknown[]) => void | Promise<void>>>;
+/**
+ * Validate all `requires` declarations and detect circular dependencies.
+ * Throws with a descriptive error on the first problem found.
+ *
+ * Checks:
+ * - Apparatus requires: every named dependency must exist (kit or apparatus).
+ * - Kit requires: every named dependency must be an apparatus (kits can't
+ *   depend on kits).
+ * - Cycle detection: no circular dependency chains among apparatuses.
+ */
+export declare function validateRequires(kits: LoadedKit[], apparatuses: LoadedApparatus[]): void;
+/**
+ * Sort apparatuses in dependency-resolved order using topological sort.
+ * validateRequires() must be called first to ensure the graph is acyclic.
+ */
+export declare function topoSort(apparatuses: LoadedApparatus[]): LoadedApparatus[];
+/**
+ * Collect advisory warnings for kit contributions that no apparatus
+ * consumes, and for missing recommended apparatuses.
+ *
+ * Returns an array of warning strings. The caller decides how to emit
+ * them (console.warn, logger, etc.).
+ */
+export declare function collectStartupWarnings(kits: LoadedKit[], apparatuses: LoadedApparatus[]): string[];
+/**
+ * Build a StartupContext for an apparatus's start() call.
+ * The context provides event subscription; handlers are stored in the
+ * shared eventHandlers map so fireEvent can invoke them later.
+ */
+export declare function buildStartupContext(eventHandlers: EventHandlerMap): StartupContext;
+/**
+ * Fire a lifecycle event, awaiting each handler sequentially.
+ */
+export declare function fireEvent(eventHandlers: EventHandlerMap, event: string, ...args: unknown[]): Promise<void>;
+//# sourceMappingURL=guild-lifecycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guild-lifecycle.d.ts","sourceRoot":"","sources":["../src/guild-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,eAAe,EAChB,MAAM,wBAAwB,CAAC;AAIhC,MAAM,MAAM,eAAe,GAAG,GAAG,CAC/B,MAAM,EACN,KAAK,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CACpD,CAAC;AAIF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,SAAS,EAAE,EACjB,WAAW,EAAE,eAAe,EAAE,GAC7B,IAAI,CA2DN;AAID;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,WAAW,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAoB1E;AAID;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAS,SAAS,EAAE,EACxB,WAAW,EAAE,eAAe,EAAE,GAC7B,MAAM,EAAE,CA4CV;AAID;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,eAAe,GAC7B,cAAc,CAQhB;AAED;;GAEG;AACH,wBAAsB,SAAS,CAC7B,aAAa,EAAE,eAAe,EAC9B,KAAK,EAAU,MAAM,EACrB,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,IAAI,CAAC,CAKf"}

package/dist/guild-lifecycle.js

@@ -0,0 +1,164 @@
+/**
+ * Guild lifecycle — pure logic for plugin validation, ordering, and events.
+ *
+ * All functions here operate on in-memory data structures (LoadedKit[],
+ * LoadedApparatus[], Maps) with no I/O. This makes them independently
+ * testable with synthetic fixtures.
+ *
+ * `createGuild()` in arbor.ts is the orchestrator that performs I/O
+ * (config reading, dynamic imports) then delegates to these functions.
+ */
+// ── Validation ───────────────────────────────────────────────────────
+/**
+ * Validate all `requires` declarations and detect circular dependencies.
+ * Throws with a descriptive error on the first problem found.
+ *
+ * Checks:
+ * - Apparatus requires: every named dependency must exist (kit or apparatus).
+ * - Kit requires: every named dependency must be an apparatus (kits can't
+ *   depend on kits).
+ * - Cycle detection: no circular dependency chains among apparatuses.
+ */
+export function validateRequires(kits, apparatuses) {
+    const apparatusIds = new Set(apparatuses.map((a) => a.id));
+    const allIds = new Set([
+        ...kits.map((k) => k.id),
+        ...apparatuses.map((a) => a.id),
+    ]);
+    // Check apparatus requires
+    for (const app of apparatuses) {
+        for (const dep of app.apparatus.requires ?? []) {
+            if (!allIds.has(dep)) {
+                throw new Error(`[arbor] "${app.id}" requires "${dep}", which is not installed.`);
+            }
+        }
+    }
+    // Check kit requires (must be apparatus names — kits can't depend on kits)
+    for (const kit of kits) {
+        for (const dep of kit.kit.requires ?? []) {
+            if (!apparatusIds.has(dep)) {
+                if (!allIds.has(dep)) {
+                    throw new Error(`[arbor] kit "${kit.id}" requires "${dep}", which is not installed.`);
+                }
+                throw new Error(`[arbor] kit "${kit.id}" requires "${dep}", but that plugin is a kit, not an apparatus. ` +
+                    `Kit requires must name apparatus plugins.`);
+            }
+        }
+    }
+    // Detect circular dependencies among apparatuses
+    const visiting = new Set();
+    const visited = new Set();
+    function visit(id, chain) {
+        if (visited.has(id))
+            return;
+        if (visiting.has(id)) {
+            const cycle = [...chain, id].join(' → ');
+            throw new Error(`[arbor] Circular dependency detected: ${cycle}`);
+        }
+        visiting.add(id);
+        const app = apparatuses.find((a) => a.id === id);
+        if (app) {
+            for (const dep of app.apparatus.requires ?? []) {
+                visit(dep, [...chain, id]);
+            }
+        }
+        visiting.delete(id);
+        visited.add(id);
+    }
+    for (const app of apparatuses) {
+        visit(app.id, []);
+    }
+}
+// ── Dependency ordering ──────────────────────────────────────────────
+/**
+ * Sort apparatuses in dependency-resolved order using topological sort.
+ * validateRequires() must be called first to ensure the graph is acyclic.
+ */
+export function topoSort(apparatuses) {
+    const sorted = [];
+    const visited = new Set();
+    function visit(id) {
+        if (visited.has(id))
+            return;
+        const app = apparatuses.find((a) => a.id === id);
+        if (!app)
+            return;
+        for (const dep of app.apparatus.requires ?? []) {
+            visit(dep);
+        }
+        visited.add(id);
+        sorted.push(app);
+    }
+    for (const app of apparatuses) {
+        visit(app.id);
+    }
+    return sorted;
+}
+// ── Startup warnings ─────────────────────────────────────────────────
+/**
+ * Collect advisory warnings for kit contributions that no apparatus
+ * consumes, and for missing recommended apparatuses.
+ *
+ * Returns an array of warning strings. The caller decides how to emit
+ * them (console.warn, logger, etc.).
+ */
+export function collectStartupWarnings(kits, apparatuses) {
+    const warnings = [];
+    const consumedTypes = new Set();
+    const installedIds = new Set(apparatuses.map((a) => a.id));
+    for (const app of apparatuses) {
+        for (const token of app.apparatus.consumes ?? []) {
+            consumedTypes.add(token);
+        }
+    }
+    // Check apparatus recommends
+    for (const app of apparatuses) {
+        for (const rec of app.apparatus.recommends ?? []) {
+            if (!installedIds.has(rec)) {
+                warnings.push(`[arbor] warn: "${app.id}" recommends "${rec}" but it is not installed.`);
+            }
+        }
+    }
+    for (const kit of kits) {
+        // Check kit recommends
+        for (const rec of kit.kit.recommends ?? []) {
+            if (!installedIds.has(rec)) {
+                warnings.push(`[arbor] warn: "${kit.id}" recommends "${rec}" but it is not installed.`);
+            }
+        }
+        // Check contribution types against consumes
+        for (const key of Object.keys(kit.kit)) {
+            if (key === 'requires' || key === 'recommends')
+                continue;
+            if (!consumedTypes.has(key)) {
+                warnings.push(`[arbor] warn: "${kit.id}" contributes "${key}" but no installed apparatus declares consumes: ["${key}"]`);
+            }
+        }
+    }
+    return warnings;
+}
+// ── Event system ─────────────────────────────────────────────────────
+/**
+ * Build a StartupContext for an apparatus's start() call.
+ * The context provides event subscription; handlers are stored in the
+ * shared eventHandlers map so fireEvent can invoke them later.
+ */
+export function buildStartupContext(eventHandlers) {
+    return {
+        on(event, handler) {
+            const list = eventHandlers.get(event) ?? [];
+            list.push(handler);
+            eventHandlers.set(event, list);
+        },
+    };
+}
+/**
+ * Fire a lifecycle event, awaiting each handler sequentially.
+ */
+export async function fireEvent(eventHandlers, event, ...args) {
+    const handlers = eventHandlers.get(event) ?? [];
+    for (const h of handlers) {
+        await h(...args);
+    }
+}
+//# sourceMappingURL=guild-lifecycle.js.map

package/dist/guild-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guild-lifecycle.js","sourceRoot":"","sources":["../src/guild-lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @shardworks/nexus-arbor — guild runtime
+ *
+ * The arbor is the guild host: plugin loading, dependency validation,
+ * apparatus lifecycle management. It does NOT own tool discovery — that
+ * belongs to The Instrumentarium (tools-apparatus).
+ *
+ * Plugin authors never import from arbor — they import from @shardworks/nexus-core.
+ * The CLI imports from arbor to create the guild runtime and trigger startup.
+ *
+ * Package dependency graph:
+ *   core   — public SDK, types, tool() factory
+ *   arbor  — guild host, createGuild()
+ *   cli    — nsg binary, Commander.js, framework commands + Instrumentarium tools
+ *   plugins — import from core only
+ */
+export { createGuild } from './arbor.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @shardworks/nexus-arbor — guild runtime
+ *
+ * The arbor is the guild host: plugin loading, dependency validation,
+ * apparatus lifecycle management. It does NOT own tool discovery — that
+ * belongs to The Instrumentarium (tools-apparatus).
+ *
+ * Plugin authors never import from arbor — they import from @shardworks/nexus-core.
+ * The CLI imports from arbor to create the guild runtime and trigger startup.
+ *
+ * Package dependency graph:
+ *   core   — public SDK, types, tool() factory
+ *   arbor  — guild host, createGuild()
+ *   cli    — nsg binary, Commander.js, framework commands + Instrumentarium tools
+ *   plugins — import from core only
+ */
+export { createGuild } from "./arbor.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@shardworks/nexus-arbor",
+  "version": "0.1.101",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shardworks/nexus",
+    "directory": "packages/framework/arbor"
+  },
+  "description": "The Arbor — guild runtime host: loads plugins, validates dependencies, starts apparatus in order, wires the guild() singleton",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@shardworks/nexus-core": "0.1.101"
+  },
+  "devDependencies": {
+    "@types/node": "25.5.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --disable-warning=ExperimentalWarning --experimental-transform-types --test 'src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  }
+}