@etiquekit/etq 1.0.14 → 1.0.16

package/packages/control/src/seat/owner-card.ts

@@ -1,388 +0,0 @@
-import { existsSync } from 'node:fs';
-import { readdir, readFile } from 'node:fs/promises';
-import { extname, join, relative, resolve } from 'node:path';
-import { parse as parseYaml } from 'yaml';
-import { evaluateSeatReadiness, readSeatReadiness, type SeatReadinessStatus } from './readiness';
-
-export const AGENT_OWNER_CARD_SOURCE_SCHEMA = 'agent-owner-card-source.v0';
-export const AGENT_OWNER_CARD_SCHEMA = 'agent-owner-card.v0';
-export const AGENT_OWNER_CARD_PROJECTION_SCHEMA = 'agent-owner-card-projection.v0';
-
-type JsonRecord = Record<string, unknown>;
-
-export interface AgentOwnerFailureMode {
-  id: string;
-  description: string;
-  evidence_refs: string[];
-}
-
-export interface AgentOwnerCardSource {
-  schema: typeof AGENT_OWNER_CARD_SOURCE_SCHEMA;
-  seat_id: string;
-  job: string;
-  owner_principal: string;
-  maintainer: string;
-  diet_refs: string[];
-  authority_contract_ref: string;
-  allowed_work: string[];
-  forbidden_work: string[];
-  review: {
-    cadence: string;
-    last_reviewed_at: string;
-    stale_after: string;
-    event_triggers: string[];
-  };
-  failure_modes: AgentOwnerFailureMode[];
-}
-
-export interface AgentOwnerCard {
-  schema: typeof AGENT_OWNER_CARD_SCHEMA;
-  generated_at: string;
-  source_ref: string;
-  seat_id: string;
-  job: string;
-  accountability: {
-    owner_principal: string;
-    maintainer: string;
-    operator_principal_scope: 'per_run_receipts_only';
-    owner_is_not_operator: true;
-  };
-  diet_refs: string[];
-  current_occupant: null | {
-    source: 'seat-readiness.v0.1';
-    readiness_ref: string;
-    seat: string;
-    execution_surface: string;
-    model_tier: string;
-    effective_model_tier: string;
-    model_id: string | null;
-    operational_status: string;
-    capability_trusted: boolean;
-    is_stale: boolean;
-    last_heartbeat_at: string;
-    stale_after: string;
-  };
-  authority: {
-    source_ref: string;
-    allowed_work: string[];
-    forbidden_work: string[];
-    derived_from_contract: true;
-    card_may_edit_authority: false;
-  };
-  review: {
-    cadence: string;
-    last_reviewed_at: string;
-    stale_after: string;
-    is_stale: boolean;
-    event_driven_triggers: string[];
-  };
-  failure_modes: AgentOwnerFailureMode[];
-  warnings: string[];
-  authority_boundary: {
-    read_model_only: true;
-    can_authorize: false;
-    can_attach_grant: false;
-    can_change_owner: false;
-    can_edit_authority: false;
-    can_mutate_readiness: false;
-    can_merge: false;
-    can_close: false;
-  };
-}
-
-export interface AgentOwnerCardProjection {
-  schema: typeof AGENT_OWNER_CARD_PROJECTION_SCHEMA;
-  generated_at: string;
-  cards: AgentOwnerCard[];
-  validation_errors: Array<{ ref: string; reason: string }>;
-  authority_boundary: AgentOwnerCard['authority_boundary'];
-}
-
-const DEFAULT_EVENT_TRIGGERS = [
-  'model_switch',
-  'new_failure_mode',
-  'authority_change',
-  'seat_readiness_stale',
-] as const;
-
-function isoNow(at?: string): string {
-  const value = at ?? new Date().toISOString();
-  if (!Number.isFinite(Date.parse(value))) throw new Error('--at must be an ISO-8601 timestamp');
-  return new Date(value).toISOString();
-}
-
-function isRecord(value: unknown): value is JsonRecord {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function requireRecord(value: unknown, field: string): JsonRecord {
-  if (!isRecord(value)) throw new Error(`${field} must be an object`);
-  return value;
-}
-
-function requireString(record: JsonRecord, key: string): string {
-  const value = record[key];
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`${key} is required`);
-  }
-  assertSafeText(value, key);
-  return value.trim();
-}
-
-function optionalStringArray(record: JsonRecord, key: string): string[] {
-  const value = record[key];
-  if (value === undefined) return [];
-  if (!Array.isArray(value)) throw new Error(`${key} must be a string array`);
-  return value.map((item, index) => {
-    if (typeof item !== 'string' || item.trim().length === 0) {
-      throw new Error(`${key}[${index}] must be a non-empty string`);
-    }
-    assertSafeText(item, `${key}[${index}]`);
-    return item.trim();
-  });
-}
-
-function requireStringArray(record: JsonRecord, key: string): string[] {
-  const values = optionalStringArray(record, key);
-  if (values.length === 0) throw new Error(`${key} must contain at least one item`);
-  return values;
-}
-
-function assertOpaqueId(value: string, field: string): void {
-  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(value)) {
-    throw new Error(`${field} must be an opaque id using letters, numbers, hyphen, or underscore`);
-  }
-}
-
-function assertSafeText(value: string, field: string): void {
-  if (value.length > 512) throw new Error(`${field} must be 512 characters or fewer`);
-  if (/[\u0000-\u001f]/.test(value)) throw new Error(`${field} must not contain control characters`);
-}
-
-function assertIso(value: string, field: string): void {
-  if (!Number.isFinite(Date.parse(value))) throw new Error(`${field} must be an ISO-8601 timestamp`);
-}
-
-function parseFailureModes(value: unknown): AgentOwnerFailureMode[] {
-  if (!Array.isArray(value) || value.length === 0) {
-    throw new Error('failure_modes must contain at least one item');
-  }
-  return value.map((item, index) => {
-    const record = requireRecord(item, `failure_modes[${index}]`);
-    const id = requireString(record, 'id');
-    assertOpaqueId(id, `failure_modes[${index}].id`);
-    const description = requireString(record, 'description');
-    const evidenceRefs = requireStringArray(record, 'evidence_refs');
-    return { id, description, evidence_refs: evidenceRefs };
-  });
-}
-
-function parseSource(raw: unknown): AgentOwnerCardSource {
-  const record = requireRecord(raw, 'agent owner card source');
-  if (record.schema !== AGENT_OWNER_CARD_SOURCE_SCHEMA) {
-    throw new Error(`schema must be ${AGENT_OWNER_CARD_SOURCE_SCHEMA}`);
-  }
-  if ('current_occupant' in record || 'occupant' in record || 'model_id' in record || 'model_tier' in record) {
-    throw new Error('current occupant and model posture are derived from seat-readiness, not authored on the owner card source');
-  }
-  const seatId = requireString(record, 'seat_id');
-  assertOpaqueId(seatId, 'seat_id');
-  const ownerPrincipal = requireString(record, 'owner_principal');
-  assertOpaqueId(ownerPrincipal, 'owner_principal');
-  const maintainer = requireString(record, 'maintainer');
-  assertOpaqueId(maintainer, 'maintainer');
-  const review = requireRecord(record.review, 'review');
-  const lastReviewedAt = requireString(review, 'last_reviewed_at');
-  const staleAfter = requireString(review, 'stale_after');
-  assertIso(lastReviewedAt, 'review.last_reviewed_at');
-  assertIso(staleAfter, 'review.stale_after');
-  return {
-    schema: AGENT_OWNER_CARD_SOURCE_SCHEMA,
-    seat_id: seatId,
-    job: requireString(record, 'job'),
-    owner_principal: ownerPrincipal,
-    maintainer,
-    diet_refs: requireStringArray(record, 'diet_refs'),
-    authority_contract_ref: requireString(record, 'authority_contract_ref'),
-    allowed_work: requireStringArray(record, 'allowed_work'),
-    forbidden_work: requireStringArray(record, 'forbidden_work'),
-    review: {
-      cadence: requireString(review, 'cadence'),
-      last_reviewed_at: new Date(lastReviewedAt).toISOString(),
-      stale_after: new Date(staleAfter).toISOString(),
-      event_triggers: optionalStringArray(review, 'event_triggers'),
-    },
-    failure_modes: parseFailureModes(record.failure_modes),
-  };
-}
-
-async function readStructured(path: string): Promise<unknown> {
-  const raw = await readFile(path, 'utf-8');
-  if (extname(path).toLowerCase() === '.json') return JSON.parse(raw) as unknown;
-  return parseYaml(raw) as unknown;
-}
-
-function projectRelative(projectRoot: string, path: string): string {
-  const rel = relative(resolve(projectRoot), resolve(path));
-  if (rel.length === 0 || rel.startsWith('..') || rel.includes('\\')) {
-    throw new Error(`path must stay inside project root: ${path}`);
-  }
-  return rel;
-}
-
-function unique(values: string[]): string[] {
-  return [...new Set(values)];
-}
-
-function currentOccupant(
-  status: SeatReadinessStatus | null,
-  readinessRef: string,
-): AgentOwnerCard['current_occupant'] {
-  if (!status) return null;
-  return {
-    source: 'seat-readiness.v0.1',
-    readiness_ref: readinessRef,
-    seat: status.seat,
-    execution_surface: status.execution_surface,
-    model_tier: status.model_tier,
-    effective_model_tier: status.effective_model_tier,
-    model_id: status.model_id ?? null,
-    operational_status: status.operational_status,
-    capability_trusted: status.capability_trusted,
-    is_stale: status.is_stale,
-    last_heartbeat_at: status.last_heartbeat_at,
-    stale_after: status.stale_after,
-  };
-}
-
-function boundary(): AgentOwnerCard['authority_boundary'] {
-  return {
-    read_model_only: true,
-    can_authorize: false,
-    can_attach_grant: false,
-    can_change_owner: false,
-    can_edit_authority: false,
-    can_mutate_readiness: false,
-    can_merge: false,
-    can_close: false,
-  };
-}
-
-export async function buildAgentOwnerCard(options: {
-  projectRoot: string;
-  manifestPath: string;
-  statePath?: string;
-  at?: string;
-}): Promise<AgentOwnerCard> {
-  const root = resolve(options.projectRoot);
-  const generatedAt = isoNow(options.at);
-  const manifestPath = resolve(options.manifestPath);
-  const source = parseSource(await readStructured(manifestPath));
-  const sourceRef = projectRelative(root, manifestPath);
-  const readinessRef = options.statePath
-    ? projectRelative(root, resolve(options.statePath))
-    : '.etiquette/state/seat-readiness.json';
-
-  let readiness: SeatReadinessStatus | null = null;
-  const warnings: string[] = [];
-  try {
-    const record = await readSeatReadiness(root, options.statePath);
-    readiness = evaluateSeatReadiness(record, generatedAt);
-    if (readiness.seat !== source.seat_id) warnings.push('seat_readiness_mismatch');
-    if (readiness.is_stale) warnings.push('seat_readiness_stale');
-  } catch (err) {
-    warnings.push(`seat_readiness_unavailable:${err instanceof Error ? err.message : String(err)}`);
-  }
-
-  const reviewIsStale = Date.parse(generatedAt) > Date.parse(source.review.stale_after);
-  if (reviewIsStale) warnings.push('owner_card_review_stale');
-
-  return {
-    schema: AGENT_OWNER_CARD_SCHEMA,
-    generated_at: generatedAt,
-    source_ref: sourceRef,
-    seat_id: source.seat_id,
-    job: source.job,
-    accountability: {
-      owner_principal: source.owner_principal,
-      maintainer: source.maintainer,
-      operator_principal_scope: 'per_run_receipts_only',
-      owner_is_not_operator: true,
-    },
-    diet_refs: source.diet_refs,
-    current_occupant: currentOccupant(readiness, readinessRef),
-    authority: {
-      source_ref: source.authority_contract_ref,
-      allowed_work: source.allowed_work,
-      forbidden_work: source.forbidden_work,
-      derived_from_contract: true,
-      card_may_edit_authority: false,
-    },
-    review: {
-      cadence: source.review.cadence,
-      last_reviewed_at: source.review.last_reviewed_at,
-      stale_after: source.review.stale_after,
-      is_stale: reviewIsStale,
-      event_driven_triggers: unique([...DEFAULT_EVENT_TRIGGERS, ...source.review.event_triggers]),
-    },
-    failure_modes: source.failure_modes,
-    warnings,
-    authority_boundary: boundary(),
-  };
-}
-
-async function collectFiles(dir: string): Promise<string[]> {
-  if (!existsSync(dir)) return [];
-  const entries = await readdir(dir, { withFileTypes: true });
-  const nested = await Promise.all(entries.map(async (entry) => {
-    const path = join(dir, entry.name);
-    if (entry.isDirectory()) return collectFiles(path);
-    return entry.isFile() ? [path] : [];
-  }));
-  return nested.flat().sort();
-}
-
-export async function buildAgentOwnerCardProjection(options: {
-  projectRoot: string;
-  statePath?: string;
-  at?: string;
-}): Promise<AgentOwnerCardProjection> {
-  const root = resolve(options.projectRoot);
-  const generatedAt = isoNow(options.at);
-  const candidates = [
-    join(root, '.etiquette', 'seats', 'owner-card.yaml'),
-    join(root, '.etiquette', 'seats', 'owner-card.yml'),
-    join(root, '.etiquette', 'seats', 'owner-card.json'),
-    ...(await collectFiles(join(root, '.etiquette', 'seats', 'owner-cards'))),
-    ...(await collectFiles(join(root, 'docs', 'work', 'seats', 'owner-cards'))),
-  ].filter((path, index, all) => {
-    const ext = extname(path).toLowerCase();
-    return existsSync(path) && ['.yaml', '.yml', '.json'].includes(ext) && all.indexOf(path) === index;
-  });
-
-  const cards: AgentOwnerCard[] = [];
-  const validationErrors: AgentOwnerCardProjection['validation_errors'] = [];
-  for (const manifestPath of candidates) {
-    try {
-      cards.push(await buildAgentOwnerCard({
-        projectRoot: root,
-        manifestPath,
-        statePath: options.statePath,
-        at: generatedAt,
-      }));
-    } catch (err) {
-      validationErrors.push({
-        ref: projectRelative(root, manifestPath),
-        reason: err instanceof Error ? err.message : String(err),
-      });
-    }
-  }
-
-  return {
-    schema: AGENT_OWNER_CARD_PROJECTION_SCHEMA,
-    generated_at: generatedAt,
-    cards,
-    validation_errors: validationErrors,
-    authority_boundary: boundary(),
-  };
-}