@ikenga/contract 0.17.0 → 0.18.0

package/src/ngwa.test.ts

@@ -0,0 +1,330 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  NGWA_KINDS,
+  NGWA_SOURCES,
+  NGWA_STATES,
+  NgwaItemSchema,
+  NgwaOriginSchema,
+  NgwaPermsSummarySchema,
+  NgwaPlacementSchema,
+  NgwaRefSchema,
+  NgwaRuntimeSchema,
+  NgwaScopeSchema,
+  NgwaSnapshotSchema,
+  NgwaTrustSchema,
+  NgwaUsageSchema,
+} from './ngwa.js';
+
+// ─── WP-13 — G-NGWA-ITEM (drafts/ngwa-item.md §2, frozen Round 11) ──────────
+
+const ORIGIN = {
+  source: 'registry',
+  url: 'https://registry.ikenga.dev/index.json',
+  ref: null,
+  resolved_version: '0.4.2',
+  publisher: 'ikenga-hq',
+  managed: true,
+  auto_update: false,
+  installed_at_ms: 1_726_000_000_000,
+  updated_at_ms: 1_726_900_000_000,
+};
+
+const PERMS = {
+  shell_execute: ['git *'],
+  fs_write_outside_sandbox: ['~/.claude/**'],
+  net: ['https://api.royalti.io/**'],
+  vault_keys: ['supabase.anon'],
+};
+
+const TRUST = {
+  state: 'granted',
+  signed: true,
+  auto_trusted: false,
+  review_pending: false,
+  perms: PERMS,
+  last_granted_at_ms: 1_726_900_000_000,
+};
+
+const RUNTIME = {
+  state: 'running',
+  pid: 44_112,
+  uptime_s: 903,
+  restarts: 1,
+  last_err: null,
+  last_crash_ms: null,
+};
+
+const PLACEMENT = {
+  engine: 'claude',
+  scope: { kind: 'project', project_id: 'C--Users-x-royalti-co' },
+  path: '/Users/x/royalti-co/.claude/skills/groundwork',
+  mechanism: 'symlink-dir',
+  present: true,
+  link_target: '/Users/x/.ikenga/oba/skills/groundwork',
+  in_store: true,
+  managed_by: 'oba',
+  overridden_by: null,
+  format: 'md-yaml',
+  status: 'active',
+};
+
+const USAGE = {
+  source: 'transcript',
+  last_used_ms: 1_726_950_000_000,
+  count_7d: 12,
+  count_30d: 72,
+  tokens_30d: 1_240_991,
+  window_start_ms: 1_724_000_000_000,
+};
+
+const REF = {
+  kind: 'skill',
+  name: 'skill-core',
+  item_id: 'skill:personal:skill-core',
+  source: 'catalog',
+  ref: null,
+};
+
+const ITEM = {
+  id: 'com.ikenga.studio',
+  kind: 'app',
+  name: 'studio',
+  display_name: 'Studio',
+  description: 'Beat-detection workbench.',
+  version: '0.4.2',
+  latest_version: '0.5.0',
+  scope: { kind: 'personal' },
+  origin: ORIGIN,
+  state: 'enabled',
+  runtime: RUNTIME,
+  trust: TRUST,
+  placements: [PLACEMENT],
+  usage: USAGE,
+  requires: [REF],
+  required_by: [],
+  owner_pkg_id: null,
+  install_path: '/Users/x/.ikenga/pkgs/com.ikenga.studio',
+  engines: ['claude'],
+};
+
+const SOURCE_HEALTH = { ok: true, error: null, count: 3 };
+
+const SNAPSHOT = {
+  items: [ITEM],
+  as_of_ms: 1_726_951_000_000,
+  sources: {
+    kernel: SOURCE_HEALTH,
+    oba: SOURCE_HEALTH,
+    engine_config: SOURCE_HEALTH,
+    engine_assets: { ok: false, error: 'registry snapshot unavailable', count: 0 },
+    trust: SOURCE_HEALTH,
+    usage: SOURCE_HEALTH,
+  },
+};
+
+/** Every object key anywhere in a parsed value must be snake_case (§2: the
+ *  producer is a Rust command serializing with serde defaults and no renames). */
+function assertSnakeCaseKeys(value: unknown, path = '$'): void {
+  if (Array.isArray(value)) {
+    value.forEach((v, i) => assertSnakeCaseKeys(v, `${path}[${i}]`));
+    return;
+  }
+  if (value === null || typeof value !== 'object') return;
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    assert.match(k, /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/, `key ${path}.${k} is not snake_case`);
+    assertSnakeCaseKeys(v, `${path}.${k}`);
+  }
+}
+
+const keys = (o: object) => Object.keys(o).sort();
+
+// ── (a) every field in §2 is present, and keys are snake_case ──────────────
+
+test('Ngwa: every field name in draft §2 is present on a parsed fixture', () => {
+  const item = NgwaItemSchema.parse(ITEM);
+
+  assert.deepEqual(keys(item), keys({
+    id: 0, kind: 0, name: 0, display_name: 0, description: 0, version: 0,
+    latest_version: 0, scope: 0, origin: 0, state: 0, runtime: 0, trust: 0,
+    placements: 0, usage: 0, requires: 0, required_by: 0, owner_pkg_id: 0,
+    install_path: 0, engines: 0,
+  }));
+
+  assert.deepEqual(keys(NgwaOriginSchema.parse(ORIGIN)), keys({
+    source: 0, url: 0, ref: 0, resolved_version: 0, publisher: 0, managed: 0,
+    auto_update: 0, installed_at_ms: 0, updated_at_ms: 0,
+  }));
+
+  assert.deepEqual(keys(NgwaRuntimeSchema.parse(RUNTIME)), keys({
+    state: 0, pid: 0, uptime_s: 0, restarts: 0, last_err: 0, last_crash_ms: 0,
+  }));
+
+  assert.deepEqual(keys(NgwaTrustSchema.parse(TRUST)), keys({
+    state: 0, signed: 0, auto_trusted: 0, review_pending: 0, perms: 0,
+    last_granted_at_ms: 0,
+  }));
+
+  assert.deepEqual(keys(NgwaPermsSummarySchema.parse(PERMS)), keys({
+    shell_execute: 0, fs_write_outside_sandbox: 0, net: 0, vault_keys: 0,
+  }));
+
+  assert.deepEqual(keys(NgwaPlacementSchema.parse(PLACEMENT)), keys({
+    engine: 0, scope: 0, path: 0, mechanism: 0, present: 0, link_target: 0,
+    in_store: 0, managed_by: 0, overridden_by: 0, format: 0, status: 0,
+  }));
+
+  assert.deepEqual(keys(NgwaUsageSchema.parse(USAGE)), keys({
+    source: 0, last_used_ms: 0, count_7d: 0, count_30d: 0, tokens_30d: 0,
+    window_start_ms: 0,
+  }));
+
+  assert.deepEqual(keys(NgwaRefSchema.parse(REF)), keys({
+    kind: 0, name: 0, item_id: 0, source: 0, ref: 0,
+  }));
+
+  const snap = NgwaSnapshotSchema.parse(SNAPSHOT);
+  assert.deepEqual(keys(snap), ['as_of_ms', 'items', 'sources']);
+  assert.deepEqual(keys(snap.sources), [
+    'engine_assets', 'engine_config', 'kernel', 'oba', 'trust', 'usage',
+  ]);
+  assert.deepEqual(keys(snap.sources.kernel), ['count', 'error', 'ok']);
+
+  // …and nothing anywhere in the parsed snapshot is camelCase.
+  assertSnakeCaseKeys(snap);
+});
+
+test('Ngwa: the three frozen enum lists match §2 exactly', () => {
+  assert.deepEqual([...NGWA_KINDS], [
+    'app', 'engine', 'tool', 'sidecar',
+    'skill', 'agent', 'command', 'hook',
+    'bundle', 'schedule', 'workflow',
+  ]);
+  assert.deepEqual([...NGWA_SOURCES], [
+    'builtin', 'registry', 'git', 'npx', 'local', 'dev', 'catalog',
+  ]);
+  assert.deepEqual([...NGWA_STATES], [
+    'enabled', 'disabled', 'available', 'update', 'orphaned', 'broken',
+  ]);
+});
+
+// ── (b) invalid kind is rejected ───────────────────────────────────────────
+
+test('Ngwa: an invalid kind is rejected', () => {
+  // `project` and `artifact` appear in the older ngwa-surface.html mock but are
+  // deliberately NOT in the union (§4) — neither has a producer.
+  assert.throws(() => NgwaItemSchema.parse({ ...ITEM, kind: 'project' }));
+  assert.throws(() => NgwaItemSchema.parse({ ...ITEM, kind: 'artifact' }));
+  assert.throws(() => NgwaItemSchema.parse({ ...ITEM, kind: 'APP' }));
+  // …while every frozen kind is accepted.
+  for (const k of NGWA_KINDS) {
+    assert.equal(NgwaItemSchema.parse({ ...ITEM, kind: k }).kind, k);
+  }
+});
+
+// ── (c) invalid origin.source is rejected ──────────────────────────────────
+
+test('Ngwa: an invalid origin.source is rejected', () => {
+  assert.throws(() =>
+    NgwaItemSchema.parse({ ...ITEM, origin: { ...ORIGIN, source: 'ftp' } }),
+  );
+  assert.throws(() => NgwaOriginSchema.parse({ ...ORIGIN, source: 'marketplace' }));
+  assert.throws(() => NgwaOriginSchema.parse({ ...ORIGIN, source: null }));
+  for (const s of NGWA_SOURCES) {
+    assert.equal(NgwaOriginSchema.parse({ ...ORIGIN, source: s }).source, s);
+  }
+});
+
+// ── (d) usage: null vs a measured zero ─────────────────────────────────────
+
+test('Ngwa: usage null parses and is distinguishable from a zeroed NgwaUsage', () => {
+  const unmeasured = NgwaItemSchema.parse({ ...ITEM, usage: null });
+  assert.equal(unmeasured.usage, null);
+
+  const zeroed = NgwaItemSchema.parse({
+    ...ITEM,
+    usage: {
+      source: 'transcript',
+      last_used_ms: null,
+      count_7d: 0,
+      count_30d: 0,
+      tokens_30d: 0,
+      window_start_ms: 1_724_000_000_000,
+    },
+  });
+  assert.notEqual(zeroed.usage, null);
+  assert.equal(zeroed.usage?.count_7d, 0);
+  assert.equal(zeroed.usage?.count_30d, 0);
+
+  // The whole point of the nullable: "never measured" must not collapse into a
+  // measured zero (frame-workbench-v4.html:2679 — unmeasured reads "—", not 0).
+  assert.notDeepEqual(unmeasured.usage, zeroed.usage);
+  assert.equal(unmeasured.usage ?? 'dash', 'dash');
+  assert.notEqual(zeroed.usage ?? 'dash', 'dash');
+
+  // `usage` is required on the item — absent is not the same as null.
+  const { usage: _omit, ...withoutUsage } = ITEM;
+  assert.throws(() => NgwaItemSchema.parse(withoutUsage));
+});
+
+// ── Scope: the two-arm discriminated union ─────────────────────────────────
+
+test('Ngwa: NgwaScope is a two-arm union discriminated on kind', () => {
+  assert.deepEqual(NgwaScopeSchema.parse({ kind: 'personal' }), { kind: 'personal' });
+  assert.deepEqual(NgwaScopeSchema.parse({ kind: 'project', project_id: 'p1' }), {
+    kind: 'project',
+    project_id: 'p1',
+  });
+  // project_id is required on the project arm, and absent from the personal one.
+  assert.throws(() => NgwaScopeSchema.parse({ kind: 'project' }));
+  assert.throws(() => NgwaScopeSchema.parse({ kind: 'workspace' }));
+});
+
+// ── Nullability and openness the draft calls out explicitly ────────────────
+
+test('Ngwa: runtime is null for items with no supervisor child', () => {
+  const skill = NgwaItemSchema.parse({ ...ITEM, kind: 'skill', runtime: null });
+  assert.equal(skill.runtime, null);
+});
+
+test('Ngwa: Ọba primitives carry trust not_applicable with perms null (§5)', () => {
+  const item = NgwaItemSchema.parse({
+    ...ITEM,
+    kind: 'skill',
+    trust: {
+      state: 'not_applicable',
+      signed: false,
+      auto_trusted: false,
+      review_pending: false,
+      perms: null,
+      last_granted_at_ms: null,
+    },
+  });
+  assert.equal(item.trust.state, 'not_applicable');
+  assert.equal(item.trust.perms, null);
+});
+
+test('Ngwa: NgwaRef.kind stays open, mirroring RequiresEntry.kind', () => {
+  // §2: `NgwaKind | string` — a future primitive kind must not break a snapshot.
+  assert.equal(NgwaRefSchema.parse({ ...REF, kind: 'mcp' }).kind, 'mcp');
+  assert.equal(NgwaRefSchema.parse({ ...REF, kind: 'bundle' }).kind, 'bundle');
+  // …but NgwaRef.source is the closed NgwaSource union, nullable.
+  assert.equal(NgwaRefSchema.parse({ ...REF, source: null }).source, null);
+  assert.throws(() => NgwaRefSchema.parse({ ...REF, source: 'ftp' }));
+});
+
+test('Ngwa: an item with no placements is not an error (a pkg app has none)', () => {
+  const app = NgwaItemSchema.parse({ ...ITEM, placements: [], engines: [] });
+  assert.deepEqual(app.placements, []);
+});
+
+test('Ngwa: placement present:false on an enabled item parses (the orphan case)', () => {
+  const orphan = NgwaItemSchema.parse({
+    ...ITEM,
+    state: 'enabled',
+    placements: [{ ...PLACEMENT, present: false, link_target: null, format: null }],
+  });
+  assert.equal(orphan.placements[0]?.present, false);
+  assert.equal(orphan.placements[0]?.format, null);
+});

