---
name: snappy-channel-contract
role: Uniform hands-and-eyes shape every channel skill implements
loaded-by: preload-skill-context hook
---

# snappy-channel-contract — The Hands-and-Eyes Layer

Every channel skill (snappy-slack, snappy-email, snappy-linkedin, snappy-whatsapp, snappy-imessage, snappy-telegram, snappy-skool) exports an `adapter.ts` conforming to this contract. Chains consume **only** the contract types — never the native api.ts shapes. That's what makes a chain channel-agnostic.

## The three verbs

```typescript
import type { ChannelAdapter, Event, PostTarget, PostContent } from "../snappy-channel-contract/types.ts";

const adapter: ChannelAdapter = {
  source: "slack",
  read(since?, limit?)    -> Promise<Event[]>
  post(target, content)   -> Promise<PostResult>
  identify(authorId)      -> Promise<Contact | null>
  selfCheck()             -> Promise<SelfCheckResult>
};
```

## Event shape (canonical)

```typescript
{
  source: "slack" | "gmail" | "linkedin" | ...,
  event_id: string,           // unique within source
  thread_id: string | null,   // null if channel has no threads
  channel_id: string,
  channel_name: string,
  author: { id, handle, display },
  text: string,
  ts: string,                 // ISO 8601 UTC
  permalink: string | null,
  meta: Record<string, unknown>,
}
```

All downstream classifiers and chains trust this shape. Adapters that can't fill a field return `""` or `null` — never throw mid-map.

## Verification

```bash
# verify all adapters (auto-discovers snappy-*/adapter.ts)
npx tsx ~/.claude/skills/snappy-channel-contract/verify.ts

# verify one
npx tsx ~/.claude/skills/snappy-slack/adapter.ts
```

Every run appends certs to `~/.claude/logs/channel-certs.ndjson`. Exit 0 = all green, exit 1 = at least one fail.

`selfCheck()` calls `read(limit=3)`, checks shape, and tries `identify()` on the first event's author. It does **not** call `post()` (destructive).

## How to use in a chain

```typescript
import slack from "../snappy-slack/adapter.ts";
import gmail from "../snappy-email/adapter.ts";

const adapters = [slack, gmail /* ... */];
for (const a of adapters) {
  const events = await a.read();
  for (const e of events) {
    const intent = classify(e);
    if (intent === "bug-report") await bugChain(e, a);
  }
}
```

`bugChain(e, a)` calls `a.post({ source: e.source, channel_id: e.channel_id, thread_id: e.thread_id, to_user: null }, { text, files })` — works identically on any channel.

## How to add a new channel

1. Add the source literal to `ChannelSource` in `types.ts`.
2. In the channel's skill directory, create `adapter.ts` exporting `adapter: ChannelAdapter`.
3. Wrap existing `api.ts` functions (plus any sweep fetchers) to fill the Event shape.
4. Run `npx tsx <your-adapter>.ts` — selfCheck must pass.
5. Run the full verify — your adapter shows up automatically via discovery.

## Adapter inventory (2026-04-13)

| source    | status | notes |
|-----------|--------|-------|
| slack     | PASS   | wraps `fetchSlackUnread` + `sendSlackMessage`/`replyInThread`/`getUserInfo` |
| gmail     | PASS   | wraps `fetchGmailUnread` (work+personal) + `createEmailDraft` (draft-only by design) |
| linkedin  | PASS*  | wraps `fetchLinkedInDMs` + `sendLinkedInDM` from inbox-sweep. Browser auth expires periodically; read returns [] on expiry instead of throwing. `identify` is null until snappy-linkedin gains a profile-by-urn primitive. |
| skool     | PASS*  | wraps `fetchSkoolNotifications` + `sendSkoolReply`. Scraper occasionally hits 404 — returns [] gracefully. |
| telegram  | PASS   | native `getRecentTelegramMessages` + `sendText`. `identify` only returns bot self; per-user identify needs a future primitive. |
| whatsapp  | PASS   | reads from local webhook log, synthesizes thread_id from sender phone. |
| imessage  | FAIL   | SSH to Mac mini rejecting auth — pre-existing infra issue, not contract code. Adapter logic is correct. |

*Auth-degraded but contract-compliant (graceful empty returns).

## Rules

