@shardworks/loom-apparatus 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,128 @@
+# `@shardworks/loom-apparatus`
+
+The Loom — the guild's session context composer. This apparatus owns system prompt assembly: given a role name, it weaves charter, curricula, temperament, and role instructions into an `AnimaWeave` that The Animator consumes to launch AI sessions. The work prompt (what the anima should do) bypasses The Loom — it is not a composition concern.
+
+MVP: system prompt composition is not yet implemented — `weave()` returns an empty `AnimaWeave` (systemPrompt undefined). The role is accepted but not yet used. The seam exists now so the contract is stable as composition logic is built out.
+
+```
+caller (Animator.summon)         → weave({ role })
+@shardworks/loom-apparatus       → AnimaWeave { systemPrompt? }
+The Animator                     → launches session with weave + work prompt
+```
+
+---
+
+## Installation
+
+```json
+{
+  "dependencies": {
+    "@shardworks/loom-apparatus": "workspace:*"
+  }
+}
+```
+
+Plugin id: `loom`
+
+---
+
+## API
+
+The Loom exposes `LoomApi` via `provides`, accessed by other plugins as:
+
+```typescript
+import { guild } from '@shardworks/nexus-core';
+import type { LoomApi } from '@shardworks/loom-apparatus';
+
+const loom = guild().apparatus<LoomApi>('loom');
+```
+
+### `LoomApi`
+
+```typescript
+interface LoomApi {
+  /**
+   * Weave an anima's session context.
+   *
+   * Given a role name, produces an AnimaWeave containing the composed
+   * system prompt. MVP: returns undefined for systemPrompt.
+   */
+  weave(request: WeaveRequest): Promise<AnimaWeave>;
+}
+```
+
+### `WeaveRequest`
+
+```typescript
+interface WeaveRequest {
+  /**
+   * The role to weave context for (e.g. 'artificer', 'scribe').
+   * MVP: accepted but not used. Future: resolves role instructions,
+   * curriculum, temperament, and composes the system prompt.
+   */
+  role?: string;
+}
+```
+
+### `AnimaWeave`
+
+```typescript
+interface AnimaWeave {
+  /** The system prompt for the AI process. Undefined until composition is implemented. */
+  systemPrompt?: string;
+}
+```
+
+### Usage Examples
+
+**Weave a context for a role:**
+
+```typescript
+const loom = guild().apparatus<LoomApi>('loom');
+
+const weave = await loom.weave({ role: 'artificer' });
+// MVP → { systemPrompt: undefined }
+// Future → { systemPrompt: '<woven from charter + curricula + ...>' }
+```
+
+**Via The Animator (typical path):**
+
+```typescript
+const animator = guild().apparatus<AnimatorApi>('animator');
+
+// summon() calls loom.weave() internally — you don't need to call it directly
+const result = await animator.summon({
+  role: 'artificer',
+  prompt: 'Build the frobnicator module with tests',
+  cwd: '/path/to/workdir',
+});
+```
+
+---
+
+## Configuration
+
+MVP: none. The Loom reads no guild configuration.
+
+Future versions will read role definitions, anima identity records, charter content, and curricula from guild config and The Stacks.
+
+---
+
+## Exports
+
+```typescript
+// Loom API types
+import {
+  type LoomApi,
+  type WeaveRequest,
+  type AnimaWeave,
+  createLoom,
+} from '@shardworks/loom-apparatus';
+```
+
+The default export is the apparatus plugin instance, ready for use in `guild.json`:
+
+```typescript
+import loom from '@shardworks/loom-apparatus';
+// → Plugin with apparatus.provides = LoomApi
+```

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @shardworks/loom-apparatus — The Loom.
+ *
+ * Session context composition: weaves role instructions, curricula, and
+ * temperaments into an AnimaWeave that The Animator can consume to
+ * launch AI sessions.
+ *
+ * See: docs/specification.md (loom)
+ */
+export { type LoomApi, type WeaveRequest, type AnimaWeave, type LoomConfig, type RoleDefinition, createLoom, } from './loom.ts';
+import type { LoomConfig } from './loom.ts';
+declare module '@shardworks/nexus-core' {
+    interface GuildConfig {
+        loom?: LoomConfig;
+    }
+}
+declare const _default: import("@shardworks/nexus-core").Plugin;
+export default _default;
+//# 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;;;;;;;;GAQG;AAMH,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,UAAU,GACX,MAAM,WAAW,CAAC;AAMnB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,WAAW;QACnB,IAAI,CAAC,EAAE,UAAU,CAAC;KACnB;CACF;;AAID,wBAA4B"}

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @shardworks/loom-apparatus — The Loom.
+ *
+ * Session context composition: weaves role instructions, curricula, and
+ * temperaments into an AnimaWeave that The Animator can consume to
+ * launch AI sessions.
+ *
+ * See: docs/specification.md (loom)
+ */
+import { createLoom } from "./loom.js";
+// ── Loom API ─────────────────────────────────────────────────────────
+export { createLoom, } from "./loom.js";
+// ── Default export: the apparatus plugin ──────────────────────────────
+export default createLoom();
+//# 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;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,wEAAwE;AAExE,OAAO,EAML,UAAU,GACX,MAAM,WAAW,CAAC;AAanB,yEAAyE;AAEzE,eAAe,UAAU,EAAE,CAAC"}

