npm package: @huddle-marketplace/skills
Description: 63-jurisdiction rental compliance skills for autonomous AI agents. OpenClaw, MCP, LangChain, and CrewAI compatible.
Latest version: 0.2.0

# @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)