@event4u/agent-config 14.19.0 → 14.21.0

package/src/scripts/_lib/tty_prompt.ts

@@ -0,0 +1,76 @@
+/**
+ * Synchronous terminal prompting for the release pipeline.
+ *
+ * Its own module because `release.ts` sits 371 lines over the 1500-line source
+ * ratchet, where every added line is one unit of excess — and because a SECOND
+ * caller now needs these: `guard_release_curation` in `release_publication.ts`
+ * collects the governance answer it used to only refuse over.
+ *
+ * Extracted verbatim from `release.ts`, where the `/dev/tty` discipline below
+ * was established against a reproduced failure. Do not "simplify" it back to
+ * `readSync(0)`; the comment on `promptLine` says what that costs.
+ */
+import * as fs from 'node:fs';
+import process from 'node:process';
+
+/** Can we prompt at all — is fd 0 a TTY, or is a controlling terminal openable? */
+export function canPrompt(): boolean {
+    if (process.env.CI) return false; // CI is non-interactive by contract → require --yes
+    if (process.stdin.isTTY) return true;
+    try {
+        const fd = fs.openSync('/dev/tty', 'r');
+        fs.closeSync(fd);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Mirror of Python `input(prompt)` — write the prompt, read one line from the
+ * controlling terminal. Returns `null` when no terminal is reachable.
+ *
+ * The answer is ALWAYS read from a freshly opened, blocking `/dev/tty`
+ * (`openSync(..., 'rs')`), NEVER from fd 0. `task release` / `./scripts-run`
+ * run this under go-task's `interactive: true`, which leaves fd 0 a TTY
+ * (`process.stdin.isTTY === true`) but one Node treats as NON-blocking — so a
+ * bare `readSync(0)` throws `EAGAIN`, the catch swallows it, and the `[y/N]`
+ * prompt "auto-aborts" without ever waiting (the exact failure this fixes;
+ * reproduced with `isTTY === true`). A fresh blocking `/dev/tty` descriptor
+ * blocks for real input regardless of how the script was invoked — the proven
+ * synchronous-prompt pattern.
+ */
+export function promptLine(prompt: string): string | null {
+    process.stdout.write(prompt);
+    let fd: number;
+    try {
+        // 'rs' → O_RDONLY | O_SYNC: a fresh, blocking descriptor on the
+        // controlling terminal, unaffected by Node's non-blocking fd 0.
+        fd = fs.openSync('/dev/tty', 'rs');
+    } catch {
+        return null; // no controlling terminal (true non-interactive)
+    }
+    try {
+        const buf = Buffer.alloc(1);
+        const chars: number[] = [];
+        for (;;) {
+            let bytesRead: number;
+            try {
+                bytesRead = fs.readSync(fd, buf, 0, 1, null);
+            } catch (e) {
+                const code = (e as NodeJS.ErrnoException).code;
+                // A blocking /dev/tty should not yield these, but inherited
+                // descriptor flags can — retry rather than abort the prompt.
+                if (code === 'EAGAIN' || code === 'EINTR') continue;
+                break; // EOF / EIO → EOFError analogue; return what we have.
+            }
+            if (bytesRead === 0) break;
+            const b = buf[0] as number;
+            if (b === 0x0a) break; // newline terminates the line (stripped, like input()).
+            chars.push(b);
+        }
+        return Buffer.from(chars).toString('utf-8');
+    } finally {
+        fs.closeSync(fd);
+    }
+}

package/src/scripts/ai_council/api_transport.ts

@@ -0,0 +1,163 @@
+/**
+ * The council's synchronous HTTP transport, and the per-provider shims that
+ * turn it into the SDK-shaped callables `clients.ts::ask()` reads.
+ *
+ * Extracted from `clients.ts` (road-to-admissible-council-seats 1.1). Two
+ * reasons, and only the first is about tidiness:
+ *
+ * 1. `clients.ts` is ~1,370 lines past the 1,500-line ceiling
+ *    `check_source_size_budget` ratchets, so every line added there costs one
+ *    excess line. The three shims below are new code; putting them in a file
+ *    UNDER the ceiling is what lets 1.1 land without raising a baseline.
+ * 2. Before 1.1 exactly one provider (OpenAI) had a live transport and the
+ *    other four constructors threw `… package not installed. pip install …`
+ *    after the api-key check — so `mode: api` was dead for gemini, xai and
+ *    perplexity. A shared shim module is the honest home for "how this
+ *    package actually reaches a provider over HTTP", rather than four
+ *    copies of the same curl call inside four constructors.
+ *
+ * The injectable seam. Every shim takes a `JsonPost` rather than calling `curlJsonPost` directly.
+ * A test can then construct a REAL client with a REAL api_key — exercising
+ * the shim-building path a mock `client:` object skips entirely — and still
+ * make no network call. That is the difference between testing the transport
+ * and testing around it.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+/** The one network primitive. Swappable so tests never reach the network. */
+export type JsonPost = (url: string, extraHeaders: string[], body: unknown) => unknown;
+
+export const GEMINI_BASE_URL = 'https://generativelanguage.googleapis.com/v1beta';
+
+/**
+ * Synchronous JSON POST via `curl` (no Node SDK, no Python). Matches the
+ * council's `spawnSync` transport model so the live-call clients stay
+ * synchronous. Returns the parsed response JSON (the provider HTTP APIs return
+ * exactly the SDK response shape `ask()` reads). Throws on transport failure or
+ * a non-2xx status so `ask()`'s catch surfaces it as a member error.
+ */
+export function curlJsonPost(url: string, extraHeaders: string[], body: unknown): unknown {
+    const args = ['-sS', '-X', 'POST', url, '-H', 'content-type: application/json'];
+    for (const h of extraHeaders) {
+        args.push('-H', h);
+    }
+    // `--connect-timeout` fast-fails a dead host; `--max-time` lets curl abort
+    // itself cleanly (surfacing a real `curl exited` error with stderr) ~10s
+    // before the `spawnSync` timeout would kill it with an opaque ETIMEDOUT.
+    // A full 16k-token generation legitimately runs several minutes, so the
+    // ceiling is 300s, not 120s (the old value timed out long Anthropic calls).
+    args.push('--connect-timeout', '30', '--max-time', '290');
+    args.push('-w', '\n%{http_code}', '--data-binary', '@-');
+    const r = spawnSync('curl', args, {
+        input: JSON.stringify(body),
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+        timeout: 300_000,
+    });
+    if (r.error) {
+        throw new Error(`curl spawn failed: ${(r.error as Error).message}`);
+    }
+    if (r.status !== 0) {
+        throw new Error(
+            `curl exited ${r.status ?? 'null'}: ${(r.stderr ?? '').toString().slice(0, 500)}`,
+        );
+    }
+    const out = (r.stdout ?? '').toString();
+    const nl = out.lastIndexOf('\n');
+    const httpCode = (nl >= 0 ? out.slice(nl + 1) : out).trim();
+    const bodyText = nl >= 0 ? out.slice(0, nl) : out;
+    if (!/^2\d\d$/.test(httpCode)) {
+        throw new Error(`HTTP ${httpCode}: ${bodyText.slice(0, 500)}`);
+    }
+    return JSON.parse(bodyText);
+}
+
+/**
+ * `chat.completions.create` over any OpenAI-compatible `/v1/chat/completions`.
+ * Used by OpenAI itself and by the two OpenAI-compatible vendors (xAI,
+ * Perplexity), whose only difference is the base URL.
+ *
+ * `baseUrl` is passed rather than read off `this.base_url`: a subclass field
+ * initializer (`override base_url = XAI_BASE_URL`) runs AFTER the base
+ * constructor, so reading the field during construction would silently build
+ * every compatible client against the empty string.
+ */
+export function openAiCompatibleClient(
+    baseUrl: string,
+    apiKey: string,
+    post: JsonPost = curlJsonPost,
+): unknown {
+    const url = `${baseUrl.replace(/\/+$/, '')}/chat/completions`;
+    return {
+        chat: {
+            completions: {
+                create: (kwargs: Record<string, unknown>): unknown =>
+                    post(url, [`authorization: Bearer ${apiKey}`], kwargs),
+            },
+        },
+    };
+}
+
+/**
+ * `models.generate_content` over the Gemini REST API, normalised to the
+ * `google-genai` SDK response shape `GeminiClient.ask()` reads.
+ *
+ * The normalisation is the whole point and is not cosmetic: REST answers with
+ * `candidates[0].content.parts[*].text` and `usageMetadata.promptTokenCount`,
+ * while `ask()` reads `.text`, `.model_version` and
+ * `.usage_metadata.{prompt_token_count, candidates_token_count}`. Rewriting
+ * `ask()` to read REST instead would break every injected SDK-shaped mock in
+ * the existing tests, so the adapter lives here, at the transport boundary,
+ * where a shape mismatch is a transport concern.
+ */
+export function geminiRestClient(
+    apiKey: string,
+    post: JsonPost = curlJsonPost,
+    baseUrl: string = GEMINI_BASE_URL,
+): unknown {
+    return {
+        models: {
+            generate_content: (kwargs: Record<string, unknown>): unknown => {
+                const model = String(kwargs['model'] ?? '');
+                const cfg = (kwargs['config'] ?? {}) as Record<string, unknown>;
+                const url = `${baseUrl.replace(/\/+$/, '')}/models/${model}:generateContent`;
+                const raw = post(
+                    url,
+                    [`x-goog-api-key: ${apiKey}`],
+                    {
+                        contents: [{ role: 'user', parts: [{ text: String(kwargs['contents'] ?? '') }] }],
+                        generationConfig: { maxOutputTokens: cfg['max_output_tokens'] ?? null },
+                    },
+                );
+                return normaliseGeminiRest(raw);
+            },
+        },
+    };
+}
+
+/** REST envelope → the `google-genai` SDK response shape. Exported for tests. */
+export function normaliseGeminiRest(raw: unknown): {
+    text: string;
+    model_version: string;
+    usage_metadata: { prompt_token_count: number; candidates_token_count: number };
+} {
+    const env = (raw ?? {}) as Record<string, unknown>;
+    const candidates = Array.isArray(env['candidates']) ? (env['candidates'] as unknown[]) : [];
+    const first = (candidates[0] ?? {}) as Record<string, unknown>;
+    const content = (first['content'] ?? {}) as Record<string, unknown>;
+    const parts = Array.isArray(content['parts']) ? (content['parts'] as unknown[]) : [];
+    const text = parts
+        .map((p) => String(((p ?? {}) as Record<string, unknown>)['text'] ?? ''))
+        .join('');
+    const usage = (env['usageMetadata'] ?? {}) as Record<string, unknown>;
+    const num = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+    return {
+        text,
+        model_version: String(env['modelVersion'] ?? ''),
+        usage_metadata: {
+            prompt_token_count: num(usage['promptTokenCount']),
+            candidates_token_count: num(usage['candidatesTokenCount']),
+        },
+    };
+}

package/src/scripts/ai_council/clients.ts

@@ -47,6 +47,12 @@ import * as path from 'node:path';
 
 import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
 import { boundFor } from './cli_agency_bounds.js';
+import {
+    curlJsonPost as _curlJsonPost,
+    geminiRestClient,
+    openAiCompatibleClient,
+    type JsonPost,
+} from './api_transport.js';
 import { SESSION_ROLE_ENV } from '../_lib/session_role.js';
 import { load_agent_settings } from '../_lib/agent_settings.js';
 
@@ -163,9 +169,8 @@ export const DEFAULT_OPENAI_CLI_MODEL = OPENAI_CLI_VENDOR_DEFAULT;
 export const DEFAULT_ANTHROPIC_CLI_MODEL = 'sonnet';
 export const DEFAULT_GEMINI_CLI_MODEL = 'gemini-2.5-pro';
 
-// OpenAI-API-compatible endpoints. xAI and Perplexity both expose the
-// `/v1/chat/completions` shape, so their clients reuse the `openai` SDK with a
-// custom `base_url`. Gemini has its own SDK (`google-genai`).
+// OpenAI-API-compatible endpoints — xAI and Perplexity both expose the
+// `/v1/chat/completions` shape, reached by one curl shim in `api_transport.ts`.
 export const XAI_BASE_URL = 'https://api.x.ai/v1';
 export const PERPLEXITY_BASE_URL = 'https://api.perplexity.ai';
 
@@ -461,6 +466,12 @@ interface ApiClientOptions {
     // Phase 4). Default '5m' when omitted — see `DEFAULT_PROMPT_CACHE_TTL`.
     // Only meaningful when `enable_prompt_cache` is true.
     prompt_cache_ttl?: PromptCacheTtl | undefined;
+    /**
+     * HTTP seam. Omitted → the live `curl` post. A test passes a double
+     * TOGETHER with a real `api_key`, which exercises the shim-building
+     * path that an injected `client:` object skips entirely.
+     */
+    transport?: JsonPost | undefined;
 }
 
 /** Shared ctor-options shape for the CLI clients. */
@@ -479,47 +490,6 @@ interface CliClientOptions {
     consumer?: string | undefined;
 }
 
-/**
- * Synchronous JSON POST via `curl` (no Node SDK, no Python). Matches the
- * council's `spawnSync` transport model so the live-call clients stay
- * synchronous. Returns the parsed response JSON (the provider HTTP APIs return
- * exactly the SDK response shape `ask()` reads). Throws on transport failure or
- * a non-2xx status so `ask()`'s catch surfaces it as a member error.
- */
-function _curlJsonPost(url: string, extraHeaders: string[], body: unknown): unknown {
-    const args = ['-sS', '-X', 'POST', url, '-H', 'content-type: application/json'];
-    for (const h of extraHeaders) {
-        args.push('-H', h);
-    }
-    // `--connect-timeout` fast-fails a dead host; `--max-time` lets curl abort
-    // itself cleanly (surfacing a real `curl exited` error with stderr) ~10s
-    // before the `spawnSync` timeout would kill it with an opaque ETIMEDOUT.
-    // A full 16k-token generation legitimately runs several minutes, so the
-    // ceiling is 300s, not 120s (the old value timed out long Anthropic calls).
-    args.push('--connect-timeout', '30', '--max-time', '290');
-    args.push('-w', '\n%{http_code}', '--data-binary', '@-');
-    const r = spawnSync('curl', args, {
-        input: JSON.stringify(body),
-        encoding: 'utf8',
-        maxBuffer: 64 * 1024 * 1024,
-        timeout: 300_000,
-    });
-    if (r.error) {
-        throw new Error(`curl spawn failed: ${(r.error as Error).message}`);
-    }
-    if (r.status !== 0) {
-        throw new Error(`curl exited ${r.status ?? 'null'}: ${(r.stderr ?? '').toString().slice(0, 500)}`);
-    }
-    const out = (r.stdout ?? '').toString();
-    const nl = out.lastIndexOf('\n');
-    const httpCode = (nl >= 0 ? out.slice(nl + 1) : out).trim();
-    const bodyText = nl >= 0 ? out.slice(0, nl) : out;
-    if (!/^2\d\d$/.test(httpCode)) {
-        throw new Error(`HTTP ${httpCode}: ${bodyText.slice(0, 500)}`);
-    }
-    return JSON.parse(bodyText);
-}
-
 export class AnthropicClient extends ExternalAIClient {
     override name = 'anthropic';
     override billable = true;
@@ -824,13 +794,12 @@ export class OpenAIClient extends ExternalAIClient {
 // ── Gemini / xAI / Perplexity (Phase 0 — Step 6) ─────────────────────
 
 /**
- * Google Gemini via the `google-genai` SDK.
- *
- * Lazy-imports `google.genai` on first `ask()` so disabled members do not
- * require the SDK to be installed. Tests inject a mock client shaped like
- * `genai.Client(api_key=...)` — `self._client.models.generate_content(...)`
- * returns an object with `.text` and
- * `.usage_metadata.{prompt_token_count, candidates_token_count}`.
+ * Google Gemini over the REST API (1.1 — there is no SDK dependency; the old
+ * `google-genai` lazy-import never existed in the TS port and the constructor
+ * simply threw). `ask()` still reads the SDK RESPONSE shape — `.text`,
+ * `.model_version`, `.usage_metadata.{prompt_token_count,
+ * candidates_token_count}` — which `geminiRestClient` normalises to, so every
+ * injected-mock test is unaffected.
  */
 export class GeminiClient extends ExternalAIClient {
     override name = 'gemini';
@@ -851,7 +820,12 @@ export class GeminiClient extends ExternalAIClient {
                     'Use `api_key_ref: env:GEMINI_API_KEY` in ~/.event4u/agent-config/settings/.ai-council.yml.',
             );
         }
-        throw new Error('google-genai package not installed. `pip install google-genai`.');
+        // Live transport (1.1). Was an unconditional `pip install google-genai`
+        // throw, which made `mode: api` dead for this provider however the key
+        // was configured. `geminiRestClient` normalises the REST envelope into
+        // the SDK shape `ask()` below already reads, so `ask()` is untouched
+        // and every existing injected-mock test keeps passing.
+        this._client = geminiRestClient(api_key, opts.transport ?? _curlJsonPost);
     }
 
     override ask(
@@ -901,19 +875,26 @@ export class GeminiClient extends ExternalAIClient {
 }
 
 /**
- * Shared shape for OpenAI-API-compatible providers (xAI, Perplexity).
- *
- * Both vendors implement `/v1/chat/completions` and accept the `openai` Python
- * SDK with a custom `base_url`. The reasoning-model branch from `OpenAIClient`
- * is intentionally omitted — neither xAI nor Perplexity ships a reasoning model
- * that requires `max_completion_tokens` as of 2026-05-14.
+ * Shared shape for OpenAI-API-compatible providers (xAI, Perplexity): both
+ * implement `/v1/chat/completions`, so 1.1 reaches them with one curl shim and
+ * a base URL. The reasoning-model branch from `OpenAIClient` is intentionally
+ * omitted — neither ships a reasoning model that requires
+ * `max_completion_tokens` as of 2026-05-14.
  */
 export class _OpenAICompatibleClient extends ExternalAIClient {
     override billable = true;
     base_url = '';
     protected _client: unknown;
 
-    constructor(opts: { model: string; client?: unknown; api_key?: string | null | undefined }) {
+    constructor(opts: {
+        model: string;
+        client?: unknown;
+        api_key?: string | null | undefined;
+        transport?: JsonPost | undefined;
+        // Passed, never read off `this.base_url`: a subclass field initializer
+        // runs AFTER this constructor, so the field is still '' right here.
+        base_url: string;
+    }) {
         super();
         this.model = opts.model;
         if (opts.client !== undefined && opts.client !== null) {
@@ -926,7 +907,13 @@ export class _OpenAICompatibleClient extends ExternalAIClient {
                 `${this.constructor.name} requires explicit api_key or injected client.`,
             );
         }
-        throw new Error('openai package not installed. `pip install openai`.');
+        // Live transport (1.1) — replaces an unconditional `pip install openai`
+        // throw that made `mode: api` dead for xai and perplexity.
+        this._client = openAiCompatibleClient(
+            opts.base_url,
+            api_key,
+            opts.transport ?? _curlJsonPost,
+        );
     }
 
     override ask(
@@ -989,7 +976,13 @@ export class XAIClient extends _OpenAICompatibleClient {
     override base_url = XAI_BASE_URL;
 
     constructor(opts: ApiClientOptions = {}) {
-        super({ model: opts.model ?? DEFAULT_XAI_MODEL, client: opts.client, api_key: opts.api_key });
+        super({
+            model: opts.model ?? DEFAULT_XAI_MODEL,
+            client: opts.client,
+            api_key: opts.api_key,
+            transport: opts.transport,
+            base_url: XAI_BASE_URL,
+        });
     }
 }
 
@@ -1003,6 +996,8 @@ export class PerplexityClient extends _OpenAICompatibleClient {
             model: opts.model ?? DEFAULT_PERPLEXITY_MODEL,
             client: opts.client,
             api_key: opts.api_key,
+            transport: opts.transport,
+            base_url: PERPLEXITY_BASE_URL,
         });
     }
 }
@@ -1028,8 +1023,8 @@ export {
 //
 // Raised 120 → 300 (2026-08-13) to match the API transport, which has carried
 // `--max-time 290` / `timeout: 300_000` since the 2026-06-24 repair of the same
-// symptom. That repair landed in `_curlJsonPost` only, so when a member resolves
-// to `cli · subscription` the old cap was still live — and a deep design run
+// symptom. That repair landed in `api_transport.ts::curlJsonPost` only, so with
+// a member on `cli · subscription` the old cap was still live — a deep run
 // reproduced it exactly: both members returned `error: timeout` at
 // `latency_ms: 122921` with `timeout_seconds: 120`, and the run reported
 // `0/2 present — INCONCLUSIVE`.

package/src/scripts/ai_council/config.ts

@@ -83,6 +83,8 @@ import * as budget from './cli_call_budget.js';
 // Converting it to a value import — or adding any other runtime import from
 // quorum into config — creates a real ESM cycle in the loader's init path.
 import { OPENAI_CLI_VENDOR_DEFAULT } from './clients.js';
+import { parseSeatFields, type PolicyExclusion } from './seat_policy.js';
+import type { ContentClass } from './content_ceiling.js';
 import { SOLO_FLOOR_MIN_PRESENT } from './quorum.js';
 
 const _VALID_PROVIDERS: ReadonlySet<string> = new Set([
@@ -330,6 +332,12 @@ export interface MemberConfig {
      * demanding a date nobody would refresh.
      */
     readonly verified_at: string | null;
+    /** Seat policy — parsed and documented by `seat_policy.ts::parseSeatFields`.
+     *  All three are NOTES or REFUSALS: none can make a seat available that was
+     *  not already available. */
+    readonly disabled_reason: string | null;
+    readonly policy_exclusion: PolicyExclusion | null;
+    readonly content_ceiling: ContentClass;
 }
 
 /**
@@ -1875,6 +1883,10 @@ function _build_member(
         }
         verified_at = coerced;
     }
+    const seat = parseSeatFields(name, cfg as Record<string, unknown>);
+    if ('error' in seat) {
+        throw new CouncilConfigError(seat.error);
+    }
     const prompt_cache_raw = _get(cfg, 'prompt_cache', null);
     let prompt_cache_ttl: '5m' | '1h' = '5m';
     if (prompt_cache_raw !== null && prompt_cache_raw !== undefined && !_isBool(prompt_cache_raw)) {
@@ -1907,6 +1919,7 @@ function _build_member(
         tier,
         prompt_cache_ttl,
         verified_at,
+        ...seat.fields,
     };
 }
 

package/src/scripts/ai_council/content_ceiling.ts

@@ -0,0 +1,79 @@
+/**
+ * One binary content ceiling per seat — road-to-admissible-council-seats 2.2.
+ *
+ * Redaction today is a SECRETS floor and says so
+ * (`src/skills/ai-council/references/cost-and-redaction.md`). Nothing above it
+ * could express "this project's diff may not go to that seat", which is a
+ * different question with a different answer: a diff carrying no secret at all
+ * is still the consumer's private source.
+ *
+ * Deliberately BINARY. A graded scale invites a middle value nobody can define
+ * and every caller reads differently; two values force the decision at
+ * authoring time, where it belongs.
+ *
+ *   public-artifact  — repo-owned artefacts: skill descriptions, the trigger
+ *                      corpus, rule text, bench fixtures. Already public.
+ *   project-content  — everything a consumer supplies. The DEFAULT, so an
+ *                      unclassified payload is treated as private rather than
+ *                      as publishable.
+ *
+ * A seat's ceiling is the most sensitive class it may receive. `public-artifact`
+ * is therefore the NARROWER seat: it admits public artefacts only.
+ */
+
+export const CONTENT_CLASSES = ['public-artifact', 'project-content'] as const;
+export type ContentClass = (typeof CONTENT_CLASSES)[number];
+
+/** The default for anything not explicitly classified: private, not public. */
+export const DEFAULT_CONTENT_CLASS: ContentClass = 'project-content';
+
+/** The default seat ceiling: unchanged behaviour for every existing seat. */
+export const DEFAULT_SEAT_CEILING: ContentClass = 'project-content';
+
+const _SET: ReadonlySet<string> = new Set<string>(CONTENT_CLASSES);
+
+/**
+ * Any configured value → a content class. Unrecognised input becomes
+ * `project-content`, the RESTRICTIVE value: a typo must narrow what a seat may
+ * receive, never widen it.
+ */
+export function classifyContentClass(raw: unknown, fallback: ContentClass = DEFAULT_CONTENT_CLASS): ContentClass {
+    if (typeof raw === 'string' && _SET.has(raw)) {
+        return raw as ContentClass;
+    }
+    return fallback;
+}
+
+export interface CeilingVerdict {
+    readonly admitted: boolean;
+    /** Non-null exactly when `admitted` is false. */
+    readonly reason: string | null;
+}
+
+/**
+ * Does a seat whose ceiling is `seatCeiling` admit a payload of `contentClass`?
+ *
+ * The one refusal is `project-content` into a `public-artifact` seat. Every
+ * other pairing is admitted, including public artefacts into a
+ * `project-content` seat — a seat cleared for private content is trivially
+ * cleared for public content, and refusing that would be a nonsense that
+ * disables the default seat for its own repo's fixtures.
+ *
+ * Refusal is a GREEN path (this roadmap's 2.2 verify): the caller drops the
+ * seat and the run continues. It is not an error, because a policy working as
+ * designed is not a failure.
+ */
+export function admitsContent(
+    seatCeiling: ContentClass,
+    contentClass: ContentClass,
+): CeilingVerdict {
+    if (seatCeiling === 'public-artifact' && contentClass === 'project-content') {
+        return {
+            admitted: false,
+            reason:
+                "seat ceiling is 'public-artifact'; the payload is classified " +
+                "'project-content' (consumer-supplied)",
+        };
+    }
+    return { admitted: true, reason: null };
+}