1. **Never break the shape.** If a channel can't fill a field, use `""` or `null`, not `undefined`.
2. **`read()` must not throw.** Degrade to `[]` on auth expiry, rate limit, network error. Errors go in the next `selfCheck()` via reproduced exception during sweep.
3. **`post()` must never auto-publish without intent.** Gmail stays draft-only; other channels send directly (Robert's prior authorization for ephemeral comms).
4. **`selfCheck()` is read-only.** Never call `post()` from it.
5. **No new channel skill without a contract-compliant adapter.** The cert log is the gate.

<!-- SKILL-INDEX-START -->
[snappy-channel-contract Index]|root: ~/.claude/skills/snappy-channel-contract|IMPORTANT: Prefer these files over pre-training assumptions for this domain. Read the relevant file when the AGENTS.md summary is insufficient.|root:{SKILL.md,SPEC.md}
<!-- SKILL-INDEX-END -->

## Used by

Nothing in the collection names this skill.

<!-- SNAPPY-CONTRACT-VERBS-START -->
## Contract verbs

Generated from `api.ts` `HAND_CONTRACT`. Do not hand-edit this block.

| Verb | Contract arguments | Effect | First call |
|---|---|---|---|
| `certs` | — | `read` | `npx tsx ~/.claude/skills/snappy-channel-contract/api.ts certs` |
| `list` | — | `read` | `npx tsx ~/.claude/skills/snappy-channel-contract/api.ts list` |
| `schema` | — | `read` | `npx tsx ~/.claude/skills/snappy-channel-contract/api.ts schema` |
| `validate` | — | `read` | `npx tsx ~/.claude/skills/snappy-channel-contract/api.ts validate` |

## Show the result

When an answer carries `face_hint`, show it with one `snappy_present(<answer>)` call.
See `/snappy-faces` for face selection. Human-facing images must crop to the
element, render at 2x on Retina, and fill the destination channel instead of
placing a small card in a full-page screenshot.
<!-- SNAPPY-CONTRACT-VERBS-END -->

---
name: snappy-channel-contract
purpose: Uniform hands-and-eyes shape every channel skill implements so chains are channel-agnostic
triggers on: mentions of channel contract, channel adapter, ChannelAdapter, PostTarget, or channel self-check.
status: LIVE — 2026-04-13
description: "Uniform hands-and-eyes shape every channel skill implements so chains are channel-agnostic. Triggers on mentions of channel contract, channel adapter, ChannelAdapter, PostTarget, or channel self-check."
---

# snappy-channel-contract

The hands-and-eyes layer. One shape, three verbs, seven channels. Chains consume only this contract — never native `api.ts` shapes. That is what makes a chain channel-agnostic.

## Files

| file | role |
|---|---|
| `types.ts` | Contract types (`Event`, `ChannelAdapter`, `PostTarget`, `PostContent`, `PostResult`, `Contact`, `SelfCheckResult`) + `isValidEvent()` type guard |
| `verify.ts` | Kernel verifier. Auto-discovers `snappy-*/adapter.ts`, runs `selfCheck()`, writes certs to `~/.claude/logs/channel-certs.ndjson`, prints table, exits 0/1 |
| `AGENTS.md` | Injected loader for agents working in the domain |
| `SPEC.md` | Historical design doc (2026-04-13 audit) — kept for provenance |

## The three verbs

```typescript
interface ChannelAdapter {
  source: ChannelSource;
  read(since?: string, limit?: number): Promise<Event[]>;
  post(target: PostTarget, content: PostContent): Promise<PostResult>;
  identify(authorId: string): Promise<Contact | null>;
  selfCheck(): Promise<SelfCheckResult>;
}
```

See `types.ts` for full shapes. `Event` is canonical — every downstream classifier and chain trusts it.

## Verification

```bash
# verify all adapters
npx tsx ~/.claude/skills/snappy-channel-contract/verify.ts

# verify one
npx tsx ~/.claude/skills/snappy-slack/adapter.ts
```

`selfCheck()` calls `read(limit=3)`, validates shape via `isValidEvent`, tries `identify()` on the first event's `author.id`. **It never calls `post()`** — reads only.

Every run appends a cert line to `~/.claude/logs/channel-certs.ndjson`. Exit 0 = all green, exit 1 = at least one FAIL. This log is the gate: no chain may depend on an adapter that isn't currently green in the cert log.

## Adapter inventory (2026-04-13)

| source | status | wraps |
|---|---|---|
| slack | PASS | `fetchSlackUnread` + `sendSlackMessage`/`replyInThread`/`getUserInfo` |
| gmail | PASS | `fetchGmailUnread` (work+personal) + `createEmailDraft` (draft-only) |
| linkedin | PASS* | `fetchLinkedInDMs` + `sendLinkedInDM` from inbox-sweep |
| skool | PASS* | `fetchSkoolNotifications` + `sendSkoolReply` |
| telegram | PASS | native `getRecentTelegramMessages` + `sendText` |
| whatsapp | PASS | local webhook log + `sendMessage`; thread_id synthesized from sender phone |
| imessage | FAIL | SSH to Mac mini rejecting auth — pre-existing infra issue, adapter logic correct |

\*Auth-degraded but contract-compliant (graceful empty return on auth expiry).

## Five rules

1. **Never break the shape.** Missing field → `""` or `null`, never `undefined`, never throw mid-map.
2. **`read()` must not throw.** Auth expiry, rate limit, network error → degrade to `[]`. The next `selfCheck()` captures the error.
3. **`post()` must never auto-publish without intent.** Gmail stays draft-only. Other channels send directly (prior standing authorization for ephemeral comms; Robert still reviews outputs).
4. **`selfCheck()` is read-only.** Never call `post()` from it.
5. **No new channel skill without a contract-compliant adapter.** The cert log is the gate.

## Adding a new channel

1. Add the source literal to `ChannelSource` in `types.ts`.
2. Create `snappy-<name>/adapter.ts` exporting `adapter: ChannelAdapter`.
3. Wrap existing `api.ts` functions (plus any sweep fetchers) into the `Event` shape.
4. Smoke test: `npx tsx snappy-<name>/adapter.ts` — `selfCheck()` must pass.
5. Run the full verifier — discovery picks up the new adapter automatically.

## How chains consume it

```typescript
import slack from "../snappy-slack/adapter.ts";
import gmail from "../snappy-email/adapter.ts";

for (const a of [slack, gmail /* ... */]) {
  for (const e of await a.read()) {
    const intent = classify(e);
    if (intent === "bug-report") await bugChain(e, a);
  }
}
```

`bugChain(e, a)` only touches `a.post(...)` — same call shape on every channel. Writing a new chain once unlocks all 7 channels.

## Why this exists

Before this contract, every chain re-learned a new channel shape. Slack reads differently than Gmail, which identifies users differently than LinkedIn, which threads differently than WhatsApp. Each new chain unlocked ONE channel. That is the "we barely move" feeling. Uniform shape collapses N×M work into N+M.

---
name: snappy-channel-contract
status: DRAFT — 2026-04-13
purpose: One uniform shape every channel skill implements so chains are channel-agnostic.
---

# snappy-channel-contract — The Hands-and-Eyes Contract

## Why this exists

Every chain you try to build ("Mark reports bug in Slack → PR") re-learns a new channel shape. Slack reads differently than Gmail, which reads differently than LinkedIn, which identifies users differently than WhatsApp. Each new chain unlocks ONE channel instead of N. That's why it feels like you barely move.

This spec defines ONE shape. Every channel skill implements it. Chains consume it. New channel = wrap. New chain = compose.

## The contract

```typescript
// All timestamps are ISO 8601 strings in UTC.
// All IDs are opaque strings scoped by source.

export type ChannelSource =
  | "slack" | "gmail" | "linkedin" | "whatsapp"
  | "imessage" | "telegram" | "skool";

export interface Event {
  source:       ChannelSource;
  event_id:     string;            // stable unique id within source
  thread_id:    string | null;     // null = not threaded (whatsapp, imessage)
  channel_id:   string;            // e.g. slack channel, gmail account, skool group
  channel_name: string;
  author: {
    id:      string;               // opaque source-scoped id
    handle:  string;               // @name, email, phone, urn
    display: string;               // human name if known
  };
  text:         string;            // flattened plain text
  ts:           string;            // ISO 8601
  permalink:    string | null;     // deep link if available
  meta:         Record<string, unknown>;  // source-specific extras
}

export interface PostTarget {
  source:    ChannelSource;
  channel_id: string;              // required
  thread_id: string | null;        // reply target (null = new top-level)
  to_user:   string | null;        // DM target if source supports it
}

export interface PostContent {
  text:   string;
  files?: Array<{ path: string; filename: string; alt?: string }>;
}

export interface PostResult {
  ok:          boolean;
  posted_id:   string | null;
  permalink:   string | null;
  error?:      string;
}

export interface Contact {
  id:         string;
  handle:     string;
  display:    string;
  profile_url: string | null;
  meta:       Record<string, unknown>;
}

// The three verbs every channel must implement
export interface ChannelAdapter {
  source: ChannelSource;
  read(since?: string, limit?: number): Promise<Event[]>;
  post(target: PostTarget, content: PostContent): Promise<PostResult>;
  identify(authorId: string): Promise<Contact | null>;
}
```

That's it. Three verbs, one event type, one target type. A chain is then:

```typescript
for (const e of await adapter.read(since)) {
  const intent = await classify(e);
  if (intent === "bug-report") await bugChain(e, adapter);
}
```

…and `bugChain` uses the same `adapter.post({thread_id: e.thread_id, ...}, {text, files})` on ANY channel.

## Current state audit (2026-04-13)

What each channel skill has vs what the contract needs:

| skill | read | post-to-thread | identify | gap severity |
|---|---|---|---|---|
| **snappy-slack** | `readMessages`, `recentMessages`, `searchSlackMessages` | `sendSlackMessage(ch, text, threadTs)`, `replyInThread` | `getUserInfo(userId)` | **LOW** — adapter ~50 lines |
| **snappy-email** (Gmail) | `searchGmailMessages`, `getMessage`, `getThread` | `createEmailDraft`, `sendTransactional` | *missing contact resolver* | MEDIUM — needs identify() + thread reply, not draft |
| **snappy-telegram** | `getRecentTelegramMessages`, `getUpdates` | `sendText`, `editTelegramMessage` | `getMe()` only (self) | MEDIUM — no per-user identify |
| **snappy-skool** (Skool) | `listPosts`, `getPostDetail`, `listComments`, `listMembers`, `listChats`, `listSkoolMessages` | `stagePost`, `stageComment`, `stageDm` | `listMembers(group,page)` | MEDIUM — posts/comments model differs from chat threads |
| **snappy-whatsapp** | `getRecentWhatsAppMessages` | `sendMessage(to, text)` | *none* | MEDIUM — no threading, no contact resolver |
| **snappy-imessage** | `readRecent(contact)` | `sendIMessage(to, text)` | implicit | MEDIUM — no structured ids |
| **snappy-linkedin** | **NOTHING** — no DM or comment read primitive | `commentOnLinkedInPost(postUrn)` only | `getProfile()` (self) | **CRITICAL** — LinkedIn is post-only today. inbox-sweep must be pulling LinkedIn DMs from somewhere else. |

**Biggest blocker:** LinkedIn. The sweep IS producing LinkedIn DM events (per Robert's memory / sweep logs), so *something* reads them — but it's not in `snappy-linkedin/api.ts`. That read path needs to move into the skill before LinkedIn can participate in any chain.

## Adapter layout (proposed)

Each channel skill gains one new file:

```
snappy-slack/
  api.ts          # existing native functions — untouched
  adapter.ts      # NEW: implements ChannelAdapter, wraps api.ts
```

`adapter.ts` exports a default `ChannelAdapter` instance that calls existing functions and reshapes results. No existing callers break. Chains import from `adapter.ts`; everything else keeps using `api.ts`.

```typescript
// snappy-slack/adapter.ts
import * as slack from "./api.ts";
import type { ChannelAdapter, Event, PostTarget, PostContent, PostResult } from "../snappy-channel-contract/types.ts";

export const adapter: ChannelAdapter = {
  source: "slack",
  async read(since, limit = 50) {
    const msgs = await slack.recentMessages(limit);
    return msgs.map(toEvent);
  },
  async post(target, content) {
    if (target.thread_id) {
      const r = await slack.replyInThread(target.channel_id, target.thread_id, content.text);
      return { ok: true, posted_id: r.ts, permalink: null };
    }
    const r = await slack.sendSlackMessage(target.channel_id, content.text);
    return { ok: true, posted_id: r.ts, permalink: null };
  },
  async identify(authorId) {
    const u = await slack.getUserInfo(authorId);
    return u ? { id: u.id, handle: u.name, display: u.real_name, profile_url: null, meta: u } : null;
  },
};
```

~50 lines per channel. 7 channels. Half a day of mechanical wrapping for Slack/Gmail/Telegram/Skool. Telegram/WhatsApp/iMessage need identify() gaps filled. LinkedIn needs the whole read path built first.

## Gap work, prioritized

1. **Define `types.ts`** in snappy-channel-contract (15 min).
2. **Slack adapter** — easiest, most-used (1 hr).
3. **Gmail adapter** — needs real thread reply (not draft) (2 hrs).
4. **Skool adapter** — map posts+comments to thread model (1 hr).
5. **Telegram adapter** + per-user identify (1 hr).
6. **WhatsApp adapter** — threading workaround: synthesize thread_id from sender phone (30 min).
7. **iMessage adapter** — same synthesis trick (30 min).
8. **LinkedIn DM read primitive** — find where sweep currently gets these, move into `snappy-linkedin/api.ts`, then wrap (unknown — 2–6 hrs).

**Total:** ~1 day of plumbing to get 7 channels on the same contract. After that, the Mark-bug chain is 2 hours and it works on all 7 channels.

## Chain shape (for reference — built AFTER contract lands)

```typescript
// snappy-chain/bug-report.ts
import type { Event, ChannelAdapter } from "../snappy-channel-contract/types.ts";

export async function bugReportChain(e: Event, adapter: ChannelAdapter, repoHint?: string) {
  const repo = repoHint || await inferRepo(e);
  const issue = await triage(e, repo);            // snappy-github
  const fix   = await reproAndFix(issue, repo);   // snappy-dispatch → pi agent
  const screenshots = await captureUI(fix);       // snappy-browse
  const pr = await openPR(repo, fix, screenshots); // snappy-github
  await adapter.post(
    { source: e.source, channel_id: e.channel_id, thread_id: e.thread_id, to_user: null },
    { text: `Fix up: ${pr.url}`, files: screenshots }
  );
}
```

Channel-agnostic. Works the same whether `e` came from Slack, Gmail, LinkedIn, or Skool.

## Open questions

1. **Sweep output shape vs Event type** — inbox-sweep already emits a JSON list. Do we migrate sweep to emit `Event[]` directly, or keep a separate normalizer? (Proposal: migrate. One shape everywhere.)
2. **Identity linking across channels** — Contact.id is source-scoped. To "find Mark across channels" we need a cross-source link table. Out of scope for v1. Chains can take `repoHint` etc. explicitly until then.
3. **Rate limiting + auth refresh** — per-channel concern, stays inside each adapter. Contract doesn't dictate.
4. **Historical backfill vs live** — `read(since)` is polling. Webhooks for Slack/Telegram/Gmail push could come later. Polling is fine for the cron-driven flow we already have.

## Validation

- 2026-04-13: SPEC.md drafted from live audit of 7 channel skills. No code yet. Awaiting Robert's sign-off before scaffolding types.ts and the first adapter.

#!/usr/bin/env npx tsx
// snappy-channel-contract/api.ts
// Programmatic interface for the channel contract.
//
// The contract types live in types.ts and the adapter discovery + verifier
// lives in verify.ts. This file is the rung-1 surface: re-exports + a tiny CLI
// so the ladder detects api.ts and other skills can `import { ... } from
// "../snappy-channel-contract/api.ts"`.
//
// Usage:
//   npx tsx api.ts list             # list every discovered snappy-*/adapter.ts
//   npx tsx api.ts certs [N]        # tail last N channel-cert lines
//   npx tsx api.ts schema           # print the Event/Adapter type names + fields
//   npx tsx api.ts validate < event.json   # type-guard a single Event payload

import { existsSync, readFileSync, readdirSync } from "node:fs";
import { resolve } from "node:path";
import {
  isValidEvent,
  type ChannelAdapter,
  type ChannelSource,
  type Contact,
  type Event,
  type PostContent,
  type PostResult,
  type PostTarget,
  type SelfCheckResult,
} from "./types.ts";
import { discoverAdapters, runSelfCheck } from "./verify.ts";
import { realpathSync } from "fs";
import { printRefusal, refuse, refusalTable } from "../snappy-settings/refusal-codes.ts";
import { boundRows, limitSchema, takeLimit } from "../snappy-settings/read-limit.ts";

export {
  isValidEvent,
  discoverAdapters,
  runSelfCheck,
  type ChannelAdapter,
  type ChannelSource,
  type Contact,
  type Event,
  type PostContent,
  type PostResult,
  type PostTarget,
  type SelfCheckResult,
};

const SKILLS_ROOT = `${process.env.HOME}/.claude/skills`;
const CERT_LOG = `${process.env.HOME}/.claude/logs/channel-certs.ndjson`;

export type AdapterEntry = {
  skill: string;
  source: ChannelSource | string;
  path: string;
};

/** Synchronous adapter discovery for callers that don't want to await. */
export function listAdapters(): AdapterEntry[] {
  if (!existsSync(SKILLS_ROOT)) return [];
  const out: AdapterEntry[] = [];
  for (const e of readdirSync(SKILLS_ROOT, { withFileTypes: true })) {
    if (!e.isDirectory() || !e.name.startsWith("snappy-")) continue;
    const p = resolve(SKILLS_ROOT, e.name, "adapter.ts");
    if (!existsSync(p)) continue;
    out.push({ skill: e.name, source: e.name.replace(/^snappy-/, ""), path: p });
  }
  return out;
}

/** Read the last N channel-cert lines (most recent last). */
export function readChannelCerts(limit = 20): SelfCheckResult[] {
  if (!existsSync(CERT_LOG)) return [];
  const lines = readFileSync(CERT_LOG, "utf-8").trim().split("\n");
  const tail = lines.slice(-limit);
  const out: SelfCheckResult[] = [];
  for (const line of tail) {
    try {
      out.push(JSON.parse(line) as SelfCheckResult);
    } catch {
      /* skip malformed */
    }
  }
  return out;
}

/** The contract shape, surfaced as plain data so callers can introspect without TS. */
export function describeContract(): Record<string, string[]> {
  return {
    Event: [
      "source",
      "event_id",
      "thread_id",
      "channel_id",
      "channel_name",
      "author.id",
      "author.handle",
      "author.display",
      "text",
      "ts",
      "permalink",
      "meta",
    ],
    PostTarget: ["source", "channel_id", "thread_id", "to_user"],
    PostContent: ["text", "files[]"],
    PostResult: ["ok", "posted_id", "permalink", "error?"],
    Contact: ["id", "handle", "display", "profile_url", "meta"],
    SelfCheckResult: [
      "source",
      "ok",
      "read_ok",
      "read_count",
      "shape_valid",
      "identify_ok",
      "errors[]",
      "duration_ms",
      "ts",
    ],
    ChannelAdapter: [
      "source",
      "read(since?, limit?) -> Event[]",
      "post(target, content) -> PostResult",
      "identify(authorId) -> Contact|null",
      "selfCheck() -> SelfCheckResult",
    ],
  };
}

async function readStdin(): Promise<string> {
  if (process.stdin.isTTY) return "";
  const chunks: Buffer[] = [];
  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
  return Buffer.concat(chunks).toString("utf8");
}
/** WHAT THIS HAND ANSWERS, and what each verb does to the world.
 *  Derived from this file's own CLI dispatch by
 *  `snappy-hands/contract-derive.ts` — a verb the code does not implement is
 *  never declared here. Snappy's daemon reads it (`api.ts contract`) to
 *  validate every call, build the argument words in order, decide whether the
 *  act runs now or stages for the owner, and hand the child exactly the
 *  environment keys named in `requires` — never a value, never anything else.
 */
export const HAND_CONTRACT = {
  skill: "snappy-channel-contract",
  description: "Uniform hands-and-eyes shape every channel skill implements so chains are channel-agnostic. Triggers on mentions of channel contract, channel adapter, ChannelAdapter, PostTarget, or channel self-check.",
  managed: false,
  requires: [] as string[],
  refusals: refusalTable("unknown_verb"),
  verbs: {
    certs: {
      args: [], effect: "read",
      class: "read", execution: "call", openWorld: false,
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false },
    },
    list: {
      args: [], flags: { limit: "--limit" }, effect: "read",
      class: "read", execution: "call", openWorld: false,
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false },
      inputSchema: { properties: {
        limit: limitSchema(200, "How many channels to return"),
      } },
    },
    schema: {
      args: [], effect: "read",
      class: "read", execution: "call", openWorld: false,
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false },
    },
    validate: {
      args: [], effect: "read",
      class: "read", execution: "call", openWorld: false,
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false },
    },
  },
} as const;

