@consiliency/agent-board-schema 1.2.0

package/src/tooling.test.mjs

@@ -0,0 +1,97 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadManifest, loadOrderedMigrations, sha256 } from './index.js';
+import { materialize } from './materialize.js';
+import { plan } from './plan.js';
+import { check, EXIT } from './check.js';
+
+const manifest = loadManifest();
+const ordered = loadOrderedMigrations();
+const tmps = [];
+const mktmp = () => {
+  const d = mkdtempSync(join(tmpdir(), 'abs-test-'));
+  tmps.push(d);
+  return d;
+};
+afterEach(() => {
+  while (tmps.length) rmSync(tmps.pop(), { recursive: true, force: true });
+});
+
+const historyExact = () => ({ applied: ordered.map((m) => ({ id: m.id, sha256: m.sha256 })) });
+const union = () => ordered.filter((m) => m.origin !== 'message-board-forward');
+
+describe('manifest integrity', () => {
+  it('aggregate digest matches recomputation over ordered per-file digests', () => {
+    const agg = sha256(Buffer.from(ordered.map((e) => `${e.order} ${e.id} ${e.sha256}`).join('\n')));
+    expect(agg).toBe(manifest.aggregateSha256);
+  });
+  it('every ordered migration file matches its manifest digest (immutable bytes)', () => {
+    for (const m of ordered) expect(sha256(m.bytes)).toBe(m.sha256);
+  });
+  it('records source refs, schema version, and min client version', () => {
+    expect(manifest.source.portalBaseline).toMatch(/^[0-9a-f]{40}$/);
+    expect(manifest.source.laneHead).toMatch(/^[0-9a-f]{40}$/);
+    expect(manifest.source.mergeBase).toMatch(/^[0-9a-f]{40}$/);
+    expect(manifest.schemaVersion).toBe(7);
+    expect(manifest.minClientVersion).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+});
+
+describe('materialize (sole adopter path)', () => {
+  it('writes original bytes with a provenance marker; byte-exact + idempotent', () => {
+    const t = mktmp();
+    materialize(t);
+    const files = readdirSync(t).filter((f) => f.endsWith('.sql'));
+    expect(files.length).toBe(ordered.length);
+    for (const m of ordered) {
+      const written = readFileSync(join(t, m.filename), 'utf8');
+      expect(written.startsWith('-- @agent-board-schema:materialized')).toBe(true);
+      const original = written.slice(written.indexOf('\n') + 1);
+      expect(sha256(Buffer.from(original))).toBe(m.sha256);
+    }
+    // receipt present
+    const receipt = JSON.parse(readFileSync(join(t, '.agent-board-schema-materialize-receipt.json'), 'utf8'));
+    expect(receipt.orderedIds.length).toBe(ordered.length);
+    // idempotent
+    expect(() => materialize(t)).not.toThrow();
+  });
+  it('refuses to overwrite a manual difference', () => {
+    const t = mktmp();
+    materialize(t);
+    const victim = join(t, ordered[0].filename);
+    writeFileSync(victim, '-- @agent-board-schema:materialized 1.1.0 x y\nSELECT 1; -- tampered\n');
+    expect(() => materialize(t)).toThrow(/manual difference/);
+  });
+});
+
+describe('plan / check postures + exit codes (SemVer contract)', () => {
+  it('exact when the closed set is fully applied', () => {
+    expect(plan(historyExact()).posture).toBe('exact');
+    const c = check(historyExact());
+    expect(c.posture).toBe('exact');
+    expect(c.exitCode).toBe(0);
+  });
+  it('behind when the endpoint forward migration is pending', () => {
+    const p = plan({ applied: union().map((m) => ({ id: m.id, sha256: m.sha256 })) });
+    expect(p.posture).toBe('behind');
+    expect(p.perId.filter((r) => r.action === 'pending').map((r) => r.id)).toContain(
+      '20260712000000_agent_board_bundle_endpoint_compat',
+    );
+    expect(check({ applied: union().map((m) => ({ id: m.id, sha256: m.sha256 })) }).exitCode).toBe(10);
+  });
+  it('divergent when an applied digest mismatches', () => {
+    const applied = ordered.map((m, i) => (i === 3 ? { id: m.id, sha256: 'deadbeef' } : { id: m.id, sha256: m.sha256 }));
+    expect(check({ applied }).posture).toBe('divergent');
+    expect(check({ applied }).exitCode).toBe(12);
+  });
+  it('ahead when the adopter has an extra migration and nothing pending', () => {
+    const applied = [...historyExact().applied, { id: '99999999999999_extra', sha256: 'ff' }];
+    expect(check({ applied }).posture).toBe('ahead');
+    expect(check({ applied }).exitCode).toBe(11);
+  });
+  it('exit-code map is a frozen SemVer surface', () => {
+    expect(EXIT).toEqual({ exact: 0, behind: 10, ahead: 11, divergent: 12, error: 13 });
+  });
+});

package/tests/agent_board_addressing.test.sql

@@ -0,0 +1,166 @@
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(8);
+
+create temp table _addressing_fixture (
+  actor uuid,
+  worker uuid,
+  reviewer uuid,
+  human uuid,
+  board_id uuid,
+  thread_id uuid
+) on commit drop;
+grant all on table _addressing_fixture to authenticated, service_role;
+
+do $$
+declare
+  v_suffix text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_actor uuid := gen_random_uuid();
+  v_worker uuid := gen_random_uuid();
+  v_reviewer uuid := gen_random_uuid();
+  v_human uuid := gen_random_uuid();
+  v_thread uuid := gen_random_uuid();
+  v_board uuid;
+begin
+  insert into agent_board.agents(id, agent_type, kind, handle, display_name, status, metadata)
+  values
+    (v_actor, 'agent', 'agent', 'addressing-actor-' || v_suffix, 'ADDRESSING Actor', 'active', '{"role":"phase_worker","groupAliases":["ops"]}'::jsonb),
+    (v_worker, 'agent', 'agent', 'addressing-worker-' || v_suffix, 'ADDRESSING Worker', 'active', '{"role":"phase_worker","groupAliases":["ops"]}'::jsonb),
+    (v_reviewer, 'agent', 'agent', 'addressing-reviewer-' || v_suffix, 'ADDRESSING Reviewer', 'active', '{"roles":["reviewer"],"groupAliases":["review"]}'::jsonb),
+    (v_human, 'human', 'human', 'addressing-human-' || v_suffix, 'ADDRESSING Human', 'active', '{}'::jsonb);
+
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject)
+  values (v_thread, 'coordination', v_actor, 'ADDRESSING thread');
+
+  select board_id into v_board
+    from agent_board.create_board(v_actor, 'addressing-board-' || v_suffix, 'ADDRESSING Board', 'addressing test board', '{}'::jsonb, 'open');
+  perform agent_board.join_board(v_board, v_actor, 'joined', v_actor, '{}'::jsonb);
+  perform agent_board.join_board(v_board, v_worker, 'subscribed', v_actor, '{}'::jsonb);
+
+  insert into _addressing_fixture(actor, worker, reviewer, human, board_id, thread_id)
+  values (v_actor, v_worker, v_reviewer, v_human, v_board, v_thread);
+end
+$$;
+
+select is(
+  jsonb_array_length(r."resolvedRecipients"),
+  2,
+  'group alias and duplicate explicit recipient collapse to two canonical recipients'
+)
+from agent_board.resolve_recipients(
+  (select actor from _addressing_fixture),
+  jsonb_build_array(
+    jsonb_build_object('kind', 'group_alias', 'groupAlias', 'ops'),
+    jsonb_build_object('kind', 'agent_id', 'agentId', (select worker::text from _addressing_fixture))
+  )
+) r;
+
+select is(
+  jsonb_array_length(r."deniedRecipients"),
+  1,
+  'unknown handles are reported deterministically'
+)
+from agent_board.expand_recipients_dry_run(
+  (select actor from _addressing_fixture),
+  '[{"kind":"agent_handle","handle":"missing-addressing-agent"}]'::jsonb,
+  'addressing-thread-key'
+) r;
+
+select ok(
+  (select not r."idempotentThreadReuse"
+     from agent_board.expand_recipients_dry_run(
+       (select actor from _addressing_fixture),
+       jsonb_build_array(jsonb_build_object('kind', 'agent_id', 'agentId', (select worker::text from _addressing_fixture))),
+       'addressing-thread-key'
+     ) r),
+  'dry run does not create idempotent threads'
+);
+
+select ok(
+  (select reused = false
+     from agent_board.create_or_find_thread(
+       (select actor from _addressing_fixture),
+       'ADDRESSING create or find',
+       'addressing-thread-key',
+       'coordination',
+       '{}'::jsonb
+     )),
+  'first create_or_find_thread call creates the thread'
+);
+
+select ok(
+  (select reused = true
+     from agent_board.create_or_find_thread(
+       (select actor from _addressing_fixture),
+       'ADDRESSING create or find',
+       'addressing-thread-key',
+       'coordination',
+       '{}'::jsonb
+     )),
+  'second create_or_find_thread call reuses the thread'
+);
+
+select lives_ok(
+  $$
+    select *
+      from agent_board.send_direct_message(
+        (select thread_id from _addressing_fixture),
+        (select actor from _addressing_fixture),
+        jsonb_build_object('kind', 'agent_handle', 'handle', (select handle from agent_board.agents where id = (select worker from _addressing_fixture))),
+        'addressing_v1',
+        'Addressed direct',
+        'Addressed direct body',
+        'comment',
+        'medium',
+        'addressing-direct',
+        '{}'::jsonb
+      )
+  $$,
+  'send_direct_message accepts an agent handle descriptor'
+);
+
+select lives_ok(
+  $$
+    select *
+      from agent_board.post_board_message(
+        (select thread_id from _addressing_fixture),
+        (select actor from _addressing_fixture),
+        (select slug from agent_board.boards where id = (select board_id from _addressing_fixture)),
+        'addressing_v1',
+        'Addressed board',
+        'Addressed board body',
+        'comment',
+        'medium',
+        'addressing-board-post',
+        '{}'::jsonb
+      )
+  $$,
+  'post_board_message accepts board slug while preserving board-post RPC checks'
+);
+
+select throws_ok(
+  $$
+    select *
+      from agent_board.send_direct_message(
+        (select thread_id from _addressing_fixture),
+        (select actor from _addressing_fixture),
+        '{"kind":"role_selector","role":"phase_worker"}'::jsonb,
+        'addressing_v1',
+        'Ambiguous direct',
+        'Direct role should resolve more than one recipient',
+        'comment',
+        'medium',
+        'addressing-direct-role',
+        '{}'::jsonb
+      )
+  $$,
+  '22023',
+  null,
+  'direct send rejects descriptors that expand to more than one recipient'
+);
+
+select * from finish();
+rollback;

package/tests/agent_board_auth_rls.test.sql

@@ -0,0 +1,243 @@
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(4);
+
+select has_table('agent_board', 'inbox_items', 'inbox_items table exists for auth RLS checks');
+select has_table('agent_board', 'callback_endpoints', 'callback_endpoints table exists for auth RLS checks');
+
+create temp table _agent_board_authrls_fixture (
+  user_a uuid,
+  user_b uuid,
+  agent_a uuid,
+  agent_b uuid,
+  board_a uuid
+) on commit drop;
+
+grant all on table _agent_board_authrls_fixture to authenticated, service_role;
+
+do $$
+declare
+  v_suffix text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_user_a uuid;
+  v_user_b uuid;
+  v_agent_a uuid := gen_random_uuid();
+  v_agent_b uuid := gen_random_uuid();
+  v_thread_a uuid := gen_random_uuid();
+  v_thread_b uuid := gen_random_uuid();
+  v_message_a uuid := gen_random_uuid();
+  v_message_b uuid := gen_random_uuid();
+  v_task_a uuid := gen_random_uuid();
+  v_task_b uuid := gen_random_uuid();
+  v_board_a uuid := gen_random_uuid();
+  v_board_b uuid := gen_random_uuid();
+  v_recipient_a uuid := gen_random_uuid();
+  v_recipient_b uuid := gen_random_uuid();
+  v_inbox_a uuid := gen_random_uuid();
+  v_inbox_b uuid := gen_random_uuid();
+  v_endpoint_a uuid := gen_random_uuid();
+  v_endpoint_b uuid := gen_random_uuid();
+  v_subscription_a uuid := gen_random_uuid();
+  v_subscription_b uuid := gen_random_uuid();
+  v_outbox_a uuid := gen_random_uuid();
+  v_outbox_b uuid := gen_random_uuid();
+begin
+  v_user_a := public.ensure_github_user(
+    'agent-board-authrls-a-' || v_suffix,
+    'agent-board-authrls-a-' || v_suffix || '@example.test',
+    'agent-board-authrls-a-' || v_suffix,
+    'Agent Board Auth RLS A ' || v_suffix
+  );
+  v_user_b := public.ensure_github_user(
+    'agent-board-authrls-b-' || v_suffix,
+    'agent-board-authrls-b-' || v_suffix || '@example.test',
+    'agent-board-authrls-b-' || v_suffix,
+    'Agent Board Auth RLS B ' || v_suffix
+  );
+
+  insert into agent_board.agents(id, agent_type, kind, handle, display_name, status, auth_user_id, owner_user_id)
+  values
+    (v_agent_a, 'agent', 'agent', 'authrls-a-' || v_suffix, 'Auth RLS Agent A', 'active', v_user_a, v_user_a),
+    (v_agent_b, 'agent', 'agent', 'authrls-b-' || v_suffix, 'Auth RLS Agent B', 'active', v_user_b, v_user_b);
+
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject)
+  values
+    (v_thread_a, 'coordination', v_agent_a, 'Auth RLS Thread A'),
+    (v_thread_b, 'coordination', v_agent_b, 'Auth RLS Thread B');
+
+  insert into agent_board.tasks(id, thread_id, created_by_agent_id, assigned_agent_id, root_task_id, title, priority, orchestration_mode)
+  values
+    (v_task_a, v_thread_a, v_agent_a, v_agent_a, v_task_a, 'Auth RLS Task A', 'medium', 'distributed'),
+    (v_task_b, v_thread_b, v_agent_b, v_agent_b, v_task_b, 'Auth RLS Task B', 'medium', 'distributed');
+
+  insert into agent_board.task_events(task_id, thread_id, actor_agent_id, event_sequence, event_type, payload)
+  values
+    (v_task_a, v_thread_a, v_agent_a, 1, 'created', '{}'::jsonb),
+    (v_task_b, v_thread_b, v_agent_b, 1, 'created', '{}'::jsonb);
+
+  insert into agent_board.messages(id, thread_id, author_agent_id, message_sequence, message_type, body)
+  values
+    (v_message_a, v_thread_a, v_agent_a, 1, 'comment', 'message a'),
+    (v_message_b, v_thread_b, v_agent_b, 1, 'comment', 'message b');
+
+  insert into agent_board.claims(task_id, thread_id, agent_id, resource_kind, resource_key, lease_expires_at)
+  values
+    (v_task_a, v_thread_a, v_agent_a, 'repo_file', 'authrls-a-' || v_suffix, now() + interval '1 hour'),
+    (v_task_b, v_thread_b, v_agent_b, 'repo_file', 'authrls-b-' || v_suffix, now() + interval '1 hour');
+
+  insert into agent_board.boards(id, slug, name, created_by_agent_id)
+  values
+    (v_board_a, 'authrls-board-a-' || v_suffix, 'Auth RLS Board A', v_agent_a),
+    (v_board_b, 'authrls-board-b-' || v_suffix, 'Auth RLS Board B', v_agent_b);
+
+  insert into agent_board.board_memberships(id, board_id, agent_id, membership_state, created_by_agent_id)
+  values
+    (gen_random_uuid(), v_board_a, v_agent_a, 'joined', v_agent_a),
+    (gen_random_uuid(), v_board_b, v_agent_b, 'joined', v_agent_b);
+
+  insert into agent_board.delivery_recipients(id, delivery_mode, recipient_agent_id, source_kind, source_message_id, board_id)
+  values
+    (v_recipient_a, 'direct', v_agent_a, 'message', v_message_a, null),
+    (v_recipient_b, 'direct', v_agent_b, 'message', v_message_b, null);
+
+  insert into agent_board.inbox_items(
+    id,
+    delivery_recipient_id,
+    recipient_agent_id,
+    board_id,
+    delivery_mode,
+    source_kind,
+    source_message_id,
+    subject,
+    preview,
+    priority,
+    action_state,
+    visible_in_inbox,
+    visible_in_board_feed,
+    fetch_descriptor
+  )
+  values
+    (
+      v_inbox_a,
+      v_recipient_a,
+      v_agent_a,
+      null,
+      'direct',
+      'message',
+      v_message_a,
+      'Inbox A',
+      'Preview A',
+      'medium',
+      'new',
+      true,
+      false,
+      jsonb_build_object('surface', 'thread', 'targetId', v_thread_a::text, 'view', 'agent_board.v_thread_feed', 'filters', jsonb_build_object(), 'reason', 'auth rls a')
+    ),
+    (
+      v_inbox_b,
+      v_recipient_b,
+      v_agent_b,
+      null,
+      'direct',
+      'message',
+      v_message_b,
+      'Inbox B',
+      'Preview B',
+      'medium',
+      'new',
+      true,
+      false,
+      jsonb_build_object('surface', 'thread', 'targetId', v_thread_b::text, 'view', 'agent_board.v_thread_feed', 'filters', jsonb_build_object(), 'reason', 'auth rls b')
+    );
+
+  insert into agent_board.callback_endpoints(id, owner_agent_id, endpoint_url, endpoint_status, verification_requested_at, verified_at)
+  values
+    (v_endpoint_a, v_agent_a, 'https://example.test/authrls-a-' || v_suffix, 'verified', now(), now()),
+    (v_endpoint_b, v_agent_b, 'https://example.test/authrls-b-' || v_suffix, 'verified', now(), now());
+
+  insert into agent_board.callback_subscriptions(id, endpoint_id, agent_id, subscription_scope, event_category, subscription_status)
+  values
+    (v_subscription_a, v_endpoint_a, v_agent_a, 'own_inbox', 'inbox.item.delivered', 'active'),
+    (v_subscription_b, v_endpoint_b, v_agent_b, 'own_inbox', 'inbox.item.delivered', 'active');
+
+  insert into agent_board.callback_outbox_events(
+    id,
+    endpoint_id,
+    subscription_id,
+    recipient_agent_id,
+    inbox_item_id,
+    event_category,
+    delivery_mode,
+    source_kind,
+    source_message_id,
+    idempotency_key,
+    fetch_descriptor
+  )
+  values
+    (v_outbox_a, v_endpoint_a, v_subscription_a, v_agent_a, v_inbox_a, 'inbox.item.delivered', 'direct', 'message', v_message_a, 'outbox-a-' || v_suffix, jsonb_build_object('surface', 'thread', 'targetId', v_thread_a::text, 'view', 'agent_board.v_thread_feed', 'filters', jsonb_build_object(), 'reason', 'auth rls outbox a')),
+    (v_outbox_b, v_endpoint_b, v_subscription_b, v_agent_b, v_inbox_b, 'inbox.item.delivered', 'direct', 'message', v_message_b, 'outbox-b-' || v_suffix, jsonb_build_object('surface', 'thread', 'targetId', v_thread_b::text, 'view', 'agent_board.v_thread_feed', 'filters', jsonb_build_object(), 'reason', 'auth rls outbox b'));
+
+  insert into agent_board.callback_delivery_attempts(outbox_event_id, endpoint_id, attempt_number, attempt_outcome, started_at, finished_at)
+  values
+    (v_outbox_a, v_endpoint_a, 1, 'delivered', now(), now()),
+    (v_outbox_b, v_endpoint_b, 1, 'delivered', now(), now());
+
+  insert into _agent_board_authrls_fixture(user_a, user_b, agent_a, agent_b, board_a)
+  values (v_user_a, v_user_b, v_agent_a, v_agent_b, v_board_a);
+end
+$$;
+
+set local role authenticated;
+select set_config('request.jwt.claim.role', 'authenticated', true);
+
+do $$
+declare
+  v_fixture record;
+  v_inbox_count bigint;
+  v_claim_count bigint;
+  v_board_count bigint;
+  v_endpoint_count bigint;
+begin
+  select * into v_fixture from _agent_board_authrls_fixture;
+  perform set_config('request.jwt.claim.sub', v_fixture.user_a::text, true);
+
+  select count(*) into v_inbox_count from agent_board.v_agent_inbox;
+  if v_inbox_count <> 1 then
+    raise exception 'agent A should see exactly one inbox item, saw %', v_inbox_count;
+  end if;
+
+  if exists (
+    select 1
+      from agent_board.inbox_items ii
+     where ii.recipient_agent_id = v_fixture.agent_b
+  ) then
+    raise exception 'agent A unexpectedly read agent B inbox rows';
+  end if;
+
+  select count(*) into v_claim_count from agent_board.claims;
+  if v_claim_count <> 1 then
+    raise exception 'agent A should see exactly one claim row, saw %', v_claim_count;
+  end if;
+
+  select count(*) into v_board_count
+    from agent_board.v_board_directory
+   where board_id = v_fixture.board_a;
+  if v_board_count <> 1 then
+    raise exception 'agent A should see exactly one joined board, saw %', v_board_count;
+  end if;
+
+  select count(*) into v_endpoint_count from agent_board.callback_endpoints;
+  if v_endpoint_count <> 1 then
+    raise exception 'agent A should see exactly one callback endpoint, saw %', v_endpoint_count;
+  end if;
+end
+$$;
+
+select pass('Authenticated RLS filters inbox, claim, board, and callback rows to the current agent');
+select pass('Authenticated cross-agent reads are denied by current_agent_id-scoped policies');
+
+select finish();
+
+rollback;