@ikenga/contract 0.7.0 → 0.9.0

package/src/canvas/use-drag-snap.ts

@@ -0,0 +1,107 @@
+// Scale-aware grid-snap drag for the <Canvas> primitive.
+//
+// Owns the in-flight drag gesture (which item, where it started) and the
+// pointer math that moves it: cursor delta is divided by the current viewport
+// scale (so a 10px screen move at scale 0.5 becomes a 20px canvas move, and at
+// scale 2.0 a 5px canvas move), then snapped to the `gridSnap` lattice.
+//
+//   nx = round((startPos.x + dx / scale) / gridSnap) * gridSnap
+//
+// Does NOT own `layout` — it reads the current placement to seed the gesture
+// and emits the moved layout through `onLayoutChange`. The parent stays the
+// source of truth.
+//
+// Extracted verbatim (behavior-preserving) from shell home.tsx's canvas block.
+
+import { useCallback, useEffect, useRef } from 'react';
+import type { ItemId, Placement } from './types.js';
+
+export interface DragState {
+  id: ItemId;
+  startMouse: { x: number; y: number };
+  startPos: { x: number; y: number };
+}
+
+export interface UseDragSnapArgs {
+  /** Controlled layout (id → placement). Read at gesture start; never mutated. */
+  layout: Record<ItemId, Placement>;
+  /** Snap lattice in canvas units. Home passes 12, studio passes 24. */
+  gridSnap: number;
+  /** Current viewport scale — drag delta is divided by this. */
+  scale: number;
+  /** Emits the moved layout so the parent can persist / re-render. */
+  onLayoutChange?: (layout: Record<ItemId, Placement>) => void;
+  /** Stage element whose `.is-dragging` class suppresses the pan transition. */
+  stageRef: React.RefObject<HTMLDivElement | null>;
+}
+
+export interface UseDragSnap {
+  dragState: React.MutableRefObject<DragState | null>;
+  /** Begin dragging `id` from a mousedown at screen (clientX, clientY). */
+  beginDrag: (id: ItemId, clientX: number, clientY: number) => void;
+  /** Is an item drag in flight? */
+  isDragging: () => boolean;
+}
+
+export function useDragSnap(args: UseDragSnapArgs): UseDragSnap {
+  const { layout, gridSnap, scale, onLayoutChange, stageRef } = args;
+  const dragState = useRef<DragState | null>(null);
+
+  // Keep the freshest layout/scale/snap reachable from the global listener
+  // without re-subscribing it on every render.
+  const layoutRef = useRef(layout);
+  layoutRef.current = layout;
+  const scaleRef = useRef(scale);
+  scaleRef.current = scale;
+  const gridSnapRef = useRef(gridSnap);
+  gridSnapRef.current = gridSnap;
+  const onLayoutChangeRef = useRef(onLayoutChange);
+  onLayoutChangeRef.current = onLayoutChange;
+
+  const beginDrag = useCallback(
+    (id: ItemId, clientX: number, clientY: number) => {
+      const w = layoutRef.current[id];
+      if (!w) return;
+      dragState.current = {
+        id,
+        startMouse: { x: clientX, y: clientY },
+        startPos: { x: w.x, y: w.y },
+      };
+      stageRef.current?.classList.add('is-dragging');
+    },
+    [stageRef]
+  );
+
+  const isDragging = useCallback(() => dragState.current != null, []);
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => {
+      if (!dragState.current) return;
+      const s = scaleRef.current || 1;
+      const snap = gridSnapRef.current;
+      const dx = e.clientX - dragState.current.startMouse.x;
+      const dy = e.clientY - dragState.current.startMouse.y;
+      const nx = Math.round((dragState.current.startPos.x + dx / s) / snap) * snap;
+      const ny = Math.round((dragState.current.startPos.y + dy / s) / snap) * snap;
+      const id = dragState.current.id;
+      const cur = layoutRef.current;
+      const prev = cur[id];
+      if (!prev || (prev.x === nx && prev.y === ny)) return;
+      onLayoutChangeRef.current?.({ ...cur, [id]: { ...prev, x: nx, y: ny } });
+    };
+    const onUp = () => {
+      if (dragState.current) {
+        dragState.current = null;
+        stageRef.current?.classList.remove('is-dragging');
+      }
+    };
+    window.addEventListener('mousemove', onMove);
+    window.addEventListener('mouseup', onUp);
+    return () => {
+      window.removeEventListener('mousemove', onMove);
+      window.removeEventListener('mouseup', onUp);
+    };
+  }, [stageRef]);
+
+  return { dragState, beginDrag, isDragging };
+}