package/src/ngwa.ts

@@ -0,0 +1,262 @@
+// Ngwa — the unified "installed thing" item, frozen as gate G-NGWA-ITEM
+// (`plans/shell-ux-rearchitecture/drafts/ngwa-item.md` §2, Round 11).
+//
+// One `NgwaItem` joins five subsystems that no command joins today: the pkg
+// kernel (`InstalledSummary`), the Ọba Claude-asset store (`ClaudeStoreEntry`),
+// the engine-config scan (`claude_config.rs`), the `engine_assets` registry,
+// and trust (`pkg/trust.rs` + `commands/pkg_trust.rs`). None of the five is a
+// superset of another, so this type is a join, not a rename of any one of them.
+//
+// Producer: the Rust `ngwa_snapshot` command (WP-14). Consumers: WP-15
+// installed+store, WP-16 scopes+health, WP-17 item detail, WP-18 trust sheet.
+//
+// KEY CASING IS `snake_case`, deliberately. The producer is a Rust command
+// whose neighbouring struct (`InstalledSummary`) serializes with serde defaults
+// and no renames; Ọba's camelCase renames are the exception in this codebase,
+// not the rule, and matching serde defaults keeps `ngwa_snapshot` free of a
+// rename attribute per field.
+//
+// The draft is FROZEN: any change to the shape below needs a new round in
+// `04-discussion.md`, not an edit here.
+
+import { z } from 'zod';
+
+// ── Kind ──────────────────────────────────────────────────────────────────
+
+/** Eleven kinds — two more than D-02's locked Kind facet. `bundle` and
+ *  `sidecar` are real in the code (`Kind::Bundle`, `SidecarSpec`) and reachable
+ *  through *More filters*; `workflow` has no producer in Phase 2 (Phase 4 /
+ *  G-MANIFEST-V5) but stays in the union so adding one is not a contract break.
+ *  `project` and `artifact` from the older `ngwa-surface.html` are NOT here —
+ *  neither is in the locked facet list and neither has a producer. */
+export const NGWA_KINDS = [
+  'app', 'engine', 'tool', 'sidecar',        // from the pkg kernel
+  'skill', 'agent', 'command', 'hook',       // from Ọba + the engine-config scan
+  'bundle',                                  // Ọba bundle, or a pkg that only pulls requires[]
+  'schedule',                                // manifest cron[]
+  'workflow',                                // Phase 4 — no producer in Phase 2
+] as const;
+export const NgwaKindSchema = z.enum(NGWA_KINDS);
+export type NgwaKind = (typeof NGWA_KINDS)[number];
+
+// ── Scope ─────────────────────────────────────────────────────────────────
+
+/** `personal` is the kernel's `project_id: null` and Ọba's `workspace`. */
+export const NgwaScopeSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('personal') }),
+  z.object({ kind: z.literal('project'), project_id: z.string() }),
+]);
+export type NgwaScope = z.infer<typeof NgwaScopeSchema>;
+
+// ── Source (provenance) ───────────────────────────────────────────────────
+
+/** The union of the kernel's `InstallSource` (`builtin`/`registry`/`local`/
+ *  `dev`) and Ọba's `ProvenanceSource` (`local`/`git`/`npx`/`catalog`). */
+export const NGWA_SOURCES = [
+  'builtin', 'registry', 'git', 'npx', 'local', 'dev',
+  'catalog',   // deprecated Ọba back-compat only (claude_store.rs:94-109)
+] as const;
+export const NgwaSourceSchema = z.enum(NGWA_SOURCES);
+export type NgwaSource = z.infer<typeof NgwaSourceSchema>;
+
+/** Provenance. The plan's single `source` string could not hold the url / ref /
+ *  resolved version / publisher both provenance records carry, so it became an
+ *  object; `origin.source` is the facet value. */
+export const NgwaOriginSchema = z.object({
+  source: NgwaSourceSchema,
+  /** registry url | git remote | npm spec */
+  url: z.string().nullable(),
+  /** git ref */
+  ref: z.string().nullable(),
+  /** git SHA | npm version */
+  resolved_version: z.string().nullable(),
+  /** `InstallSource::Registry.publisher_key`, or catalog publisher */
+  publisher: z.string().nullable(),
+  /** vault-owned and deletable (Ọba `managed`) */
+  managed: z.boolean(),
+  auto_update: z.boolean(),
+  installed_at_ms: z.number().nullable(),
+  updated_at_ms: z.number().nullable(),
+});
+export type NgwaOrigin = z.infer<typeof NgwaOriginSchema>;
+
+// ── State ─────────────────────────────────────────────────────────────────
+
+export const NGWA_STATES = [
+  'enabled', 'disabled', 'available', 'update', 'orphaned', 'broken',
+] as const;
+export const NgwaStateSchema = z.enum(NGWA_STATES);
+export type NgwaState = z.infer<typeof NgwaStateSchema>;
+
+/** Live supervisor state. Only long-lived sidecars / MCP servers have one.
+ *  Read from `sidecar_supervisor` directly — `PkgRowV2.state` never does, which
+ *  is drift §10.5 that this type fixes for the new surface. */
+export const NgwaRuntimeSchema = z.object({
+  state: z.enum([
+    'spawning', 'running', 'crashed', 'blocked', 'parked', 'stopped', 'shuttingdown',
+  ]),
+  pid: z.number().nullable(),
+  uptime_s: z.number().nullable(),
+  restarts: z.number(),
+  last_err: z.string().nullable(),
+  last_crash_ms: z.number().nullable(),
+});
+export type NgwaRuntime = z.infer<typeof NgwaRuntimeSchema>;
+
+// ── Trust ─────────────────────────────────────────────────────────────────
+
+/** The four sorted permission lists the trust snapshot hash is taken over
+ *  (`trust.rs:61-67`, `159-182`). All-or-nothing: no per-permission row exists
+ *  anywhere, which is the constraint WP-18 inherits. */
+export const NgwaPermsSummarySchema = z.object({
+  shell_execute: z.array(z.string()),
+  fs_write_outside_sandbox: z.array(z.string()),
+  net: z.array(z.string()),
+  vault_keys: z.array(z.string()),
+});
+export type NgwaPermsSummary = z.infer<typeof NgwaPermsSummarySchema>;
+
+/** Two distinct trust systems exist and must not be conflated: `pkg/trust.rs`
+ *  is the per-call sensitive-permission gate (`state`), `commands/pkg_trust.rs`
+ *  is the separate boot-time capability-diff review (`review_pending`). The
+ *  D-02 facet values are derived, not read off one enum:
+ *  `builtin` ← `auto_trusted`; `signed` ← `signed`; `unsigned` ← `!signed &&
+ *  state !== 'needs_approval'`; `review` ← `state === 'needs_approval' ||
+ *  review_pending`. Ọba primitives get `state: 'not_applicable'`, `perms: null`
+ *  — a skill declares intent and is never granted anything. */
+export const NgwaTrustSchema = z.object({
+  /** Mirrors PkgTrustState; 'not_applicable' for everything that is not a pkg. */
+  state: z.enum([
+    'auto_trusted', 'auto_granted', 'granted', 'needs_approval', 'not_applicable',
+  ]),
+  /** manifest `signature` present, or minisign-verified catalog entry */
+  signed: z.boolean(),
+  /** provenance-trusted (builtin / dev) */
+  auto_trusted: z.boolean(),
+  /** a TrustReview row is waiting (pkg_trust.rs) */
+  review_pending: z.boolean(),
+  /** null when state is 'not_applicable' */
+  perms: NgwaPermsSummarySchema.nullable(),
+  last_granted_at_ms: z.number().nullable(),
+});
+export type NgwaTrust = z.infer<typeof NgwaTrustSchema>;
+
+// ── Placement ─────────────────────────────────────────────────────────────
+
+/** The real per-instance placement record, sourced primarily from the
+ *  `claude_config` scan; `engine_assets` is a second contributor that marks a
+ *  placement `managed_by: 'pkg'`. `present === false` on an `enabled` item is
+ *  the orphan case WP-16 Health reports. */
+export const NgwaPlacementSchema = z.object({
+  /** 'claude' | 'gemini' | 'codex' | ... */
+  engine: z.string(),
+  scope: NgwaScopeSchema,
+  path: z.string(),
+  mechanism: z.enum(['symlink-dir', 'file', 'settings-key']),
+  /** the target actually exists on disk */
+  present: z.boolean(),
+  link_target: z.string().nullable(),
+  /** the link resolves into the Ọba store */
+  in_store: z.boolean(),
+  managed_by: z.enum(['oba', 'pkg', 'user']),
+  /** path of the placement that shadows this one */
+  overridden_by: z.string().nullable(),
+  format: z.enum(['md-yaml', 'toml', 'json-embedded']).nullable(),
+  status: z.enum(['active', 'deprecated']),
+});
+export type NgwaPlacement = z.infer<typeof NgwaPlacementSchema>;
+
+// ── Usage ─────────────────────────────────────────────────────────────────
+
+/** null on the item means "never measured" and MUST render as "—", never as 0
+ *  (designs/frame-workbench-v4.html:2679 — "anything not measured reads —").
+ *  Phase 2 sources this from transcript JSONL (DEC-24); `'hooks'` stays a legal
+ *  value so a later increment can add it — principally for `hook` rows, which
+ *  the transcript cannot see at all — without reopening the gate. */
+export const NgwaUsageSchema = z.object({
+  source: z.enum(['hooks', 'transcript']),
+  last_used_ms: z.number().nullable(),
+  count_7d: z.number().nullable(),
+  count_30d: z.number().nullable(),
+  /** null when the chosen source carries no tokens */
+  tokens_30d: z.number().nullable(),
+  /** Earliest moment the source can see. Anything before it is unknown, not zero. */
+  window_start_ms: z.number(),
+});
+export type NgwaUsage = z.infer<typeof NgwaUsageSchema>;
+
+// ── Dependency edges ──────────────────────────────────────────────────────
+
+export const NgwaRefSchema = z.object({
+  /** open, mirroring RequiresEntry.kind (manifest.rs:177-192) */
+  kind: z.union([NgwaKindSchema, z.string()]),
+  name: z.string(),
+  /** resolved NgwaItem.id, or null if unresolved */
+  item_id: z.string().nullable(),
+  source: NgwaSourceSchema.nullable(),
+  ref: z.string().nullable(),
+});
+export type NgwaRef = z.infer<typeof NgwaRefSchema>;
+
+// ── The item ──────────────────────────────────────────────────────────────
+
+export const NgwaItemSchema = z.object({
+  /** Stable across a refresh. Pkg-backed: the manifest id. Everything else:
+   *  `${kind}:${scope_key}:${name}` where scope_key is 'personal' | `project:<id>`. */
+  id: z.string(),
+  kind: NgwaKindSchema,
+  /** the on-disk / manifest name (stable, used for joins) */
+  name: z.string(),
+  /** manifest `name`, else `name` */
+  display_name: z.string(),
+  description: z.string().nullable(),
+  /** null for Ọba primitives with no resolved version */
+  version: z.string().nullable(),
+  /** registry index only; null otherwise */
+  latest_version: z.string().nullable(),
+  scope: NgwaScopeSchema,
+  origin: NgwaOriginSchema,
+  state: NgwaStateSchema,
+  runtime: NgwaRuntimeSchema.nullable(),
+  trust: NgwaTrustSchema,
+  /** An item with no placements is not an error: a pkg app has none. */
+  placements: z.array(NgwaPlacementSchema),
+  /** null = unmeasured. A measured zero is `{ count_7d: 0, … }`; the UI must
+   *  distinguish them. */
+  usage: NgwaUsageSchema.nullable(),
+  requires: z.array(NgwaRefSchema),
+  /** Computed per snapshot by inverting `requires[]`, never stored — Ọba
+   *  deliberately does not persist the reverse graph (claude_store.rs:120-122). */
+  required_by: z.array(NgwaRefSchema),
+  /** The pkg that contributed this item, when it is not itself a pkg. */
+  owner_pkg_id: z.string().nullable(),
+  install_path: z.string().nullable(),
+  /** Engines this item is placed in, derived from placements[]. Facet source. */
+  engines: z.array(z.string()),
+});
+export type NgwaItem = z.infer<typeof NgwaItemSchema>;
+
+/** Per-source health entry, so the UI can say "Ọba unreadable" instead of
+ *  silently rendering "no skills". */
+export const NgwaSourceHealthSchema = z.object({
+  ok: z.boolean(),
+  error: z.string().nullable(),
+  count: z.number(),
+});
+export type NgwaSourceHealth = z.infer<typeof NgwaSourceHealthSchema>;
+
+export const NgwaSnapshotSchema = z.object({
+  /** `id` is unique within a snapshot; WP-14 asserts uniqueness. */
+  items: z.array(NgwaItemSchema),
+  as_of_ms: z.number(),
+  /** Per-source health, so the UI can say "Ọba unreadable" instead of "no skills". */
+  sources: z.object({
+    kernel: NgwaSourceHealthSchema,
+    oba: NgwaSourceHealthSchema,
+    engine_config: NgwaSourceHealthSchema,
+    engine_assets: NgwaSourceHealthSchema,
+    trust: NgwaSourceHealthSchema,
+    usage: NgwaSourceHealthSchema,
+  }),
+});
+export type NgwaSnapshot = z.infer<typeof NgwaSnapshotSchema>;