@huddle-marketplace/skills 0.2.0

package/README.md

@@ -0,0 +1,256 @@
+# @huddle-marketplace/skills
+
+**63-jurisdiction rental compliance skills for autonomous AI agents.**
+
+Validates security deposits, rent payments, late fees, and deposit returns against real statutes across 50 US states, 13 Canadian provinces, and federal overlays. OpenClaw, MCP, LangChain, and CrewAI compatible.
+
+```bash
+npm install @huddle-marketplace/skills
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { validate, composeSkills, registry } from "@huddle-marketplace/skills";
+
+// Single jurisdiction — wBTC bond in Texas
+const result = await validate("US-TX", {
+  type: "deposit-validation",
+  depositAmountCents: 200000,   // $2,000 — always in CENTS
+  monthlyRentCents: 200000,     // $2,000
+  currency: "USDC",
+  collateralType: "wbtc",
+  instrumentType: "collateralized_lease_guarantee",
+});
+
+console.log(result.compliant);    // true
+console.log(result.confidence);   // 0.9
+console.log(result.citations);    // [{ statute: "Texas SB-38", section: "Section 3", ... }]
+
+// Stacked validation — CFTC federal preemption + state rules
+const composed = await composeSkills(["US-CFTC", "US-TX"], {
+  type: "deposit-validation",
+  depositAmountCents: 200000,
+  monthlyRentCents: 200000,
+  currency: "USDC",
+  collateralType: "wbtc",
+  instrumentType: "collateralized_lease_guarantee",
+  wbtcUsdcRatio: 1.05,
+  custodyType: "smart_contract",
+  sentinelMonitoring: true,
+  sentinelMode: "CO_PILOT",
+  lastSentinelCheckMs: Date.now() - 60000,
+  auditLogEnabled: true,
+  lastDecisionReasoning: "LTV nominal",
+});
+
+console.log(composed.compliant);          // true
+console.log(composed.layers.length);      // 2
+console.log(composed.checks[0].name);     // "[US-CFTC] federal-preemption"
+console.log(composed.citations.length);   // merged + deduplicated
+```
+
+---
+
+## API Reference
+
+### `validate(jurisdiction, input)`
+
+Run a single jurisdiction's skill against the input.
+
+```typescript
+const result = await validate("US-CA", input);
+// result: SkillResult
+```
+
+### `composeSkills(jurisdictions, input, options?)`
+
+Stack multiple jurisdictions into one layered compliance proof. Layers run in parallel.
+
+```typescript
+const result = await composeSkills(["US-CFTC", "US-IL"], input);
+// result: ComposedResult — { compliant, confidence, layers[], checks[], citations[], remediation[] }
+
+// Advisory mode: only US-CFTC determines overall compliance
+const result = await composeSkills(["US-CFTC", "US-TX"], input, {
+  mode: "advisory",
+  criticalJurisdictions: ["US-CFTC"],
+});
+```
+
+### `registry`
+
+Pre-loaded registry with all 64 jurisdictions.
+
+```typescript
+registry.get("US-TX")               // HuddleSkill | undefined
+registry.jurisdictions()            // JurisdictionCode[]
+registry.isSupported("US-TX")       // boolean
+registry.search(["deposit-validation"])  // HuddleSkill[]
+```
+
+### `explain(jurisdiction, result)`
+
+Human-readable explanation of a validation result.
+
+```typescript
+const text = explain("US-TX", result);
+// "This transaction PASSES Texas SB-38 & Property Code §92 compliance (confidence: 90%)..."
+```
+
+---
+
+## Jurisdictions
+
+### US States (50)
+
+| Tier | States | Capabilities |
+|---|---|---|
+| **Tier 1 — Full statute logic** | TX, FL, CA, NY | deposit-validation, deposit-return, federal-preemption |
+| **Tier 2 — Real rules** | IL, WA, CO, MA, PA, OH, GA, NC, VA, MI | deposit-validation, payment-compliance, deposit-return, deposit-interest |
+| **Tier 3 — Capped states** | 26 states with statutory caps | deposit-validation, federal-preemption |
+| **Tier 4 — No-cap states** | Remaining states | deposit-validation, federal-preemption |
+
+### Canadian Provinces (13)
+
+| Tier | Provinces |
+|---|---|
+| **Full statute** | BC, ON, QC (bilingual), NS |
+| **Template** | AB, MB, SK, NB, PE, NL, NT, YT, NU |
+
+### Federal Overlays
+
+| Code | Coverage |
+|---|---|
+| `US-CFTC` | CFTC 9180-26: wBTC bond federal preemption, 1:1 reserve ratio, Sentinel monitoring, TRAIGA |
+| `CA-QC` | CCQ art. 1904 deposit prohibition, TAL jurisdiction, bilingual FR/EN citations |
+
+---
+
+## Web3-Native Features
+
+### wBTC Bond Recognition
+
+When `collateralType: "wbtc"` is set, skills recognize that `HuddleDepositVaultV3`'s on-chain Golden Rule (wBTC value ≥ original principal, enforced by Solidity) structurally satisfies — and exceeds — statutory interest requirements:
+
+```typescript
+// IL requires 5% annual interest on deposits
+// wBTC bond → interest check returns confidence: 0.98 (higher than legacy 0.75)
+const result = await validate("US-IL", {
+  type: "deposit-validation",
+  collateralType: "wbtc",  // ← Web3 path
+  ...
+});
+// check "deposit-interest-requirement": passed: true, confidence: 0.98
+// note: "SATISFIED: wBTC bond appreciation via HuddleDepositVaultV3 structurally exceeds..."
+```
+
+### Composition Engine
+
+Federal + state validation in one call:
+
+```typescript
+const result = await composeSkills(["US-CFTC", "US-TX", "US-IL"], input);
+// Runs all 3 in parallel, merges checks, deduplicates citations
+```
+
+---
+
+## Framework Adapters
+
+### MCP (Model Context Protocol)
+
+```typescript
+import { getMCPToolDefinitions, handleMCPRequest } from "@huddle-marketplace/skills/mcp";
+
+const tools = getMCPToolDefinitions();  // Ready for Claude Desktop
+const response = await handleMCPRequest(mcpRequest, registry);
+```
+
+### OpenClaw
+
+```typescript
+import { toOpenClawSkill } from "@huddle-marketplace/skills/openclaw";
+
+const openClawTool = toOpenClawSkill(usTxSkill);
+```
+
+### LangChain
+
+```typescript
+import { registry } from "@huddle-marketplace/skills/langchain";
+// DynamicStructuredTool instances for every jurisdiction
+```
+
+### TRAIGA Audit Logging
+
+```typescript
+import { withTraiga, ConsoleTraigaAdapter } from "@huddle-marketplace/skills/traiga";
+
+const auditedSkill = withTraiga(usTxSkill, new ConsoleTraigaAdapter());
+// Every validation is logged with inputHash, outputHash, decision, confidence
+```
+
+---
+
+## Input Types
+
+All monetary amounts are in **cents** (integer).
+
+```typescript
+// Deposit validation
+{ type: "deposit-validation", depositAmountCents, monthlyRentCents, currency, ... }
+
+// Payment compliance
+{ type: "payment-compliance", paymentAmountCents, monthlyRentCents, dueDate, paymentDate, ... }
+
+// Rent increase
+{ type: "rent-increase-validation", currentRentCents, proposedRentCents, noticeDateDays, ... }
+
+// Deposit return
+{ type: "deposit-return", originalDepositCents, proposedReturnCents, leaseEndDate, returnDate, ... }
+
+// Homeownership readiness
+{ type: "homeownership-readiness", annualIncomeCents, monthlyDebtCents, creditScore, ... }
+```
+
+---
+
+## Publishing (Maintainers)
+
+The CI/CD pipeline automatically publishes to npm when a commit on `main` starts with `release:`.
+
+### Steps
+
+1. Bump version in [package.json](./package.json)
+2. Run prepublish gate locally:
+   ```bash
+   npm run prepublishOnly   # lint + test (146 tests) + build
+   ```
+3. Commit and push:
+   ```bash
+   git add packages/huddle-skills/
+   git commit -m "release: v0.2.0"
+   git push origin main
+   ```
+4. GitHub Actions triggers `.github/workflows/huddle-skills-ci.yml`:
+   - `test` job: lint → 146 tests → build → verify dist
+   - `publish` job (only on `release:` prefix + `NPM_TOKEN` secret): `npm publish --access public`
+
+### Required GitHub Secret
+
+`NPM_TOKEN` — create at [npmjs.com/settings/tokens](https://www.npmjs.com/settings/tokens) (Automation token, read+write), add to repo secrets at Settings → Secrets → Actions.
+
+### Package Size Budget
+
+Target: < 500KB, tree-shakeable per jurisdiction via named exports.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE)
+
+Built by [Huddle Protocol](https://github.com/huddle-protocol)

package/dist/adapters/openclaw.d.ts

@@ -0,0 +1,42 @@
+/**
+ * OpenClaw Adapter
+ *
+ * Wraps Huddle skills in OpenClaw-compatible format.
+ * Each skill becomes an OpenClaw skill with SKILL.md metadata.
+ */
+import type { HuddleSkill, SkillResult, SkillMetadata } from "../types/index.js";
+/** OpenClaw skill manifest (SKILL.md frontmatter) */
+export interface OpenClawManifest {
+    name: string;
+    version: string;
+    description: string;
+    author: string;
+    capabilities: string[];
+    inputs: {
+        schema: string;
+    };
+    outputs: {
+        schema: string;
+    };
+    permissions: string[];
+    tags: string[];
+}
+/** OpenClaw-compatible skill wrapper */
+export interface OpenClawSkill {
+    manifest: OpenClawManifest;
+    execute(input: Record<string, unknown>): Promise<SkillResult>;
+    metadata(): SkillMetadata;
+}
+/**
+ * Convert a HuddleSkill to an OpenClaw-compatible skill
+ */
+export declare function toOpenClawSkill(skill: HuddleSkill): OpenClawSkill;
+/**
+ * Convert all skills to OpenClaw format
+ */
+export declare function toOpenClawSkills(skills: HuddleSkill[]): OpenClawSkill[];
+/**
+ * Generate SKILL.md content for a skill (YAML frontmatter + markdown body)
+ */
+export declare function generateSkillMd(skill: HuddleSkill): string;
+//# sourceMappingURL=openclaw.d.ts.map

package/dist/adapters/openclaw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openclaw.d.ts","sourceRoot":"","sources":["../../src/adapters/openclaw.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAc,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE7F,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3B,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9D,QAAQ,IAAI,aAAa,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,aAAa,CAwBjE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,aAAa,EAAE,CAEvE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAsD1D"}

package/dist/adapters/openclaw.js

@@ -0,0 +1,94 @@
+/**
+ * OpenClaw Adapter
+ *
+ * Wraps Huddle skills in OpenClaw-compatible format.
+ * Each skill becomes an OpenClaw skill with SKILL.md metadata.
+ */
+/**
+ * Convert a HuddleSkill to an OpenClaw-compatible skill
+ */
+export function toOpenClawSkill(skill) {
+    const meta = skill.getMetadata();
+    return {
+        manifest: {
+            name: meta.id,
+            version: meta.version,
+            description: meta.description,
+            author: meta.author,
+            capabilities: meta.capabilities,
+            inputs: { schema: "./schemas/input.json" },
+            outputs: { schema: "./schemas/output.json" },
+            permissions: meta.permissions,
+            tags: meta.tags,
+        },
+        async execute(input) {
+            return skill.validate(input);
+        },
+        metadata() {
+            return skill.getMetadata();
+        },
+    };
+}
+/**
+ * Convert all skills to OpenClaw format
+ */
+export function toOpenClawSkills(skills) {
+    return skills.map(toOpenClawSkill);
+}
+/**
+ * Generate SKILL.md content for a skill (YAML frontmatter + markdown body)
+ */
+export function generateSkillMd(skill) {
+    const meta = skill.getMetadata();
+    const yaml = [
+        "---",
+        `name: ${meta.id}`,
+        `version: ${meta.version}`,
+        `description: ${meta.description}`,
+        `author: ${meta.author}`,
+        `jurisdiction: ${meta.jurisdiction}`,
+        `capabilities: [${meta.capabilities.join(", ")}]`,
+        `permissions: [${meta.permissions.join(", ")}]`,
+        `tags: [${meta.tags.join(", ")}]`,
+        meta.federalPreemption ? `federal_preemption: true` : null,
+        meta.effectiveDate ? `effective_date: ${meta.effectiveDate}` : null,
+        "---",
+    ].filter(Boolean).join("\n");
+    const body = [
+        "",
+        `# ${meta.name}`,
+        "",
+        `## Jurisdiction: ${meta.jurisdiction}`,
+        "",
+        meta.description,
+        "",
+        "## Capabilities",
+        "",
+        ...meta.capabilities.map((c) => `- ${c}`),
+        "",
+        "## Usage",
+        "",
+        "```typescript",
+        `import { registry } from "@huddle-marketplace/skills";`,
+        "",
+        `const skill = registry.get("${meta.jurisdiction}");`,
+        `const result = await skill.validate({`,
+        `  type: "deposit-validation",`,
+        `  depositAmountCents: 150000,`,
+        `  monthlyRentCents: 200000,`,
+        `  currency: "USD",`,
+        `});`,
+        "",
+        `console.log(result.compliant); // true/false`,
+        `console.log(skill.explain(result)); // human-readable explanation`,
+        "```",
+        "",
+        "## Permissions",
+        "",
+        "This skill requires **no network access** and **no filesystem access**.",
+        "It is a pure computation skill that evaluates inputs against legal rules.",
+        "",
+    ].join("\n");
+    return yaml + body;
+}
+//# sourceMappingURL=openclaw.js.map

package/dist/adapters/openclaw.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openclaw.js","sourceRoot":"","sources":["../../src/adapters/openclaw.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwBH;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAkB;IAChD,MAAM,IAAI,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAEjC,OAAO;QACL,QAAQ,EAAE;YACR,IAAI,EAAE,IAAI,CAAC,EAAE;YACb,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,MAAM,EAAE,EAAE,MAAM,EAAE,sBAAsB,EAAE;YAC1C,OAAO,EAAE,EAAE,MAAM,EAAE,uBAAuB,EAAE;YAC5C,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB;QAED,KAAK,CAAC,OAAO,CAAC,KAA8B;YAC1C,OAAO,KAAK,CAAC,QAAQ,CAAC,KAA8B,CAAC,CAAC;QACxD,CAAC;QAED,QAAQ;YACN,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;QAC7B,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAqB;IACpD,OAAO,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAkB;IAChD,MAAM,IAAI,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG;QACX,KAAK;QACL,SAAS,IAAI,CAAC,EAAE,EAAE;QAClB,YAAY,IAAI,CAAC,OAAO,EAAE;QAC1B,gBAAgB,IAAI,CAAC,WAAW,EAAE;QAClC,WAAW,IAAI,CAAC,MAAM,EAAE;QACxB,iBAAiB,IAAI,CAAC,YAAY,EAAE;QACpC,kBAAkB,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QACjD,iBAAiB,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QAC/C,UAAU,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QACjC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,IAAI;QAC1D,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,mBAAmB,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,IAAI;QACnE,KAAK;KACN,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE7B,MAAM,IAAI,GAAG;QACX,EAAE;QACF,KAAK,IAAI,CAAC,IAAI,EAAE;QAChB,EAAE;QACF,oBAAoB,IAAI,CAAC,YAAY,EAAE;QACvC,EAAE;QACF,IAAI,CAAC,WAAW;QAChB,EAAE;QACF,iBAAiB;QACjB,EAAE;QACF,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;QACzC,EAAE;QACF,UAAU;QACV,EAAE;QACF,eAAe;QACf,wDAAwD;QACxD,EAAE;QACF,+BAA+B,IAAI,CAAC,YAAY,KAAK;QACrD,uCAAuC;QACvC,+BAA+B;QAC/B,+BAA+B;QAC/B,6BAA6B;QAC7B,oBAAoB;QACpB,KAAK;QACL,EAAE;QACF,8CAA8C;QAC9C,mEAAmE;QACnE,KAAK;QACL,EAAE;QACF,gBAAgB;QAChB,EAAE;QACF,yEAAyE;QACzE,2EAA2E;QAC3E,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,OAAO,IAAI,GAAG,IAAI,CAAC;AACrB,CAAC"}

package/dist/base.d.ts

@@ -0,0 +1,26 @@
+/**
+ * BaseSkill — Abstract base class for all Huddle compliance skills.
+ *
+ * Provides default implementations for explain() and remediate(),
+ * so jurisdiction skills only need to implement validate().
+ */
+import type { HuddleSkill, SkillInput, SkillResult, SkillMetadata, SkillCapability, JurisdictionCode, RemediationStep, SkillCheck } from "./types/index.js";
+export declare abstract class BaseSkill implements HuddleSkill {
+    abstract readonly id: string;
+    abstract readonly name: string;
+    abstract readonly jurisdiction: JurisdictionCode;
+    abstract readonly version: string;
+    abstract readonly capabilities: SkillCapability[];
+    /** Subclasses implement this to run jurisdiction-specific rules */
+    abstract validate(input: SkillInput): Promise<SkillResult>;
+    /** Default explainability: build a human-readable summary from checks */
+    explain(result: SkillResult): string;
+    /** Default remediation: generate steps for each failed check */
+    remediate(result: SkillResult): RemediationStep[];
+    /** Convert a failed check into a remediation step. Override for custom logic. */
+    protected checkToRemediation(check: SkillCheck): RemediationStep;
+    /** Build a SkillResult from individual checks */
+    protected buildResult(checks: SkillCheck[], input: SkillInput): SkillResult;
+    getMetadata(): SkillMetadata;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,UAAU,EACX,MAAM,kBAAkB,CAAC;AAE1B,8BAAsB,SAAU,YAAW,WAAW;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;IACjD,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,QAAQ,CAAC,YAAY,EAAE,eAAe,EAAE,CAAC;IAElD,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAE1D,yEAAyE;IACzE,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM;IA4BpC,gEAAgE;IAChE,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,EAAE;IAMjD,iFAAiF;IACjF,SAAS,CAAC,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,eAAe;IAShE,iDAAiD;IACjD,SAAS,CAAC,WAAW,CACnB,MAAM,EAAE,UAAU,EAAE,EACpB,KAAK,EAAE,UAAU,GAChB,WAAW;IAmCd,WAAW,IAAI,aAAa;CAiB7B"}

package/dist/base.js

@@ -0,0 +1,97 @@
+/**
+ * BaseSkill — Abstract base class for all Huddle compliance skills.
+ *
+ * Provides default implementations for explain() and remediate(),
+ * so jurisdiction skills only need to implement validate().
+ */
+export class BaseSkill {
+    /** Default explainability: build a human-readable summary from checks */
+    explain(result) {
+        const status = result.compliant ? "PASSES" : "FAILS";
+        const failedChecks = result.checks.filter((c) => !c.passed);
+        const passedChecks = result.checks.filter((c) => c.passed);
+        let explanation = `This transaction ${status} ${this.name} compliance (confidence: ${(result.confidence * 100).toFixed(0)}%).\n\n`;
+        if (failedChecks.length > 0) {
+            explanation += "Failed checks:\n";
+            for (const check of failedChecks) {
+                explanation += `  - ${check.name}: ${check.note}`;
+                if (check.citation) {
+                    explanation += ` (${check.citation.statute} ${check.citation.section})`;
+                }
+                explanation += "\n";
+            }
+        }
+        if (passedChecks.length > 0) {
+            explanation += "\nPassed checks:\n";
+            for (const check of passedChecks) {
+                explanation += `  - ${check.name}: ${check.note}\n`;
+            }
+        }
+        return explanation;
+    }
+    /** Default remediation: generate steps for each failed check */
+    remediate(result) {
+        return result.checks
+            .filter((c) => !c.passed)
+            .map((check) => this.checkToRemediation(check));
+    }
+    /** Convert a failed check into a remediation step. Override for custom logic. */
+    checkToRemediation(check) {
+        return {
+            action: `fix_${check.name.toLowerCase().replace(/\s+/g, "_")}`,
+            description: `Address failed check: ${check.note}`,
+            urgency: "required",
+            automatable: false,
+        };
+    }
+    /** Build a SkillResult from individual checks */
+    buildResult(checks, input) {
+        const compliant = checks.every((c) => c.passed);
+        const confidence = checks.length > 0
+            ? Math.min(...checks.map((c) => c.confidence))
+            : 0;
+        const citations = checks
+            .filter((c) => c.citation)
+            .map((c) => c.citation);
+        const remediation = compliant ? undefined : this.remediate({
+            compliant,
+            confidence,
+            jurisdiction: this.jurisdiction,
+            skillId: this.id,
+            skillVersion: this.version,
+            checks,
+            timestamp: Date.now(),
+            citations,
+        });
+        return {
+            compliant,
+            confidence,
+            jurisdiction: this.jurisdiction,
+            skillId: this.id,
+            skillVersion: this.version,
+            checks,
+            explanation: undefined, // Filled by caller if needed
+            remediation,
+            citations: citations.length > 0 ? citations : undefined,
+            timestamp: Date.now(),
+        };
+    }
+    getMetadata() {
+        return {
+            id: this.id,
+            name: this.name,
+            description: `${this.name} compliance skill for ${this.jurisdiction}`,
+            jurisdiction: this.jurisdiction,
+            version: this.version,
+            capabilities: this.capabilities,
+            permissions: ["network:none", "filesystem:none"],
+            tags: [
+                "rental",
+                "compliance",
+                this.jurisdiction.toLowerCase(),
+            ],
+            author: "huddle-protocol",
+        };
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/base.js.map

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

package/dist/compose.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @huddle-marketplace/skills — Composition Engine
+ *
+ * Stack multiple jurisdiction skills for layered validation.
+ *
+ * Typical patterns:
+ *   Federal + State:   composeSkills(["US-CFTC", "US-TX"], input, registry)
+ *   Multi-state:       composeSkills(["US-CA", "US-NY"], input, registry)
+ *   Cross-border:      composeSkills(["US-CFTC", "CA-FINTRAC", "CA-ON"], input, registry)
+ *
+ * Architecture:
+ *   - Layers run in PARALLEL (Promise.all) — O(1) latency regardless of layer count
+ *   - Federal checks first in output by convention (pass them first in the array)
+ *   - Each check is prefixed with its source jurisdiction for full traceability
+ *   - Citations are deduplicated by statute+section across layers
+ *   - compliant = ALL layers compliant (strict mode, default)
+ *
+ * Web3-native: When US-CFTC is composed with a state skill, the federal layer validates
+ * bond structure (wBTC reserve ratio, non-custodial architecture, TRAIGA logging).
+ * The state layer adds local statutory rules (deposit cap, return timeline, late fee limits).
+ * Together they form a complete, TRAIGA-ready compliance proof for any Huddle transaction.
+ */
+import type { SkillInput, SkillResult, SkillCheck, LegalCitation, RemediationStep, JurisdictionCode } from "./types/index.js";
+/**
+ * The merged result of running multiple jurisdiction skills in sequence.
+ * Each layer's result is preserved in `layers[]` for full TRAIGA auditability.
+ */
+export interface ComposedResult {
+    /** true only when ALL jurisdiction layers are compliant (strict mode) */
+    compliant: boolean;
+    /** Minimum confidence across all layers — the weakest link determines overall confidence */
+    confidence: number;
+    /** Jurisdiction codes validated, in the order provided */
+    jurisdictions: string[];
+    /** Individual SkillResult per jurisdiction — full detail for TRAIGA logging */
+    layers: SkillResult[];
+    /** All checks from all layers, prefixed with source jurisdiction for traceability */
+    checks: SkillCheck[];
+    /** All citations merged and deduplicated by statute+section */
+    citations: LegalCitation[];
+    /** All remediation steps from all layers, consolidated */
+    remediation: RemediationStep[];
+    /** Unix timestamp (ms) when composition completed */
+    timestamp: number;
+}
+/**
+ * Minimal registry interface — avoids circular import from index.ts.
+ * The full SkillRegistry satisfies this interface automatically.
+ */
+export interface MinimalRegistry {
+    get(jurisdiction: JurisdictionCode): {
+        validate(input: SkillInput): Promise<SkillResult>;
+    } | undefined;
+}
+export interface ComposeOptions {
+    /**
+     * "strict" (default): ALL layers must be compliant for `compliant: true`.
+     * Use for production validation where every layer must pass.
+     *
+     * "advisory": only layers listed in `criticalJurisdictions` affect `compliant`.
+     * Use when some layers are informational overlays.
+     */
+    mode?: "strict" | "advisory";
+    /**
+     * In "advisory" mode: only these jurisdictions determine `compliant`.
+     * Defaults to all jurisdictions when not provided (equivalent to strict mode).
+     */
+    criticalJurisdictions?: string[];
+}
+/**
+ * Compose multiple jurisdiction skills into a single layered validation result.
+ *
+ * Designed for Web3-native use: the federal CFTC layer validates the bond structure,
+ * the state layer validates local statutory rules — together they form a complete
+ * compliance proof anchored on-chain via TRAIGA.
+ *
+ * NOTE: This is the low-level function that requires an explicit registry.
+ * Use the `composeSkills()` export from the main package entry which uses the
+ * default registry automatically.
+ *
+ * @param jurisdictions - Ordered list of jurisdiction codes (federal first by convention)
+ * @param input         - Skill input shared across all layers (amounts in CENTS)
+ * @param registry      - Registry instance to resolve skills from
+ * @param options       - Composition options
+ */
+export declare function composeSkillsWithRegistry(jurisdictions: (JurisdictionCode | string)[], input: SkillInput, registry: MinimalRegistry, options?: ComposeOptions): Promise<ComposedResult>;
+//# sourceMappingURL=compose.d.ts.map

package/dist/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,UAAU,EACV,aAAa,EACb,eAAe,EACf,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAM1B;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,SAAS,EAAE,OAAO,CAAC;IAEnB,4FAA4F;IAC5F,UAAU,EAAE,MAAM,CAAC;IAEnB,0DAA0D;IAC1D,aAAa,EAAE,MAAM,EAAE,CAAC;IAExB,+EAA+E;IAC/E,MAAM,EAAE,WAAW,EAAE,CAAC;IAEtB,qFAAqF;IACrF,MAAM,EAAE,UAAU,EAAE,CAAC;IAErB,+DAA+D;IAC/D,SAAS,EAAE,aAAa,EAAE,CAAC;IAE3B,0DAA0D;IAC1D,WAAW,EAAE,eAAe,EAAE,CAAC;IAE/B,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,YAAY,EAAE,gBAAgB,GAAG;QAAE,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;KAAE,GAAG,SAAS,CAAC;CACxG;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAE7B;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;CAClC;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,yBAAyB,CAC7C,aAAa,EAAE,CAAC,gBAAgB,GAAG,MAAM,CAAC,EAAE,EAC5C,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,eAAe,EACzB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAsFzB"}