if (import.meta.url === `file://${realpathSync(process.argv[1])}` && process.argv[2] === "contract") {
  console.log(JSON.stringify(HAND_CONTRACT, null, 2));
  process.exit(0);
}


if (import.meta.url === `file://${realpathSync(process.argv[1])}`) {
  (async () => {
    const [, , cmd, ...args] = process.argv;
    const wantJson = args.includes("--json");

    switch (cmd) {
      case "list": {
        const bound = takeLimit(args, { maximum: 200 });
        if (bound.refusal) { console.log(JSON.stringify(bound.refusal, null, 2)); process.exit(1); }
        const adapters = boundRows(listAdapters(), bound.limit);
        if (wantJson) {
          console.log(JSON.stringify(adapters, null, 2));
        } else {
          console.log(`${adapters.length} of ${listAdapters().length} channel adapter(s):`);
          for (const a of adapters) console.log(`  ${a.source.padEnd(12)} ${a.skill}`);
        }
        break;
      }
      case "certs": {
        const n = Number(args.find((a) => /^\d+$/.test(a))) || 20;
        const certs = readChannelCerts(n);
        if (wantJson) {
          console.log(JSON.stringify(certs, null, 2));
        } else {
          console.log(`last ${certs.length} channel cert(s):`);
          for (const c of certs) {
            const flag = c.ok ? "PASS" : "FAIL";
            console.log(`  ${flag.padEnd(4)} ${c.source.padEnd(10)} read=${c.read_count} ${c.ts}`);
          }
        }
        break;
      }
      case "schema": {
        const c = describeContract();
        if (wantJson) console.log(JSON.stringify(c, null, 2));
        else {
          for (const [name, fields] of Object.entries(c)) {
            console.log(`${name}`);
            for (const f of fields) console.log(`  - ${f}`);
          }
        }
        break;
      }
      case "validate": {
        const raw = await readStdin();
        if (!raw.trim()) {
          printRefusal(refuse("missing_argument", "validate reads one Event as JSON on stdin: `npx tsx api.ts validate < event.json`"));
          console.error("Usage: npx tsx api.ts validate < event.json");
          process.exit(1);
        }
        const parsed = JSON.parse(raw);
        const ok = isValidEvent(parsed);
        if (wantJson) console.log(JSON.stringify({ ok }));
        else console.log(ok ? "valid Event" : "INVALID Event");
        process.exit(ok ? 0 : 1);
      }
      default:
        console.log("Usage: npx tsx api.ts [list|certs|schema|validate] [--json]");
        console.log("Discover adapters, tail certs, or inspect the contract shape.");
    }
  })();
}