package/src/canvas/use-pan-zoom.ts

@@ -0,0 +1,211 @@
+// Pan / zoom / auto-fit for the <Canvas> primitive.
+//
+// Owns the viewport pan offset + scale, the imperative auto-fit math, the
+// pan gesture (Space-drag / middle-mouse / empty-canvas drag), and the
+// Space/Escape keyboard affordances + window-resize re-fit. It deliberately
+// does NOT own `layout`, `selectedId`, or `editMode` — those stay parent-held
+// and are threaded in as values so the auto-fit closure can read them.
+//
+// Extracted verbatim (behavior-preserving) from shell home.tsx's canvas block.
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { ItemId, Placement, Viewport } from './types.js';
+
+export interface UsePanZoomArgs {
+  /** Controlled layout (id → placement) the auto-fit bounding box reads. */
+  layout: Record<ItemId, Placement>;
+  /** Controlled edit-mode flag — auto-fit reserves palette width when true. */
+  editMode: boolean;
+  /** Re-fit on window resize. Default true. */
+  autoFitOnResize?: boolean;
+  /** Notified whenever the viewport pan/scale changes (controlled mirror). */
+  onViewportChange?: (viewport: Viewport) => void;
+  /** Escape exits edit mode → parent owns the state flip. */
+  onEditModeChange?: (editMode: boolean) => void;
+  /** Escape clears selection. */
+  onSelectionChange?: (selectedId: ItemId | null) => void;
+}
+
+export interface UsePanZoom {
+  /** Live viewport (x/y/scale). Mirrors `pan` in the original home code. */
+  pan: Viewport;
+  setPan: React.Dispatch<React.SetStateAction<Viewport>>;
+  /** Imperative re-fit. `animate=false` snaps without the transition. */
+  autoFit: (animate?: boolean) => void;
+  canvasRef: React.RefObject<HTMLDivElement | null>;
+  stageRef: React.RefObject<HTMLDivElement | null>;
+  /** True while Space is held — drag/pan branch reads this. */
+  spaceDown: React.MutableRefObject<boolean>;
+  /** Begin a pan gesture from a mousedown at screen (clientX, clientY). */
+  beginPan: (clientX: number, clientY: number) => void;
+  /** Is a pan gesture in flight? */
+  isPanning: () => boolean;
+}
+
+const RESERVED_PALETTE_WIDTH = 320;
+
+export function usePanZoom(args: UsePanZoomArgs): UsePanZoom {
+  const {
+    layout,
+    editMode,
+    autoFitOnResize = true,
+    onViewportChange,
+    onEditModeChange,
+    onSelectionChange,
+  } = args;
+
+  const [pan, setPan] = useState<Viewport>({ x: 0, y: 0, scale: 1 });
+
+  const canvasRef = useRef<HTMLDivElement>(null);
+  const stageRef = useRef<HTMLDivElement>(null);
+  const spaceDown = useRef(false);
+  const panStart = useRef<{ x: number; y: number } | null>(null);
+  // Latest pan reachable synchronously (for beginPan's offset seed) without
+  // adding `pan` to the gesture callbacks' deps.
+  const panRef = useRef(pan);
+  panRef.current = pan;
+
+  // Mirror viewport changes to the controlled parent in an effect (never
+  // inside a setState updater — that would setState-during-render the parent
+  // and trip React's "Cannot update a component while rendering a different
+  // component" warning). The ref skips the initial mount so the parent isn't
+  // notified of the default {0,0,1} before any real fit.
+  const viewportCbRef = useRef(onViewportChange);
+  viewportCbRef.current = onViewportChange;
+  const mountedViewport = useRef(false);
+  useEffect(() => {
+    if (!mountedViewport.current) {
+      mountedViewport.current = true;
+      return;
+    }
+    viewportCbRef.current?.(pan);
+  }, [pan]);
+
+  // Auto-fit: scale the bounding box of all items into the visible area,
+  // scaling down only (never up). Reserves the palette gutter in edit mode.
+  // Threads `layout` + `editMode` as deps so the closure never goes stale.
+  const autoFit = useCallback(
+    (animate = true) => {
+      const canvas = canvasRef.current;
+      const items = Object.values(layout);
+      if (!canvas || !items.length) return;
+      let minX = Infinity,
+        minY = Infinity,
+        maxX = -Infinity,
+        maxY = -Infinity;
+      for (const w of items) {
+        if (w.x < minX) minX = w.x;
+        if (w.y < minY) minY = w.y;
+        if (w.x + w.w > maxX) maxX = w.x + w.w;
+        if (w.y + w.h > maxY) maxY = w.y + w.h;
+      }
+      const cw = canvas.clientWidth - (editMode ? RESERVED_PALETTE_WIDTH : 0) - 40;
+      const ch = canvas.clientHeight - 44 - 32;
+      const bw = maxX - minX;
+      const bh = maxY - minY;
+      const sx = bw > 0 ? cw / bw : 1;
+      const sy = bh > 0 ? ch / bh : 1;
+      const scale = Math.min(1, sx, sy);
+      const offX = Math.round((cw + 40 - bw * scale) / 2 - minX * scale);
+      const offY = Math.round((ch + 32 - bh * scale) / 2 - minY * scale + 22);
+      setPan({ x: offX, y: offY, scale });
+      if (stageRef.current) stageRef.current.classList.toggle('is-dragging', !animate);
+    },
+    [layout, editMode, setPan]
+  );
+
+  // Initial fit + window-resize re-fit. Empty dep array on purpose — autoFit
+  // is read through the ref-stable callback, matching the original effect.
+  useEffect(() => {
+    requestAnimationFrame(() => autoFit(false));
+    if (!autoFitOnResize) return;
+    const onResize = () => autoFit(true);
+    window.addEventListener('resize', onResize);
+    return () => window.removeEventListener('resize', onResize);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Re-fit whenever edit mode toggles (palette gutter changes the fit box).
+  useEffect(() => {
+    autoFit(true);
+  }, [editMode, autoFit]);
+
+  // Keyboard — Escape exits edit, Space arms the pan-grab cursor.
+  useEffect(() => {
+    const down = (e: KeyboardEvent) => {
+      if (e.key === 'Escape' && editMode) {
+        onEditModeChange?.(false);
+        onSelectionChange?.(null);
+      }
+      if (
+        e.code === 'Space' &&
+        !e.repeat &&
+        document.activeElement === document.body &&
+        canvasRef.current
+      ) {
+        spaceDown.current = true;
+        canvasRef.current.style.cursor = 'grab';
+        e.preventDefault();
+      }
+    };
+    const up = (e: KeyboardEvent) => {
+      if (e.code === 'Space') {
+        spaceDown.current = false;
+        if (canvasRef.current) canvasRef.current.style.cursor = '';
+      }
+    };
+    window.addEventListener('keydown', down);
+    window.addEventListener('keyup', up);
+    return () => {
+      window.removeEventListener('keydown', down);
+      window.removeEventListener('keyup', up);
+    };
+  }, [editMode, onEditModeChange, onSelectionChange]);
+
+  const beginPan = useCallback((clientX: number, clientY: number) => {
+    const p = panRef.current;
+    panStart.current = { x: clientX - p.x, y: clientY - p.y };
+    stageRef.current?.classList.add('is-dragging');
+    if (canvasRef.current) canvasRef.current.style.cursor = 'grabbing';
+  }, []);
+
+  const isPanning = useCallback(() => panStart.current != null, []);
+
+  // Global pan move/up. Drag (item) move/up lives in use-drag-snap so this
+  // effect only owns the pan branch + its own cleanup.
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => {
+      if (panStart.current) {
+        setPan((p) => ({
+          ...p,
+          x: e.clientX - panStart.current!.x,
+          y: e.clientY - panStart.current!.y,
+        }));
+      }
+    };
+    const onUp = () => {
+      if (panStart.current) {
+        panStart.current = null;
+        stageRef.current?.classList.remove('is-dragging');
+        if (canvasRef.current) canvasRef.current.style.cursor = spaceDown.current ? 'grab' : '';
+      }
+    };
+    window.addEventListener('mousemove', onMove);
+    window.addEventListener('mouseup', onUp);
+    return () => {
+      window.removeEventListener('mousemove', onMove);
+      window.removeEventListener('mouseup', onUp);
+    };
+  }, [setPan]);
+
+  return {
+    pan,
+    setPan,
+    autoFit,
+    canvasRef,
+    stageRef,
+    spaceDown,
+    beginPan,
+    isPanning,
+  };
+}