package/dist/loom.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The Loom — session context composition apparatus.
+ *
+ * The Loom owns system prompt assembly. Given a role name, it produces
+ * an AnimaWeave — the composed identity context that The Animator uses
+ * to launch a session. The work prompt (what the anima should do) is
+ * not the Loom's concern; it bypasses the Loom and goes directly to
+ * the Animator.
+ *
+ * The Loom resolves the role's permission grants from guild.json, then
+ * calls the Instrumentarium to resolve the permission-gated tool set.
+ * Tools are returned on the AnimaWeave so the Animator can pass them
+ * to the session provider for MCP server configuration.
+ *
+ * See: docs/specification.md (loom)
+ */
+import type { Plugin } from '@shardworks/nexus-core';
+import type { ResolvedTool } from '@shardworks/tools-apparatus';
+export interface WeaveRequest {
+    /**
+     * The role to weave context for (e.g. 'artificer', 'scribe').
+     *
+     * When provided, the Loom resolves role → permissions from guild.json,
+     * then calls the Instrumentarium to resolve the permission-gated tool set.
+     * Tools are returned on the AnimaWeave.
+     *
+     * When omitted, no tool resolution occurs — the AnimaWeave has no tools.
+     */
+    role?: string;
+}
+/**
+ * The output of The Loom's weave() — the composed anima identity context.
+ *
+ * Contains the system prompt (produced by the Loom from the anima's
+ * identity layers) and the resolved tool set for the role. The work
+ * prompt is not part of the weave — it goes directly to the Animator.
+ */
+export interface AnimaWeave {
+    /** The system prompt for the AI process. Undefined until composition is implemented. */
+    systemPrompt?: string;
+    /** The resolved tool set for this role. Undefined when no role is specified or no tools match. */
+    tools?: ResolvedTool[];
+}
+/** The Loom's public API, exposed via `provides`. */
+export interface LoomApi {
+    /**
+     * Weave an anima's session context.
+     *
+     * Given a role name, produces an AnimaWeave containing the composed
+     * system prompt and the resolved tool set. System prompt composition
+     * (charter, curricula, temperament, role instructions) is future work —
+     * systemPrompt remains undefined until then.
+     *
+     * Tool resolution is active: if a role is provided and the Instrumentarium
+     * is installed, the Loom resolves role → permissions → tools.
+     */
+    weave(request: WeaveRequest): Promise<AnimaWeave>;
+}
+/** Role definition in guild.json under the Loom's plugin section. */
+export interface RoleDefinition {
+    /** Permission grants in `plugin:level` format. */
+    permissions: string[];
+    /**
+     * When true, permissionless tools are excluded unless the role grants
+     * `plugin:*` or `*:*` for the tool's plugin. Default: false.
+     */
+    strict?: boolean;
+}
+/** Loom configuration from guild.json. */
+export interface LoomConfig {
+    /** Role definitions keyed by role name. */
+    roles?: Record<string, RoleDefinition>;
+}
+/**
+ * Create the Loom apparatus plugin.
+ *
+ * Returns a Plugin with:
+ * - `requires: ['tools']` — needs the Instrumentarium for tool resolution
+ * - `provides: LoomApi` — the context composition API
+ */
+export declare function createLoom(): Plugin;
+//# sourceMappingURL=loom.d.ts.map

package/dist/loom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loom.d.ts","sourceRoot":"","sources":["../src/loom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,wBAAwB,CAAC;AAErE,OAAO,KAAK,EAAsB,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAIpF,MAAM,WAAW,YAAY;IAC3B;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,wFAAwF;IACxF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kGAAkG;IAClG,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,qDAAqD;AACrD,MAAM,WAAW,OAAO;IACtB;;;;;;;;;;OAUG;IACH,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACnD;AAID,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,0CAA0C;AAC1C,MAAM,WAAW,UAAU;IACzB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACxC;AAID;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,MAAM,CA2CnC"}