import { test } from "node:test";
import assert from "node:assert/strict";
import { HAND_CONTRACT } from "./api.ts";
import { REFUSAL_CODES, type RefusalCode } from "../snappy-settings/refusal-codes.ts";

/** RULE 33 COVERAGE, AGAINST THE ONE CLOSED TABLE ⟨lane r30, 2026-09-09⟩.
 *  This file used to restate a refusal row's own properties — that it has a
 *  `contract_slice`, that it has a `fix`, that it leaks no token — once per
 *  hand, 48 times, over rows that all come from the SAME object. Forty-eight
 *  copies of one check is the duplicate road the closed table exists to end:
 *  `snappy-settings/refusal-codes.test.ts` runs those checks ONCE over every
 *  row, and the second test below proves this hand carries THE ROW ITSELF and
 *  not a copy — an identity a drifted duplicate cannot fake. Before this, each
 *  hand hand-wrote its own row, and the wording had already drifted: the
 *  inline `unknown_verb` said "Call one of the verbs named in
 *  HAND_CONTRACT.verbs" while the closed table says "Call one of the verbs the
 *  contract declares; the refusal lists them."
 *
 *  DECLARED stays a literal list, deliberately. It is this hand's coverage
 *  manifest and it is what rule 33's lint reads out of the test SOURCE to ask
 *  "did a person look at this code" — deriving it from Object.keys would make
 *  the test pass for a hand with no refusals at all. `satisfies readonly
 *  RefusalCode[]` makes the compiler refuse a name the one table does not
 *  have. It NAMES codes; it no longer DEFINES them. */
