@etiquekit/etq 1.0.12 → 1.0.14

package/packages/control/src/workflow/loader.ts

@@ -0,0 +1,200 @@
+import { readFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { assertSharedMemoryScopeId, assertSharedMemoryText } from '../shared/sanitize';
+import {
+  GRANTORS,
+  STRATEGY_POLICIES,
+  WORKFLOW_DISPATCH_MODES,
+  WORKFLOW_MODE_TYPES,
+  WORKFLOW_RISK_LEVELS,
+  type Grantor,
+  type StrategyPolicy,
+  type WorkflowCheckEnvelope,
+  type WorkflowDispatchMode,
+  type WorkflowMode,
+  type WorkflowModeType,
+  type WorkflowRiskLevel,
+} from './types';
+
+type JsonRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+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 asRecord(value: unknown, name: string): JsonRecord {
+  if (!isRecord(value)) throw new Error(`${name} must be an object`);
+  return value;
+}
+
+function asString(record: JsonRecord, key: string): string {
+  const value = record[key];
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${key} must be a non-empty string`);
+  }
+  return value;
+}
+
+function asNullableString(record: JsonRecord, key: string): string | null {
+  const value = record[key];
+  if (value === null || value === undefined) return null;
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${key} must be null or a non-empty string`);
+  }
+  return value;
+}
+
+function asStringArray(record: JsonRecord, key: string): string[] {
+  const value = record[key];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+    throw new Error(`${key} must be a string array`);
+  }
+  return value as string[];
+}
+
+function asBoolean(record: JsonRecord, key: string): boolean {
+  const value = record[key];
+  if (typeof value !== 'boolean') throw new Error(`${key} must be a boolean`);
+  return value;
+}
+
+function asNumber(record: JsonRecord, key: string): number {
+  const value = record[key];
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+    throw new Error(`${key} must be a non-negative integer`);
+  }
+  return value;
+}
+
+function asEnum<T extends readonly string[]>(values: T, raw: unknown, key: string): T[number] {
+  if (typeof raw !== 'string' || !(values as readonly string[]).includes(raw)) {
+    throw new Error(`${key} must be one of: ${values.join(', ')}`);
+  }
+  return raw as T[number];
+}
+
+function assertSemverish(value: string, key: string): void {
+  if (!/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9_.-]+)?$/.test(value)) {
+    throw new Error(`${key} must be semver-like (x.y.z)`);
+  }
+}
+
+function assertSafeTextOrNull(value: string | null, key: string): void {
+  if (value !== null) assertSharedMemoryText(value, key);
+}
+
+function validateModeInvariants(mode: WorkflowMode): void {
+  if (mode.authority_status !== 'policy_preset_only') {
+    throw new Error('authority_status must be policy_preset_only');
+  }
+  if (mode.grant.advisory_consensus_can_authorize !== false) {
+    throw new Error('grant.advisory_consensus_can_authorize must be false');
+  }
+  if (mode.drafting.min_reviewers > 0 && !mode.drafting.requires_review) {
+    throw new Error('drafting.min_reviewers requires drafting.requires_review');
+  }
+  if (mode.mode_type === 'mixed' && mode.execution.dispatch === 'immediate') {
+    throw new Error('mixed mode must not dispatch immediate before a grant hinge');
+  }
+  if (mode.mode_type === 'expedient' && !mode.proof.receipt_required) {
+    throw new Error('expedient mode must require receipt proof');
+  }
+  if (mode.mode_type === 'expedient' && !mode.proof.validation_required) {
+    throw new Error('expedient mode must require validation evidence');
+  }
+}
+
+export function parseWorkflowMode(value: unknown): WorkflowMode {
+  const record = asRecord(value, 'workflow_mode');
+  const drafting = asRecord(record.drafting, 'drafting');
+  const grant = asRecord(record.grant, 'grant');
+  const execution = asRecord(record.execution, 'execution');
+  const proof = asRecord(record.proof, 'proof');
+  const audit = asRecord(record.audit, 'audit');
+
+  const mode: WorkflowMode = {
+    mode_id: asString(record, 'mode_id'),
+    mode_version: asString(record, 'mode_version'),
+    mode_type: asEnum(WORKFLOW_MODE_TYPES, record.mode_type, 'mode_type') as WorkflowModeType,
+    drafting: {
+      surface: asString(drafting, 'surface'),
+      requires_review: asBoolean(drafting, 'requires_review'),
+      min_reviewers: asNumber(drafting, 'min_reviewers'),
+      amendment_rounds_allowed: asBoolean(drafting, 'amendment_rounds_allowed'),
+      adversarial_review_required: asBoolean(drafting, 'adversarial_review_required'),
+      compact_reason_required: asBoolean(drafting, 'compact_reason_required'),
+    },
+    grant: {
+      required: asBoolean(grant, 'required'),
+      preauthorization_allowed: asBoolean(grant, 'preauthorization_allowed'),
+      granted_by: asEnum(GRANTORS, grant.granted_by, 'granted_by') as Grantor,
+      advisory_consensus_can_authorize: asBoolean(grant, 'advisory_consensus_can_authorize') as false,
+    },
+    execution: {
+      surface: asString(execution, 'surface'),
+      dispatch: asEnum(WORKFLOW_DISPATCH_MODES, execution.dispatch, 'dispatch') as WorkflowDispatchMode,
+      strategy_policy: asEnum(STRATEGY_POLICIES, execution.strategy_policy, 'strategy_policy') as StrategyPolicy,
+      rubric_required: asBoolean(execution, 'rubric_required'),
+    },
+    proof: {
+      receipt_required: asBoolean(proof, 'receipt_required'),
+      validation_required: asBoolean(proof, 'validation_required'),
+      closeout_requires_receipt: asBoolean(proof, 'closeout_requires_receipt'),
+    },
+    audit: {
+      event_log_required: asBoolean(audit, 'event_log_required'),
+      dissent_capture_required: asBoolean(audit, 'dissent_capture_required'),
+    },
+    authority_status: asEnum(['policy_preset_only'] as const, record.authority_status, 'authority_status'),
+  };
+
+  assertSharedMemoryScopeId(mode.mode_id, 'mode_id');
+  assertSemverish(mode.mode_version, 'mode_version');
+  assertSharedMemoryScopeId(mode.drafting.surface, 'drafting.surface');
+  assertSharedMemoryScopeId(mode.execution.surface, 'execution.surface');
+  validateModeInvariants(mode);
+  return mode;
+}
+
+export async function loadWorkflowMode(path: string): Promise<WorkflowMode> {
+  return parseWorkflowMode(await readStructured(path));
+}
+
+export function parseWorkflowEnvelope(value: unknown): WorkflowCheckEnvelope {
+  const record = asRecord(value, 'workflow_check_envelope');
+  const envelope: WorkflowCheckEnvelope = {
+    task_ref: asString(record, 'task_ref'),
+    workflow_mode_ref: asString(record, 'workflow_mode_ref'),
+    requested_mode_type: asEnum(WORKFLOW_MODE_TYPES, record.requested_mode_type, 'requested_mode_type') as WorkflowModeType,
+    mutates_state: asBoolean(record, 'mutates_state'),
+    grant_ref: asNullableString(record, 'grant_ref'),
+    consensus_ref: asNullableString(record, 'consensus_ref'),
+    receipt_ref: asNullableString(record, 'receipt_ref'),
+    validation_refs: asStringArray(record, 'validation_refs'),
+    bounded: asBoolean(record, 'bounded'),
+    preauthorized: asBoolean(record, 'preauthorized'),
+    advisory_consensus_claims_authority: asBoolean(record, 'advisory_consensus_claims_authority'),
+    risk: asEnum(WORKFLOW_RISK_LEVELS, record.risk, 'risk') as WorkflowRiskLevel,
+  };
+
+  assertSharedMemoryText(envelope.task_ref, 'task_ref');
+  assertSharedMemoryText(envelope.workflow_mode_ref, 'workflow_mode_ref');
+  assertSafeTextOrNull(envelope.grant_ref, 'grant_ref');
+  assertSafeTextOrNull(envelope.consensus_ref, 'consensus_ref');
+  assertSafeTextOrNull(envelope.receipt_ref, 'receipt_ref');
+  for (const ref of envelope.validation_refs) assertSharedMemoryText(ref, 'validation_refs[]');
+  return envelope;
+}
+
+export async function loadWorkflowEnvelope(path: string): Promise<WorkflowCheckEnvelope> {
+  return parseWorkflowEnvelope(await readStructured(path));
+}