package/dist/loom.js

@@ -0,0 +1,66 @@
+/**
+ * The Loom — session context composition apparatus.
+ *
+ * The Loom owns system prompt assembly. Given a role name, it produces
+ * an AnimaWeave — the composed identity context that The Animator uses
+ * to launch a session. The work prompt (what the anima should do) is
+ * not the Loom's concern; it bypasses the Loom and goes directly to
+ * the Animator.
+ *
+ * The Loom resolves the role's permission grants from guild.json, then
+ * calls the Instrumentarium to resolve the permission-gated tool set.
+ * Tools are returned on the AnimaWeave so the Animator can pass them
+ * to the session provider for MCP server configuration.
+ *
+ * See: docs/specification.md (loom)
+ */
+import { guild } from '@shardworks/nexus-core';
+// ── Apparatus factory ─────────────────────────────────────────────────
+/**
+ * Create the Loom apparatus plugin.
+ *
+ * Returns a Plugin with:
+ * - `requires: ['tools']` — needs the Instrumentarium for tool resolution
+ * - `provides: LoomApi` — the context composition API
+ */
+export function createLoom() {
+    let config = {};
+    const api = {
+        async weave(request) {
+            const weave = {};
+            // Resolve tools if a role is provided and has a definition.
+            if (request.role && config.roles) {
+                const roleDef = config.roles[request.role];
+                if (roleDef) {
+                    try {
+                        const instrumentarium = guild().apparatus('tools');
+                        weave.tools = instrumentarium.resolve({
+                            permissions: roleDef.permissions,
+                            strict: roleDef.strict,
+                            caller: 'anima',
+                        });
+                    }
+                    catch {
+                        // Instrumentarium not installed — no tools.
+                        // This shouldn't happen since we require 'tools', but
+                        // fail gracefully rather than crash the session.
+                    }
+                }
+            }
+            // Future: compose system prompt from charter + curriculum +
+            // temperament + role instructions + tool instructions.
+            return weave;
+        },
+    };
+    return {
+        apparatus: {
+            requires: ['tools'],
+            provides: api,
+            start(_ctx) {
+                const g = guild();
+                config = g.guildConfig().loom ?? {};
+            },
+        },
+    };
+}
+//# sourceMappingURL=loom.js.map

package/dist/loom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loom.js","sourceRoot":"","sources":["../src/loom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAmE/C,yEAAyE;AAEzE;;;;;;GAMG;AACH,MAAM,UAAU,UAAU;IACxB,IAAI,MAAM,GAAe,EAAE,CAAC;IAE5B,MAAM,GAAG,GAAY;QACnB,KAAK,CAAC,KAAK,CAAC,OAAqB;YAC/B,MAAM,KAAK,GAAe,EAAE,CAAC;YAE7B,4DAA4D;YAC5D,IAAI,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBACjC,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAC3C,IAAI,OAAO,EAAE,CAAC;oBACZ,IAAI,CAAC;wBACH,MAAM,eAAe,GAAG,KAAK,EAAE,CAAC,SAAS,CAAqB,OAAO,CAAC,CAAC;wBACvE,KAAK,CAAC,KAAK,GAAG,eAAe,CAAC,OAAO,CAAC;4BACpC,WAAW,EAAE,OAAO,CAAC,WAAW;4BAChC,MAAM,EAAE,OAAO,CAAC,MAAM;4BACtB,MAAM,EAAE,OAAO;yBAChB,CAAC,CAAC;oBACL,CAAC;oBAAC,MAAM,CAAC;wBACP,4CAA4C;wBAC5C,sDAAsD;wBACtD,iDAAiD;oBACnD,CAAC;gBACH,CAAC;YACH,CAAC;YAED,4DAA4D;YAC5D,uDAAuD;YACvD,OAAO,KAAK,CAAC;QACf,CAAC;KACF,CAAC;IAEF,OAAO;QACL,SAAS,EAAE;YACT,QAAQ,EAAE,CAAC,OAAO,CAAC;YACnB,QAAQ,EAAE,GAAG;YAEb,KAAK,CAAC,IAAoB;gBACxB,MAAM,CAAC,GAAG,KAAK,EAAE,CAAC;gBAClB,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;YACtC,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@shardworks/loom-apparatus",
+  "version": "0.1.101",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shardworks/nexus",
+    "directory": "packages/plugins/loom"
+  },
+  "description": "The Loom — session context composition apparatus",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "4.3.6",
+    "@shardworks/tools-apparatus": "0.1.101",
+    "@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"
+  }
+}