const DECLARED = [
  "unknown_verb",
] as const satisfies readonly RefusalCode[];

test("snappy-channel-contract: the refusal table declares exactly the codes this test names", () => {
  assert.deepEqual(Object.keys(HAND_CONTRACT.refusals ?? {}).sort(), [...DECLARED].sort());
});

test("snappy-channel-contract: every declared refusal is the one closed table's own row, never a copy", () => {
  const declared = Object.entries(HAND_CONTRACT.refusals ?? {});
  assert.ok(declared.length > 0, "HAND_CONTRACT.refusals is empty");
  for (const [code, row] of declared) {
    assert.ok(code in REFUSAL_CODES, `${code} is not a row of snappy-settings/refusal-codes.ts`);
    assert.equal(row, REFUSAL_CODES[code as RefusalCode], `${code} is a copy of the closed table's row, not the row itself`);
  }
});

{
  "providers": [
    {
      "name": "adapters",
      "label": "channel adapter",
      "description": "every snappy-*/adapter.ts that implements the contract",
      "fetch": "npx tsx ~/.claude/skills/snappy-channel-contract/api.ts list --json | jq -c '[.[] | {id:.skill,name:.source,description:.skill}]'",
      "fields": { "id": "id", "label": "name", "description": "description" },
      "verbs": [
        { "name": "self-check", "label": "run selfCheck", "description": "read=3, validate shape, identify first author", "fire": "npx tsx ~/.claude/skills/{id}/adapter.ts" },
        { "name": "tail-certs", "label": "tail latest certs", "description": "last 20 channel-cert entries", "fire": "npx tsx ~/.claude/skills/snappy-channel-contract/api.ts certs 20 | grep {name}" }
      ]
    },
    {
      "name": "certs",
      "label": "channel cert",
      "description": "recent selfCheck certificates from the cert log",
      "fetch": "npx tsx ~/.claude/skills/snappy-channel-contract/api.ts certs 20 --json | jq -c '[.[] | {id:.ts,name:.source,description:(if .ok then \"PASS\" else \"FAIL\" end + \" read=\" + (.read_count|tostring))}]'",
      "fields": { "id": "id", "label": "name", "description": "description" },
      "verbs": [
        { "name": "rerun", "label": "rerun selfCheck", "description": "execute the adapter selfCheck again", "fire": "npx tsx ~/.claude/skills/snappy-{name}/adapter.ts" }
      ]
    }
  ]
}

