@shardworks/nexus-core 0.1.270 → 0.1.271

package/README.md

@@ -101,11 +101,12 @@ writeGuildConfig(home, config);
 | `name` | `string` | Guild name |
 | `nexus` | `string` | Framework version at last init/upgrade |
 | `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` |
 
-All other top-level keys are plugin configuration sections, keyed by derived plugin id.
+All other top-level keys are plugin configuration sections, keyed by derived
+plugin id. Plugin-owned sections (e.g. `clockworks?`, `lattice?`) are
+contributed via `declare module '@shardworks/nexus-core'` from the owning
+apparatus package; the shape of those sections lives with the plugin, not here.
 
 ### Other Exports
 
@@ -113,10 +114,6 @@ All other top-level keys are plugin configuration sections, keyed by derived plu
 |---|---|
 | `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` |
 
 ---

package/dist/guild-config.d.ts

@@ -1,29 +1,3 @@
-/** A custom event declaration in guild.json clockworks.events. */
-export interface EventDeclaration {
-    /** Human-readable description of what this event means. */
-    description?: string;
-    /** Optional payload schema hint (not enforced in Phase 1). */
-    schema?: Record<string, string>;
-}
-/** A standing order — a registered response to an event. */
-export type StandingOrder = {
-    on: string;
-    run: string;
-} | {
-    on: string;
-    summon: string;
-    prompt?: string;
-} | {
-    on: string;
-    brief: string;
-};
-/** The clockworks configuration block in guild.json. */
-export interface ClockworksConfig {
-    /** Custom event declarations. */
-    events?: Record<string, EventDeclaration>;
-    /** Standing orders — event → action mappings. */
-    standingOrders?: StandingOrder[];
-}
 /** Guild-level settings — operational flags and preferences. */
 export interface GuildSettings {
     /**
@@ -45,6 +19,11 @@ export interface GuildSettings {
  * 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.
+ *
+ * Plugin-owned config sections (e.g. `clockworks?`, `lattice?`) are contributed
+ * via `declare module '@shardworks/nexus-core'` from the owning apparatus
+ * package. GuildConfig is an open interface — anything a plugin augments onto
+ * it is visible at every call site that imports this type.
  */
 export interface GuildConfig {
     /** Guild name — used as the guildhall npm package name. */
@@ -53,8 +32,6 @@ export interface GuildConfig {
     nexus: string;
     /** Installed plugin ids (derived from npm package names). Always present; starts empty. */
     plugins: string[];
-    /** Clockworks configuration — events, standing orders. */
-    clockworks?: ClockworksConfig;
     /** Guild-level settings — operational flags and preferences. Includes default model. */
     settings?: GuildSettings;
 }

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,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"}
+{"version":3,"file":"guild-config.d.ts","sourceRoot":"","sources":["../src/guild-config.ts"],"names":[],"mappings":"AAGA,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;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,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.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;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"}
+{"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;AAyC7B;;;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

@@ -9,6 +9,13 @@
  * it via `setGuild()`. The instance is backed by live data structures
  * (e.g. the provides Map) that are populated progressively as apparatus start.
  *
+ * The `Guild` interface is the contract plugin code sees — it deliberately
+ * does not expose `shutdown()`. Lifecycle teardown is the responsibility
+ * of the bootstrapping process (the CLI, a daemon entry point, a one-shot
+ * helper) that called `createGuild()`. That caller receives a
+ * `StartedGuild` (a `Guild` plus a `shutdown()` method) and is expected
+ * to invoke it before exit. See `StartedGuild` and `clearGuild()` below.
+ *
  * See: docs/architecture/plugins.md
  */
 import type { GuildConfig } from './guild-config.ts';
@@ -17,7 +24,10 @@ import type { LoadedKit, LoadedApparatus, FailedPlugin } from './plugin.ts';
  * Runtime access to guild infrastructure.
  *
  * Available after Arbor creates the instance (before apparatus start).
- * One instance per process.
+ * One instance per process. Plugin code only ever sees this narrow
+ * interface — `shutdown()` is intentionally not part of it. The
+ * bootstrap caller of `createGuild()` receives the richer
+ * `StartedGuild` and owns the shutdown lifecycle.
  */
 export interface Guild {
     /** Absolute path to the guild root (contains guild.json). */
@@ -65,6 +75,43 @@ export interface Guild {
     /** Advisory warnings collected during guild startup (missing recommends, unconsumed contributions). */
     startupWarnings(): string[];
 }
+/**
+ * Extension of {@link Guild} returned by `createGuild()` — adds the
+ * `shutdown()` method that drives reverse-topo apparatus teardown.
+ *
+ * The `Guild` interface is what plugin code sees through the
+ * process-level singleton; `shutdown()` is deliberately not exposed
+ * there because plugin code has no legitimate reason to tear down the
+ * guild it is running inside. The bootstrap caller of `createGuild()`
+ * — a CLI command, a daemon entry point, or a one-shot helper —
+ * receives this richer type and is responsible for invoking
+ * `shutdown()` on the way out.
+ *
+ * `shutdown()` invokes every started apparatus's optional `stop()` in
+ * reverse topological order, fires the `guild:shutdown` lifecycle
+ * event before any `stop()` runs, collects per-apparatus errors and
+ * surfaces them as a single aggregate (continuing iteration even when
+ * one throws), is idempotent under repeated calls, and clears the
+ * `guild()` singleton as its last act so subsequent `guild()` calls
+ * fail loudly with the existing "Guild not initialized" error rather
+ * than handing out stale references to apparatus whose handles are
+ * already gone.
+ */
+export interface StartedGuild extends Guild {
+    /**
+     * Tear the guild down: fire `guild:shutdown`, call `stop()` on every
+     * started apparatus in reverse topological order, then clear the
+     * `guild()` singleton.
+     *
+     * Idempotent — second and subsequent calls return immediately.
+     *
+     * If one or more `stop()` invocations throw, every remaining
+     * apparatus is still attempted; once iteration completes, an
+     * aggregate `Error` is thrown summarising each failure. The
+     * singleton is cleared regardless of whether any `stop()` threw.
+     */
+    shutdown(): Promise<void>;
+}
 /**
  * Get the active guild instance.
  *
@@ -79,9 +126,16 @@ export declare function guild(): Guild;
  */
 export declare function setGuild(g: Guild): void;
 /**
- * Clear the guild instance. Called by Arbor at shutdown or in tests.
+ * Clear the guild instance.
  *
- * Not for plugin use — this is framework infrastructure.
+ * Called as the last act of `StartedGuild.shutdown()` after every
+ * apparatus's optional `stop()` has run, so subsequent `guild()` calls
+ * fail loudly with the "Guild not initialized" error rather than
+ * handing out stale references to apparatus whose handles are gone.
+ * Tests call it directly to reset between cases.
+ *
+ * Not for plugin use — this is framework infrastructure. Plugin code
+ * should never need to tear the guild down.
  */
 export declare function clearGuild(): void;
 //# sourceMappingURL=guild.d.ts.map

package/dist/guild.d.ts.map

@@ -1 +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,YAAY,EAAE,MAAM,aAAa,CAAC;AAI5E;;;;;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,6FAA6F;IAC7F,IAAI,IAAI,SAAS,EAAE,CAAA;IAEnB,2CAA2C;IAC3C,WAAW,IAAI,eAAe,EAAE,CAAA;IAEhC,mEAAmE;IACnE,aAAa,IAAI,YAAY,EAAE,CAAA;IAE/B,uGAAuG;IACvG,eAAe,IAAI,MAAM,EAAE,CAAA;CAC5B;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"}
+{"version":3,"file":"guild.d.ts","sourceRoot":"","sources":["../src/guild.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI5E;;;;;;;;GAQG;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,6FAA6F;IAC7F,IAAI,IAAI,SAAS,EAAE,CAAA;IAEnB,2CAA2C;IAC3C,WAAW,IAAI,eAAe,EAAE,CAAA;IAEhC,mEAAmE;IACnE,aAAa,IAAI,YAAY,EAAE,CAAA;IAE/B,uGAAuG;IACvG,eAAe,IAAI,MAAM,EAAE,CAAA;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,YAAa,SAAQ,KAAK;IACzC;;;;;;;;;;;OAWG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAMD;;;;;GAKG;AACH,wBAAgB,KAAK,IAAI,KAAK,CAQ7B;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI,CAEvC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}

package/dist/guild.js

@@ -9,6 +9,13 @@
  * it via `setGuild()`. The instance is backed by live data structures
  * (e.g. the provides Map) that are populated progressively as apparatus start.
  *
+ * The `Guild` interface is the contract plugin code sees — it deliberately
+ * does not expose `shutdown()`. Lifecycle teardown is the responsibility
+ * of the bootstrapping process (the CLI, a daemon entry point, a one-shot
+ * helper) that called `createGuild()`. That caller receives a
+ * `StartedGuild` (a `Guild` plus a `shutdown()` method) and is expected
+ * to invoke it before exit. See `StartedGuild` and `clearGuild()` below.
+ *
  * See: docs/architecture/plugins.md
  */
 // ── Singleton ──────────────────────────────────────────────────────────
@@ -35,9 +42,16 @@ export function setGuild(g) {
     _guild = g;
 }
 /**
- * Clear the guild instance. Called by Arbor at shutdown or in tests.
+ * Clear the guild instance.
  *
- * Not for plugin use — this is framework infrastructure.
+ * Called as the last act of `StartedGuild.shutdown()` after every
+ * apparatus's optional `stop()` has run, so subsequent `guild()` calls
+ * fail loudly with the "Guild not initialized" error rather than
+ * handing out stale references to apparatus whose handles are gone.
+ * Tests call it directly to reset between cases.
+ *
+ * Not for plugin use — this is framework infrastructure. Plugin code
+ * should never need to tear the guild down.
  */
 export function clearGuild() {
     _guild = null;

package/dist/guild.js.map

@@ -1 +1 @@
-{"version":3,"file":"guild.js","sourceRoot":"","sources":["../src/guild.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAoEH,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"}
+{"version":3,"file":"guild.js","sourceRoot":"","sources":["../src/guild.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA6GH,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;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC"}

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export declare const VERSION: string;
 export { type Kit, type Apparatus, type Plugin, type LoadedKit, type LoadedApparatus, type LoadedPlugin, type FailedPlugin, type StartupContext, type KitEntry, isKit, isApparatus, isLoadedKit, isLoadedApparatus, } from './plugin.ts';
-export { type Guild, guild, setGuild, clearGuild, } from './guild.ts';
+export { type Guild, type StartedGuild, guild, setGuild, clearGuild, } from './guild.ts';
 export { findGuildRoot, nexusDir, worktreesPath, clockPidPath, clockLogPath, } from './nexus-home.ts';
+export { isProcessAlive, readPidFile, tryUnlink, waitForExit, } from './pid-helpers.ts';
 export { derivePluginId, readGuildPackageJson, resolvePackageNameForPluginId, resolveGuildPackageEntry, } from './resolve-package.ts';
-export { type GuildConfig, createInitialGuildConfig, readGuildConfig, writeGuildConfig, type EventDeclaration, type StandingOrder, type ClockworksConfig, type GuildSettings, guildConfigPath, } from './guild-config.ts';
+export { type GuildConfig, createInitialGuildConfig, readGuildConfig, writeGuildConfig, type GuildSettings, guildConfigPath, } from './guild-config.ts';
 export { generateId, shortId } from './id.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,OAAO,EAAE,MAAqB,CAAC;AAI5C,OAAO,EAEL,KAAK,GAAG,EACR,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,EACL,WAAW,EACX,WAAW,EACX,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,KAAK,KAAK,EACV,KAAK,EACL,QAAQ,EACR,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,6BAA6B,EAC7B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,WAAW,EAChB,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,OAAO,EAAE,MAAqB,CAAC;AAI5C,OAAO,EAEL,KAAK,GAAG,EACR,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,EACL,WAAW,EACX,WAAW,EACX,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,KAAK,KAAK,EACV,KAAK,YAAY,EACjB,KAAK,EACL,QAAQ,EACR,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,cAAc,EACd,WAAW,EACX,SAAS,EACT,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,6BAA6B,EAC7B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,WAAW,EAChB,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAChB,KAAK,aAAa,EAClB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -8,6 +8,7 @@ export { isKit, isApparatus, isLoadedKit, isLoadedApparatus, } from "./plugin.js
 // Guild — the process-level singleton for accessing guild infrastructure.
 export { guild, setGuild, clearGuild, } from "./guild.js";
 export { findGuildRoot, nexusDir, worktreesPath, clockPidPath, clockLogPath, } from "./nexus-home.js";
+export { isProcessAlive, readPidFile, tryUnlink, waitForExit, } from "./pid-helpers.js";
 export { derivePluginId, readGuildPackageJson, resolvePackageNameForPluginId, resolveGuildPackageEntry, } from "./resolve-package.js";
 export { createInitialGuildConfig, readGuildConfig, writeGuildConfig, guildConfigPath, } from "./guild-config.js";
 export { generateId, shortId } from "./id.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAE9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAAC;AACzC,MAAM,CAAC,MAAM,OAAO,GAAW,IAAI,CAAC,OAAO,CAAC;AAE5C,0EAA0E;AAE1E,OAAO,EAWL,KAAK,EACL,WAAW,EACX,WAAW,EACX,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAErB,0EAA0E;AAC1E,OAAO,EAEL,KAAK,EACL,QAAQ,EACR,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,6BAA6B,EAC7B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAEL,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAKhB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAE9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAAC;AACzC,MAAM,CAAC,MAAM,OAAO,GAAW,IAAI,CAAC,OAAO,CAAC;AAE5C,0EAA0E;AAE1E,OAAO,EAWL,KAAK,EACL,WAAW,EACX,WAAW,EACX,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAErB,0EAA0E;AAC1E,OAAO,EAGL,KAAK,EACL,QAAQ,EACR,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,cAAc,EACd,WAAW,EACX,SAAS,EACT,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,6BAA6B,EAC7B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAEL,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAEhB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC"}

package/dist/pid-helpers.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared PID-file and process-liveness helpers for daemon-style commands.
+ *
+ * Two daemons live in the framework today: `nsg start` (the guild daemon)
+ * and `nsg clock start` (the Clockworks daemon). Both share the same
+ * lifecycle primitives — read a pidfile, decide whether the pid behind
+ * it is still alive, unlink the pidfile when the daemon is gone, and
+ * poll until a pid actually exits after a SIGTERM.
+ *
+ * Centralising these helpers in `@shardworks/nexus-core` lets the CLI
+ * (`packages/framework/cli`) and the Clockworks apparatus
+ * (`packages/plugins/clockworks`) consume them without either depending
+ * on the other.
+ */
+/**
+ * Returns true when a process with the given pid is alive on this host.
+ *
+ * Uses signal 0 (the existence probe). The corner case worth knowing:
+ * `EPERM` means the process exists but we lack permission to signal it —
+ * we still treat it as alive.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Read a pidfile and parse it into a positive integer pid. Returns null
+ * when the file is missing, unreadable, empty, or contains a value that
+ * doesn't parse as a positive number.
+ */
+export declare function readPidFile(pidFile: string): number | null;
+/**
+ * Delete a file, swallowing any error. Used for pidfile cleanup where
+ * a stale or already-deleted file should not be a fatal condition.
+ */
+export declare function tryUnlink(file: string): void;
+/**
+ * Poll `isProcessAlive(pid)` every 200ms until the pid exits or the
+ * timeout elapses. Returns true if the process exited within the
+ * window, false otherwise.
+ */
+export declare function waitForExit(pid: number, timeoutMs: number): Promise<boolean>;
+//# sourceMappingURL=pid-helpers.d.ts.map

package/dist/pid-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pid-helpers.d.ts","sourceRoot":"","sources":["../src/pid-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAUnD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ1D;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAM5C;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOlF"}

package/dist/pid-helpers.js

@@ -0,0 +1,77 @@
+/**
+ * Shared PID-file and process-liveness helpers for daemon-style commands.
+ *
+ * Two daemons live in the framework today: `nsg start` (the guild daemon)
+ * and `nsg clock start` (the Clockworks daemon). Both share the same
+ * lifecycle primitives — read a pidfile, decide whether the pid behind
+ * it is still alive, unlink the pidfile when the daemon is gone, and
+ * poll until a pid actually exits after a SIGTERM.
+ *
+ * Centralising these helpers in `@shardworks/nexus-core` lets the CLI
+ * (`packages/framework/cli`) and the Clockworks apparatus
+ * (`packages/plugins/clockworks`) consume them without either depending
+ * on the other.
+ */
+import fs from 'node:fs';
+/**
+ * Returns true when a process with the given pid is alive on this host.
+ *
+ * Uses signal 0 (the existence probe). The corner case worth knowing:
+ * `EPERM` means the process exists but we lack permission to signal it —
+ * we still treat it as alive.
+ */
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ESRCH')
+            return false;
+        // EPERM → exists but we can't signal it. Treat as alive.
+        return true;
+    }
+}
+/**
+ * Read a pidfile and parse it into a positive integer pid. Returns null
+ * when the file is missing, unreadable, empty, or contains a value that
+ * doesn't parse as a positive number.
+ */
+export function readPidFile(pidFile) {
+    try {
+        const raw = fs.readFileSync(pidFile, 'utf-8').trim();
+        const pid = Number(raw);
+        return Number.isFinite(pid) && pid > 0 ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Delete a file, swallowing any error. Used for pidfile cleanup where
+ * a stale or already-deleted file should not be a fatal condition.
+ */
+export function tryUnlink(file) {
+    try {
+        fs.unlinkSync(file);
+    }
+    catch {
+        // ignore
+    }
+}
+/**
+ * Poll `isProcessAlive(pid)` every 200ms until the pid exits or the
+ * timeout elapses. Returns true if the process exited within the
+ * window, false otherwise.
+ */
+export async function waitForExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isProcessAlive(pid))
+            return true;
+        await new Promise((r) => setTimeout(r, 200));
+    }
+    return false;
+}
+//# sourceMappingURL=pid-helpers.js.map

package/dist/pid-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pid-helpers.js","sourceRoot":"","sources":["../src/pid-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,OAAO;YAAE,OAAO,KAAK,CAAC;QACnC,yDAAyD;QACzD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QACrD,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,SAAS;IACX,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW,EAAE,SAAiB;IAC9D,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IACxC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC7B,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QACtC,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardworks/nexus-core",
-  "version": "0.1.270",
+  "version": "0.1.271",
   "license": "ISC",
   "repository": {
     "type": "git",