@consiliency/agent-board-schema 1.23.0 → 1.25.0

package/tests/fixtures/test-prereqs.sql

@@ -115,3 +115,316 @@ $$;
 REVOKE ALL ON FUNCTION public.test_pubkey(text) FROM PUBLIC;
 REVOKE ALL ON FUNCTION public.test_key_fingerprint(text) FROM PUBLIC;
 GRANT EXECUTE ON FUNCTION public.test_pubkey(text), public.test_key_fingerprint(text) TO service_role;
+
+-- ===========================================================================
+-- Shared SQL source-text strip for pgTAP source assertions
+-- (message-board#196, message-board#199).
+--
+-- WHY THIS EXISTS. A pgTAP assertion that locates a marker in a function body
+-- with `strpos(...)` and compares positions, or that claims a marker is ABSENT
+-- with `!~` / `not like`, reads AUTHOR-CONTROLLED text. Prose that merely
+-- MENTIONS the marker satisfies the assertion while the code does the opposite,
+-- so the guard reports "ordered" / "absent" when it means "my pattern matched
+-- something that is not code". Every mode below was DEMONSTRATED, not reasoned
+-- about; each one left a hardened file fully green with a lock genuinely moved.
+--
+-- ENUMERATED ESCAPE HATCHES, and which of them a regex can close:
+--   1. a `--` comment naming the marker                       -- regex can
+--   2. a block comment whose body ends in `*` (`/* … **/`)     -- regex can
+--   3. a string literal naming the marker, incl. a dollar-quoted
+--      one; a naive two-pass scanner also DESYNCS on an odd
+--      apostrophe count (`mark_retention_metadata`'s $retention$
+--      block survives one today only because its 64 apostrophes
+--      happen to be an even number)                            -- regex can
+--   4. a NESTED block comment (message-board#199). Postgres block
+--      comments NEST; `/* note /* x */ <code> */` hides <code>
+--      from any regex that stops at the first `*/`             -- REGEX CANNOT
+--   5. an apostrophe inside a "quoted identifier"; a regex whose
+--      literal alternative does not know about `"…"` desyncs on
+--      it exactly as (3) desyncs                               -- regex cannot
+--
+-- (4) is why this is a character scanner and not a cleverer regular expression.
+-- Postgres' regex engine has no recursion, so no regular expression can match a
+-- nested block comment: the language is not regular. Rejecting nested comments
+-- instead of handling them was considered (message-board#199 suggests it) and
+-- not taken -- a scanner that handles nesting is exact, is unit-testable
+-- (agent_board_source_strip_helper.test.sql), and does not have to guess which
+-- constructs are "legitimate".
+--
+-- ONE PASS, NOT TWO. Comments-first eats a literal containing `--`;
+-- literals-first eats a comment containing an apostrophe. This scanner consumes
+-- whichever token OPENS first, which is the correct tokenization and the only
+-- one that cannot desync.
+--
+-- FAIL CLOSED. An unterminated comment, literal, dollar quote or quoted
+-- identifier raises rather than returning a truncated body, so the failure is
+-- loud instead of a silently short string that every `!~` passes.
+--
+-- MODES. `p_keep_literals => false` (the default) is the safe one and is what a
+-- positional or negative assertion should use. `p_keep_literals => true` keeps
+-- string literals -- required ONLY where the MARKER ITSELF IS A LITERAL (e.g.
+-- an assertion locating a `raise exception '<message>'`), because stripping the
+-- literals there would make the assertion vacuously true forever. Literals are
+-- still CONSUMED in that mode, so a `--` or `/*` inside one cannot be mistaken
+-- for a comment opener. This choice is NOT machine-checkable -- the lint in
+-- scripts/run-agent-board-schema-tests.sh cannot tell a message anchor from a
+-- code anchor -- so every `p_keep_literals => true` call site carries an inline
+-- justification.
+-- ===========================================================================
+CREATE SCHEMA IF NOT EXISTS agent_board_test;
+
+CREATE OR REPLACE FUNCTION agent_board_test.strip_sql(
+  p_text          text,
+  p_keep_literals boolean DEFAULT false
+) RETURNS text
+LANGUAGE plpgsql
+IMMUTABLE
+SET search_path = pg_catalog
+AS $strip$
+declare
+  c          text[];      -- p_text as characters; array indexing is O(1),
+                          -- substr()-per-character on a multibyte text is not
+  n          int;
+  i          int := 1;
+  span       int := 1;    -- start of the current KEPT run
+  parts      text[] := '{}';
+  depth      int;
+  j          int;
+  tag        text;
+  close_at   int;
+  is_estring boolean;
+begin
+  if p_text is null then
+    return null;
+  end if;
+
+  c := regexp_split_to_array(p_text, '');
+  n := coalesce(array_length(c, 1), 0);
+  if n = 0 then
+    return p_text;
+  end if;
+
+  while i <= n loop
+
+    -- (1) line comment ------------------------------------------------------
+    if c[i] = '-' and i < n and c[i + 1] = '-' then
+      parts := parts || substr(p_text, span, i - span);
+      while i <= n and c[i] <> chr(10) loop
+        i := i + 1;
+      end loop;
+      span := i;   -- the newline itself is code-relevant whitespace; keep it
+
+    -- (2) block comment, WITH NESTING (message-board#199) --------------------
+    elsif c[i] = '/' and i < n and c[i + 1] = '*' then
+      parts := parts || substr(p_text, span, i - span);
+      depth := 1;
+      i := i + 2;
+      while i <= n and depth > 0 loop
+        if c[i] = '/' and i < n and c[i + 1] = '*' then
+          depth := depth + 1; i := i + 2;
+        elsif c[i] = '*' and i < n and c[i + 1] = '/' then
+          depth := depth - 1; i := i + 2;
+        else
+          i := i + 1;
+        end if;
+      end loop;
+      if depth > 0 then
+        raise exception
+          'agent_board_test.strip_sql: unterminated block comment (depth %) -- refusing to return a truncated body',
+          depth;
+      end if;
+      span := i;
+
+    -- (3) quoted identifier: CODE, kept verbatim, but CONSUMED so that an
+    --     apostrophe inside it cannot desync the literal scanner ------------
+    elsif c[i] = '"' then
+      i := i + 1;
+      loop
+        if i > n then
+          raise exception
+            'agent_board_test.strip_sql: unterminated quoted identifier -- refusing to return a truncated body';
+        end if;
+        if c[i] = '"' then
+          if i < n and c[i + 1] = '"' then
+            i := i + 2;          -- doubled quote inside the identifier
+          else
+            i := i + 1; exit;
+          end if;
+        else
+          i := i + 1;
+        end if;
+      end loop;
+
+    -- (4) single-quoted string literal, including the E'' escape form -------
+    elsif c[i] = '''' then
+      -- E'…' only when the E is a standalone prefix, not the tail of an
+      -- identifier (`v_note'…'` is not an escape string).
+      is_estring := i > 1
+                    and upper(c[i - 1]) = 'E'
+                    and (i = 2 or c[i - 2] !~ '[A-Za-z0-9_$]|[^\x00-\x7F]');
+      if not p_keep_literals then
+        -- an E prefix is part of the literal, not of the surrounding code
+        parts := parts || substr(p_text, span, (case when is_estring then i - 1 else i end) - span);
+      end if;
+      i := i + 1;
+      loop
+        if i > n then
+          raise exception
+            'agent_board_test.strip_sql: unterminated string literal -- refusing to return a truncated body';
+        end if;
+        if is_estring and c[i] = '\' then
+          i := i + 2;                          -- backslash escapes one char
+        elsif c[i] = '''' then
+          if i < n and c[i + 1] = '''' then
+            i := i + 2;                        -- doubled quote inside the literal
+          else
+            i := i + 1; exit;
+          end if;
+        else
+          i := i + 1;
+        end if;
+      end loop;
+      if not p_keep_literals then
+        span := i;
+      end if;
+
+    -- (5) dollar-quoted string -----------------------------------------------
+    --
+    -- TWO ways this is NOT a dollar quote, and both swallow live code if missed:
+    --   a. the tag cannot start with a digit -- `$1$` is the parameter $1
+    --      followed by $, not an opener;
+    --   b. PostgreSQL permits `$` INSIDE an unquoted identifier, and the lexer
+    --      consumes it greedily, so `foo$tag$danger$tag$` is ONE identifier.
+    --      A scanner that ignores the preceding character reads `$tag$` as an
+    --      opener and deletes `$tag$danger$tag$` from live code. Verified against
+    --      the server, not assumed: `do $do$ declare foo$tag$danger$tag$ int := 7;
+    --      begin raise notice '%', foo$tag$danger$tag$; end $do$;` runs and prints 7.
+    --   c. the identifier grammar is NOT ASCII. PostgreSQL accepts any letter
+    --      the server encoding recognises in an unquoted identifier AND in a
+    --      dollar-quote tag, so `[A-Za-z0-9_]` (or an \x80-\xff byte range, which
+    --      is wrong for multi-byte UTF-8) misreads both directions: `$Ω$ … $Ω$`
+    --      was left UNSTRIPPED -- a marker could hide in it -- and
+    --      `Ω$tag$danger$tag$` was eaten as if it opened a quote. Both verified
+    --      against the server: `do $do$ begin raise notice '%', $Ω$ hello $Ω$; end $do$;`
+    --      and `do $do$ declare Ω$tag$danger$tag$ int := 7; ... end $do$;` both run.
+    --      The class used here is LOCALE-INDEPENDENT on purpose. `[[:alpha:]]` is
+    --      not: under `C` collation it does NOT match `Ω` (measured:
+    --      `('Ω' collate "C") ~ '[[:alpha:]]'` is FALSE while the default collation
+    --      says true), so a locale-sensitive class makes this scanner -- and the
+    --      whole 49-site claim that rests on it -- pass or fail depending on the
+    --      runner's collation, and diverge from the JS mirror in scripts/.
+    --      For UTF-8 PostgreSQL treats ANY non-ASCII character as an identifier
+    --      character, so `[A-Za-z_]|[^\x00-\x7F]` is both exact and collation-free.
+    elsif c[i] = '$'
+          and (i = 1 or c[i - 1] !~ '[A-Za-z0-9_$]|[^\x00-\x7F]') then
+      j := i + 1;
+      if j <= n and c[j] ~ '[A-Za-z_]|[^\x00-\x7F]' then
+        while j <= n and c[j] ~ '[A-Za-z0-9_]|[^\x00-\x7F]' loop
+          j := j + 1;
+        end loop;
+      end if;
+      if j <= n and c[j] = '$' then
+        tag      := substr(p_text, i, j - i + 1);
+        close_at := position(tag in substr(p_text, j + 1));
+        if close_at = 0 then
+          raise exception
+            'agent_board_test.strip_sql: unterminated dollar-quoted string % -- refusing to return a truncated body',
+            tag;
+        end if;
+        if not p_keep_literals then
+          parts := parts || substr(p_text, span, i - span);
+        end if;
+        i := j + close_at + length(tag);   -- first char after the closing tag
+        if not p_keep_literals then
+          span := i;
+        end if;
+      else
+        i := i + 1;                        -- a bare `$` / `$1`: ordinary code
+      end if;
+
+    else
+      i := i + 1;
+    end if;
+  end loop;
+
+  parts := parts || substr(p_text, span);
+  -- Each stripped token collapses to a single space so token boundaries
+  -- survive: `a/*x*/b` must not become the identifier `ab`.
+  return array_to_string(parts, ' ');
+end;
+$strip$;
+
+COMMENT ON FUNCTION agent_board_test.strip_sql(text, boolean) IS
+  'One-pass character scanner that removes line comments, NESTED block comments and (unless p_keep_literals) string literals from SQL/PL-pgSQL source text. Test-only; see message-board#196 / #199.';
+
+-- The stripped BODY of a function. This is what a positional or negative
+-- assertion should read.
+CREATE OR REPLACE FUNCTION agent_board_test.stripped_body(
+  p_fn            oid,
+  p_keep_literals boolean DEFAULT false
+) RETURNS text
+LANGUAGE sql
+STABLE
+SET search_path = pg_catalog
+AS $$
+  SELECT agent_board_test.strip_sql(p.prosrc, p_keep_literals)
+    FROM pg_proc p
+   WHERE p.oid = p_fn;
+$$;
+
+-- The stripped FULL DEFINITION. The header (`SECURITY DEFINER`, `SET
+-- search_path = …`, the argument list) is regenerated by Postgres from catalog
+-- metadata and cannot carry author prose, so it is left intact -- assertions
+-- that match on it keep working. Only the body is stripped.
+--
+-- Stripping pg_get_functiondef() wholesale would be a self-inflicted wound:
+-- the body is wrapped in a dollar quote (`AS $function$ … $function$`), so a
+-- dollar-quote-aware strip would delete THE ENTIRE BODY and every `!~` over the
+-- result would pass. Splicing avoids that trap by construction.
+CREATE OR REPLACE FUNCTION agent_board_test.stripped_def(
+  p_fn            oid,
+  p_keep_literals boolean DEFAULT false
+) RETURNS text
+LANGUAGE plpgsql
+STABLE
+SET search_path = pg_catalog
+AS $$
+declare
+  v_def  text;
+  v_src  text;
+  v_at   int;
+begin
+  select pg_get_functiondef(p.oid), p.prosrc into v_def, v_src
+    from pg_proc p where p.oid = p_fn;
+  if v_def is null then
+    return null;
+  end if;
+  if v_src is null or v_src = '' then
+    return v_def;
+  end if;
+  v_at := position(v_src in v_def);
+  if v_at = 0 then
+    raise exception
+      'agent_board_test.stripped_def: prosrc not found verbatim inside pg_get_functiondef for oid % -- refusing to guess', p_fn;
+  end if;
+  return substr(v_def, 1, v_at - 1)
+      || agent_board_test.strip_sql(v_src, p_keep_literals)
+      || substr(v_def, v_at + length(v_src));
+end;
+$$;
+
+-- View definitions are REGENERATED by Postgres, so comments are already gone --
+-- but string literals in the select list are not, and a negative assertion over
+-- a view body is maskable by one.
+CREATE OR REPLACE FUNCTION agent_board_test.stripped_viewdef(
+  p_rel           oid,
+  p_keep_literals boolean DEFAULT false
+) RETURNS text
+LANGUAGE sql
+STABLE
+SET search_path = pg_catalog
+AS $$
+  SELECT agent_board_test.strip_sql(pg_get_viewdef(p_rel), p_keep_literals);
+$$;
+
+GRANT USAGE ON SCHEMA agent_board_test TO PUBLIC;

package/tests/isolation/expected/atomic_fleet_lifecycle_races.out

@@ -864,7 +864,7 @@ step retry_onboard:
  <waiting ...>
 step lifecycle_commit: COMMIT;
 step retry_onboard: <... completed>
-ERROR:  enrollment replay conflicts with the frozen identity contract
+ERROR:  this signing key is already enrolled to you as agent "atomic-lifecycle-agent", but that identity is not resumable (its key or agent is inactive or unproven, its stored public key differs, or its enrollment audit records no granted scopes); enrollment need not be repeated; report this handle to an operator
 step retry_commit: COMMIT;
 step check: 
   select a.status as agent_status,
@@ -929,7 +929,7 @@ step retry_onboard:
  <waiting ...>
 step lifecycle_commit: COMMIT;
 step retry_onboard: <... completed>
-ERROR:  enrollment replay conflicts with the frozen identity contract
+ERROR:  this signing key is already enrolled to you as agent "atomic-lifecycle-agent", but that identity is not resumable (its key or agent is inactive or unproven, its stored public key differs, or its enrollment audit records no granted scopes); enrollment need not be repeated; report this handle to an operator
 step retry_commit: COMMIT;
 step check: 
   select a.status as agent_status,
@@ -994,7 +994,7 @@ step retry_onboard:
  <waiting ...>
 step lifecycle_commit: COMMIT;
 step retry_onboard: <... completed>
-ERROR:  enrollment replay conflicts with the frozen identity contract
+ERROR:  this signing key is already enrolled to you as agent "atomic-lifecycle-agent", but that identity is not resumable (its key or agent is inactive or unproven, its stored public key differs, or its enrollment audit records no granted scopes); enrollment need not be repeated; report this handle to an operator
 step retry_commit: COMMIT;
 step check: 
   select a.status as agent_status,