// snappy-channel-contract/types.ts
// The one shape every channel skill implements. Chains consume only these types.

export type ChannelSource =
  | "slack"
  | "gmail"
  | "linkedin"
  | "whatsapp"
  | "imessage"
  | "telegram"
  | "skool";

export interface Event {
  source: ChannelSource;
  event_id: string;
  thread_id: string | null;
  channel_id: string;
  channel_name: string;
  author: {
    id: string;
    handle: string;
    display: string;
  };
  text: string;
  ts: string;
  permalink: string | null;
  meta: Record<string, unknown>;
}

export interface PostTarget {
  source: ChannelSource;
  channel_id: string;
  thread_id: string | null;
  to_user: string | null;
}

export interface PostContent {
  text: string;
  files?: Array<{ path: string; filename: string; alt?: string }>;
}

export interface PostResult {
  ok: boolean;
  posted_id: string | null;
  permalink: string | null;
  error?: string;
}

export interface Contact {
  id: string;
  handle: string;
  display: string;
  profile_url: string | null;
  meta: Record<string, unknown>;
}

export interface SelfCheckResult {
  source: ChannelSource;
  ok: boolean;
  read_ok: boolean;
  read_count: number;
  shape_valid: boolean;
  identify_ok: boolean | null; // null = skipped (no event to identify from)
  errors: string[];
  duration_ms: number;
  ts: string;
}