package/packages/control/src/workflow/types.ts

@@ -0,0 +1,90 @@
+export const WORKFLOW_MODE_TYPES = ['deliberative', 'expedient', 'mixed'] as const;
+export type WorkflowModeType = typeof WORKFLOW_MODE_TYPES[number];
+
+export const WORKFLOW_DISPATCH_MODES = ['manual', 'immediate', 'immediate_after_grant'] as const;
+export type WorkflowDispatchMode = typeof WORKFLOW_DISPATCH_MODES[number];
+
+export const STRATEGY_POLICIES = ['executor_selected', 'suggested', 'required'] as const;
+export type StrategyPolicy = typeof STRATEGY_POLICIES[number];
+
+export const GRANTORS = ['operator_principal', 'delegated_control_seat'] as const;
+export type Grantor = typeof GRANTORS[number];
+
+export const WORKFLOW_RISK_LEVELS = ['low', 'medium', 'high'] as const;
+export type WorkflowRiskLevel = typeof WORKFLOW_RISK_LEVELS[number];
+
+export const WORKFLOW_RECOMMENDATIONS = ['pass', 'warn', 'block'] as const;
+export type WorkflowRecommendation = typeof WORKFLOW_RECOMMENDATIONS[number];
+
+export interface WorkflowMode {
+  mode_id: string;
+  mode_version: string;
+  mode_type: WorkflowModeType;
+  drafting: {
+    surface: string;
+    requires_review: boolean;
+    min_reviewers: number;
+    amendment_rounds_allowed: boolean;
+    adversarial_review_required: boolean;
+    compact_reason_required: boolean;
+  };
+  grant: {
+    required: boolean;
+    preauthorization_allowed: boolean;
+    granted_by: Grantor;
+    advisory_consensus_can_authorize: false;
+  };
+  execution: {
+    surface: string;
+    dispatch: WorkflowDispatchMode;
+    strategy_policy: StrategyPolicy;
+    rubric_required: boolean;
+  };
+  proof: {
+    receipt_required: boolean;
+    validation_required: boolean;
+    closeout_requires_receipt: boolean;
+  };
+  audit: {
+    event_log_required: boolean;
+    dissent_capture_required: boolean;
+  };
+  authority_status: 'policy_preset_only';
+}
+
+export interface WorkflowCheckEnvelope {
+  task_ref: string;
+  workflow_mode_ref: string;
+  requested_mode_type: WorkflowModeType;
+  mutates_state: boolean;
+  grant_ref: string | null;
+  consensus_ref: string | null;
+  receipt_ref: string | null;
+  validation_refs: string[];
+  bounded: boolean;
+  preauthorized: boolean;
+  advisory_consensus_claims_authority: boolean;
+  risk: WorkflowRiskLevel;
+}
+
+export interface WorkflowCheckResult {
+  schema: 'workflow-check-receipt.v0';
+  task_ref: string;
+  mode_id: string;
+  mode_type: WorkflowModeType;
+  recommendation: WorkflowRecommendation;
+  missing: string[];
+  warnings: string[];
+  checks: Array<{
+    check_id: string;
+    status: WorkflowRecommendation;
+    summary: string;
+  }>;
+  authority_boundary: {
+    can_authorize: false;
+    can_attach_grant: false;
+    consensus_can_authorize: false;
+    mode_is_engine: false;
+    requires_grant: boolean;
+  };
+}