package/src/host-verbs.ts

@@ -0,0 +1,207 @@
+/**
+ * Host-bridge verb shapes for the agent-ops pkg — the **G-TRIGGER** freeze gate.
+ *
+ * Unlike the kernel RPC methods in `rpc.ts`, `host.*` verbs are dispatched
+ * FE-side in the iframe host (`shell/src/components/pkg/pkg-iframe-host.tsx`)
+ * and invoked from the iframe via `app.callServerTool({ name, arguments })`,
+ * returning their payload on `res.structuredContent`. These types are the
+ * shared contract the shell (WP-09) produces and the agent-ops pkg
+ * (WP-08 reads, WP-12 writes) consumes. Frozen so changing them after both
+ * sides exist forces a cross-repo re-sync.
+ *
+ * Gated by `capabilities.agentOps` (see `AgentOpsCapabilitySchema`).
+ */
+
+/** Typed failure codes a host.agentOps verb returns on the `{ ok: false }`
+ *  branch, so the pkg UI can render a specific state rather than a raw string.
+ *  - `daemon_down`   — `~/.agent-ops/daemon.lock` missing or daemon not alive
+ *  - `unauthorized`  — the daemon rejected the token (401) — should not happen
+ *                      in normal operation (the shell reads the live lock)
+ *  - `not_found`     — no job with that id (daemon 404 / config miss)
+ *  - `disabled`      — job is disabled, cannot run-now (daemon 409)
+ *  - `forbidden`     — daemon rejected host/origin/method (403/405)
+ *  - `io_error`      — lock/config file unreadable or unwritable
+ *  - `error`         — any other failure */
+export type AgentOpsErrorCode =
+  | 'daemon_down'
+  | 'unauthorized'
+  | 'not_found'
+  | 'disabled'
+  | 'forbidden'
+  | 'io_error'
+  | 'error';
+
+export interface AgentOpsErrorResult {
+  ok: false;
+  code: AgentOpsErrorCode;
+  /** HTTP status from the daemon when applicable, else null. */
+  status: number | null;
+  error: string;
+}
+
+/** `host.agentOps.runNow({ jobId })` — fire an out-of-schedule run via the
+ *  daemon's localhost trigger endpoint. The shell reads the 0600
+ *  `~/.agent-ops/daemon.lock` for `{ port, secret }` and POSTs
+ *  `127.0.0.1:<port>/jobs/<jobId>/trigger` with BOTH required headers
+ *  (`x-agent-ops-token: <secret>` + `x-agent-ops-trigger: 1`). */
+export interface AgentOpsRunNowArgs {
+  jobId: string;
+}
+export type AgentOpsRunNowResult =
+  | { ok: true; status: number; message: string }
+  | AgentOpsErrorResult;
+
+/** `host.agentOps.setEnabled({ jobId, enabled })` — flip a job's `enabled`
+ *  flag in the project-scoped config (`~/.atelier/skill-agent-ops/jobs.json`).
+ *  The daemon honors it on next config load. Does NOT touch the executor. */
+export interface AgentOpsSetEnabledArgs {
+  jobId: string;
+  enabled: boolean;
+}
+export type AgentOpsSetEnabledResult =
+  | { ok: true; jobId: string; enabled: boolean }
+  | AgentOpsErrorResult;
+
+/** The editable job fields the CRUD form sends to `host.agentOps.upsertJob`.
+ *  The host fills JobDefinition defaults (schedule_dialect, timeout_ms, retries,
+ *  backoff, concurrency_policy) for any omitted field; the daemon's Zod loader
+ *  is the final validation backstop on next config load. */
+export interface AgentOpsJobInput {
+  id: string;
+  label: string;
+  schedule: string;
+  timezone?: string;
+  enabled?: boolean;
+  mode?: 'agent' | 'script';
+  command: string;
+  model?: string | null;
+  agent?: string | null;
+  schedule_dialect?: '5f' | '6f';
+  timeout_ms?: number;
+}
+
+/** `host.agentOps.upsertJob({ job })` — create-or-update a job in the
+ *  project-scoped config (atomic rewrite; replace by id if present, else
+ *  append). The daemon honors it on next config load. Validating-only write —
+ *  the shell does NOT run the job, never becomes the executor. */
+export interface AgentOpsUpsertJobArgs {
+  job: AgentOpsJobInput;
+}
+export type AgentOpsUpsertJobResult =
+  | { ok: true; jobId: string; created: boolean }
+  | AgentOpsErrorResult;
+
+/** `host.agentOps.deleteJob({ jobId })` — remove a job from the project-scoped
+ *  config (atomic rewrite). The daemon stops scheduling it on next load. */
+export interface AgentOpsDeleteJobArgs {
+  jobId: string;
+}
+export type AgentOpsDeleteJobResult =
+  | { ok: true; jobId: string }
+  | AgentOpsErrorResult;
+
+/** `host.agentOps.tailRun({ jobId, offset? })` — read the live (or last-completed)
+ *  run output for a job by byte-range, for the pkg's Live-output view.
+ *
+ *  Unlike the other agent-ops verbs (which reach the daemon's localhost endpoint
+ *  or rewrite its config), tailRun is a pure **filesystem read on the shell's own
+ *  event loop**: it opens the per-job marker (`~/.agent-ops/runs/<slug>.marker.json`)
+ *  to learn the current run's `tailPath` + `status` + `pid`, then reads that tail
+ *  file from `offset` forward (capped per call). Because it never touches the
+ *  daemon, the daemon being blocked mid-run (synchronously executing a job) is
+ *  irrelevant — the shell still streams whatever the child has teed to disk so far.
+ *
+ *  Mechanism is **script-mode only**: the daemon tees a script job's combined
+ *  stdout/stderr to the tail file as it runs. Agent jobs (`claude -p`) stay
+ *  byte-for-byte unchanged and have no tail file, so tailRun returns an empty
+ *  chunk with `mode:'agent'` (the pkg renders 'live output not available for
+ *  agent jobs' + a spinner driven off the marker's `status`).
+ *
+ *  Polling loop: call with `offset:0` first, then feed the returned `nextOffset`
+ *  back on each poll. `eof` true means the reader caught up to the current end of
+ *  file; keep polling while `running` is true. After a run completes the marker
+ *  still points at the final tail, so `running:false` STILL returns the final
+ *  chunk for scrollback — the view shows the completed output, not an empty pane.
+ *
+ *  - `running`     — `status === 'running'` AND the marker's `pid` is alive.
+ *  - `status`      — the marker's `status` (`'running' | 'done'`), or `null` when
+ *                    no marker exists yet (job has never produced a run).
+ *  - `startedAtMs` — the run's start epoch-ms from the marker, else `null`.
+ *  - `mode`        — `'script'` (has a tail) / `'agent'` (no tail) / `null` (no marker).
+ *  - `chunk`       — lossy-utf8 decode of the bytes read this call (may be empty).
+ *  - `nextOffset`  — `offset + bytesRead`; pass back on the next poll.
+ *  - `eof`         — reached the current end of the tail file.
+ *
+ *  Best-effort + non-throwing on the shell side: a missing marker / missing tail /
+ *  unreadable file resolves to `{ ok:true, chunk:'', eof:true, ... }` rather than
+ *  an error, so the view degrades to 'no output yet'. Only a path-escape attempt
+ *  (marker.tailPath pointing outside `~/.agent-ops/runs/`) maps to an
+ *  `{ ok:false, code:'io_error' }`. */
+export interface AgentOpsTailRunArgs {
+  jobId: string;
+  /** Byte offset into the tail file to read from. Defaults to 0. */
+  offset?: number;
+}
+export type AgentOpsTailRunResult =
+  | {
+      ok: true;
+      running: boolean;
+      status: 'running' | 'done' | null;
+      startedAtMs: number | null;
+      mode: 'agent' | 'script' | null;
+      chunk: string;
+      nextOffset: number;
+      eof: boolean;
+    }
+  | AgentOpsErrorResult;
+
+/** A merged config+state row as returned by `host.agentOps.listJobs`. Config
+ *  fields come from `~/.atelier/skill-agent-ops/jobs.json` (a JobDefinition);
+ *  `state` is that job's entry in `.company/cron/jobs-state.json` (or null if
+ *  it has never run). Field casing matches the on-disk files (camelCase state);
+ *  the pkg's data layer (WP-08) maps this into the snake_case G-VIEW. */
+export interface AgentOpsRawJobState {
+  nextRunAtMs: number | null;
+  lastRunAtMs: number | null;
+  lastStatus: string | null;
+  consecutiveErrors: number;
+  lastDurationMs: number | null;
+  totalCostUsd: number | null;
+  totalRuns: number | null;
+  lastUsage: {
+    costUsd: number | null;
+    numTurns: number | null;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    cacheReadTokens: number | null;
+    sessionId: string | null;
+  } | null;
+}
+export interface AgentOpsRawJob {
+  id: string;
+  label: string;
+  schedule: string;
+  schedule_dialect: '5f' | '6f';
+  timezone: string;
+  enabled: boolean;
+  command: string;
+  mode: 'agent' | 'script';
+  model: string | null;
+  agent: string | null;
+  _disabledReason: string | null;
+  state: AgentOpsRawJobState | null;
+}
+
+/** `host.agentOps.listJobs({})` — read the project-scoped job config + the
+ *  daemon's runtime state file and return both, merged per job, plus daemon
+ *  liveness. Run history (cron_job_runs / agent_runs) is NOT included here —
+ *  the pkg reads that directly via `host.dbQuery`. */
+export type AgentOpsListJobsArgs = Record<string, never>;
+export type AgentOpsListJobsResult =
+  | {
+      ok: true;
+      daemon_up: boolean;
+      daemon_pid: number | null;
+      jobs: AgentOpsRawJob[];
+    }
+  | AgentOpsErrorResult;

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './manifest.js';
 export * from './rpc.js';