export interface ChannelAdapter {
  source: ChannelSource;
  read(since?: string, limit?: number): Promise<Event[]>;
  post(target: PostTarget, content: PostContent): Promise<PostResult>;
  identify(authorId: string): Promise<Contact | null>;
  selfCheck(): Promise<SelfCheckResult>;
}

// Shape validator — used by selfCheck and by any chain that wants to trust incoming events.
export function isValidEvent(e: unknown): e is Event {
  if (!e || typeof e !== "object") return false;
  const o = e as Record<string, unknown>;
  if (typeof o.source !== "string") return false;
  if (typeof o.event_id !== "string") return false;
  if (o.thread_id !== null && typeof o.thread_id !== "string") return false;
  if (typeof o.channel_id !== "string") return false;
  if (typeof o.channel_name !== "string") return false;
  if (!o.author || typeof o.author !== "object") return false;
  const a = o.author as Record<string, unknown>;
  if (typeof a.id !== "string") return false;
  if (typeof a.handle !== "string") return false;
  if (typeof a.display !== "string") return false;
  if (typeof o.text !== "string") return false;
  if (typeof o.ts !== "string") return false;
  if (o.permalink !== null && typeof o.permalink !== "string") return false;
  if (!o.meta || typeof o.meta !== "object") return false;
  return true;
}

// snappy-channel-contract/verify.ts
// Kernel-side verifier: discovers every ~/.claude/skills/snappy-*/adapter.ts,
// runs its selfCheck(), and emits a table + ndjson certificate log.

import { readdir, appendFile, mkdir } from "node:fs/promises";
import { existsSync } from "node:fs";
import { resolve } from "node:path";
import type { ChannelAdapter, SelfCheckResult, Event } from "./types.ts";
import { isValidEvent } from "./types.ts";
import { realpathSync } from "fs";

const SKILLS_ROOT = `${process.env.HOME}/.claude/skills`;
const CERT_LOG = `${process.env.HOME}/.claude/logs/channel-certs.ndjson`;