+export * from './host-verbs.js';
 export * from './engine/index.js';
 export * from './scopes.js';
 export * from './iyke.js';

package/src/manifest.test.ts

@@ -0,0 +1,97 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  ManifestSchema,
+  RequiresEntrySchema,
+  RequireSourceSchema,
+} from './manifest.js';
+
+// ─── WP-11 — `requires` field (ADR-015 §3) ──────────────────────────────────
+
+const BASE = {
+  id: 'com.ikenga.studio',
+  name: 'Studio',
+  version: '0.1.0',
+  ikenga_api: '1',
+};
+
+test('RequiresEntry: full shape parses', () => {
+  const e = RequiresEntrySchema.parse({
+    kind: 'skill',
+    name: '@ikenga/studio-beat-detect',
+    source: 'npx',
+    ref: 'v1.2.0',
+  });
+  assert.equal(e.kind, 'skill');
+  assert.equal(e.source, 'npx');
+  assert.equal(e.ref, 'v1.2.0');
+});
+
+test('RequiresEntry: source + ref optional', () => {
+  const e = RequiresEntrySchema.parse({ kind: 'skill', name: 'skill-core' });
+  assert.equal(e.source, undefined);
+  assert.equal(e.ref, undefined);
+});
+
+test('RequiresEntry: rejects unknown field (.strict mirrors Rust deny_unknown_fields)', () => {
+  assert.throws(() =>
+    RequiresEntrySchema.parse({ kind: 'skill', name: 'skill-core', bogus: true }),
+  );
+});
+
+test('RequiresEntry: kind bundle is accepted (WP-18 G-BUNDLE)', () => {
+  // WP-18 locked design decision 4: `RequiresEntrySchema.kind` is `z.string()`
+  // (a free string, not a closed enum), so a `requires` entry may reference a
+  // bundle — `{kind:"bundle", name}` parses and carries the kind through. This
+  // is the contract-side half of the G-BUNDLE "requires kind:bundle parses" DoD.
+  const e = RequiresEntrySchema.parse({ kind: 'bundle', name: 'studio-archetypes' });
+  assert.equal(e.kind, 'bundle');
+  assert.equal(e.name, 'studio-archetypes');
+});
+
+test('RequiresEntry: rejects an out-of-set source', () => {
+  assert.throws(() =>
+    RequiresEntrySchema.parse({ kind: 'skill', name: 'x', source: 'ftp' }),
+  );
+});
+
+test('RequireSource: only git|npx|catalog|local', () => {
+  for (const s of ['git', 'npx', 'catalog', 'local']) {
+    assert.equal(RequireSourceSchema.parse(s), s);
+  }
+  assert.throws(() => RequireSourceSchema.parse('http'));
+});
+
+test('Manifest: requires parses and round-trips', () => {
+  const m = ManifestSchema.parse({
+    ...BASE,
+    requires: [
+      { kind: 'skill', name: '@ikenga/studio-archetypes', source: 'npx' },
+      { kind: 'skill', name: 'skill-core', source: 'git', ref: 'v1.0.0' },
+      { kind: 'skill', name: '@ikenga/studio-doctor' },
+    ],
+  });
+  assert.equal(m.requires.length, 3);
+  assert.equal(m.requires[0].name, '@ikenga/studio-archetypes');
+  assert.equal(m.requires[2].source, undefined);
+});
+
+test('Manifest: requires defaults to [] when absent (pre-Phase-4 manifest)', () => {
+  const m = ManifestSchema.parse({ ...BASE });
+  assert.deepEqual(m.requires, []);
+});
+
+test('Manifest: retired bundling fields are no longer part of the type (WP-17)', () => {
+  // ADR-015 decision 4: `skills`/`commands`/`agents` were hard-retired from the
+  // schema (lockstep with the Rust `deny_unknown_fields` Manifest, which REJECTS
+  // them — the authoritative loader). ManifestSchema is non-strict, so a stray
+  // legacy key is stripped rather than rejected here; assert it does not survive
+  // onto the parsed object.
+  const m = ManifestSchema.parse({ ...BASE, skills: 'skills', commands: 'commands' }) as Record<
+    string,
+    unknown
+  >;
+  assert.equal(m.skills, undefined);
+  assert.equal(m.commands, undefined);
+});