export async function discoverAdapters(): Promise<
  Array<{ skill: string; path: string }>
> {
  const entries = await readdir(SKILLS_ROOT, { withFileTypes: true });
  const out: Array<{ skill: string; path: string }> = [];
  for (const e of entries) {
    if (!e.isDirectory()) continue;
    if (!e.name.startsWith("snappy-")) continue;
    const p = resolve(SKILLS_ROOT, e.name, "adapter.ts");
    if (existsSync(p)) out.push({ skill: e.name, path: p });
  }
  return out;
}

export async function runSelfCheck(
  adapter: ChannelAdapter,
): Promise<SelfCheckResult> {
  const started = Date.now();
  const errors: string[] = [];
  let read_ok = false;
  let read_count = 0;
  let shape_valid = false;
  let identify_ok: boolean | null = null;
  let firstEvent: Event | null = null;

  try {
    const events = await adapter.read(undefined, 3);
    read_ok = true;
    read_count = events.length;
    if (events.length > 0) {
      firstEvent = events[0];
      shape_valid = events.every(isValidEvent);
      if (!shape_valid) {
        errors.push(
          `shape_invalid: first event failed isValidEvent() — keys=${Object.keys(events[0] || {}).join(",")}`,
        );
      }
    } else {
      shape_valid = true; // nothing to validate; not a failure
    }
  } catch (e) {
    errors.push(`read_failed: ${(e as Error).message}`);
  }

  if (firstEvent) {
    try {
      const c = await adapter.identify(firstEvent.author.id);
      identify_ok = c !== null && typeof c.id === "string";
      if (!identify_ok) errors.push(`identify_failed: returned null or bad shape`);
    } catch (e) {
      identify_ok = false;
      errors.push(`identify_threw: ${(e as Error).message}`);
    }
  }

  const ok = read_ok && shape_valid && identify_ok !== false;

  return {
    source: adapter.source,
    ok,
    read_ok,
    read_count,
    shape_valid,
    identify_ok,
    errors,
    duration_ms: Date.now() - started,
    ts: new Date().toISOString(),
  };
}

export async function runAllChecks(): Promise<SelfCheckResult[]> {
  const adapters = await discoverAdapters();
  const results: SelfCheckResult[] = [];
  for (const { skill, path } of adapters) {
    try {
      const mod = await import(path);
      const adapter: ChannelAdapter | undefined = mod.adapter ?? mod.default;
      if (!adapter || typeof adapter.read !== "function") {
        results.push({
          source: skill.replace(/^snappy-/, "") as any,
          ok: false,
          read_ok: false,
          read_count: 0,
          shape_valid: false,
          identify_ok: null,
          errors: [`no_adapter_export: ${skill}/adapter.ts`],
          duration_ms: 0,
          ts: new Date().toISOString(),
        });
        continue;
      }
      results.push(await runSelfCheck(adapter));
    } catch (e) {
      results.push({
        source: skill.replace(/^snappy-/, "") as any,
        ok: false,
        read_ok: false,
        read_count: 0,
        shape_valid: false,
        identify_ok: null,
        errors: [`import_failed: ${(e as Error).message}`],
        duration_ms: 0,
        ts: new Date().toISOString(),
      });
    }
  }
  await writeCerts(results);
  return results;
}

async function writeCerts(results: SelfCheckResult[]) {
  await mkdir(`${process.env.HOME}/.claude/logs`, { recursive: true });
  const lines = results
    .map((r) =>
      JSON.stringify({
        ts: r.ts,
        runner: "channel-contract-verify",
        ...r,
      }),
    )
    .join("\n");
  await appendFile(CERT_LOG, lines + "\n");
}

export function renderTable(results: SelfCheckResult[]): string {
  const header = "source      ok    read  count  shape  identify  dur   errors";
  const sep = "-".repeat(header.length);
  const rows = results.map((r) => {
    const source = r.source.padEnd(11);
    const ok = (r.ok ? "PASS" : "FAIL").padEnd(5);
    const readOk = (r.read_ok ? "y" : "n").padEnd(5);
    const count = String(r.read_count).padEnd(6);
    const shape = (r.shape_valid ? "y" : "n").padEnd(6);
    const ident =
      r.identify_ok === null
        ? "skip    "
        : (r.identify_ok ? "y" : "n").padEnd(8);
    const dur = `${r.duration_ms}ms`.padEnd(5);
    const err = r.errors.join("; ").slice(0, 80);
    return `${source} ${ok} ${readOk} ${count} ${shape} ${ident} ${dur} ${err}`;
  });
  return [header, sep, ...rows].join("\n");
}

// GUARDED: importing this module from a test or another hand leaves argv[1] pointing elsewhere (or nowhere); an unguarded realpathSync threw ENOENT on import (measured 2026-09-09 by the messaging lane in both adapters).
if (process.argv[1] !== undefined && import.meta.url === `file://${realpathSync(process.argv[1])}`) {
  (async () => {
    const results = await runAllChecks();
    console.log(renderTable(results));
    const failing = results.filter((r) => !r.ok).length;
    process.exit(failing > 0 ? 1 : 0);
  })();
}