Skip to main content

Schemas and Types

APS uses Zod schemas for runtime validation and TypeScript type generation.

TypeScript Types​

The core types are exported from @eddacraft/anvil-aps:

import type {
  Task,
  ModuleMetadata,
  ParsedDocument,
} from '@eddacraft/anvil-aps';

Task​

A unit of authorised work:

interface Task {
  id: string; // Pattern: SCOPE-NNN (e.g., AUTH-001)
  title: string;
  intent: string; // What the task aims to achieve (required)
  expectedOutcome?: string; // Success criteria
  validation?: string; // Command to verify completion
  confidence?: 'low' | 'medium' | 'high'; // Defaults to 'medium'
  scopes?: string[]; // File access constraints
  nonScope?: string[]; // What will NOT be changed
  files?: string[]; // Files that may be affected
  tags?: string[]; // Labels for filtering
  dependencies?: string[]; // Tasks that must complete first
  inputs?: string[]; // Required inputs or context
  risks?: string[]; // Potential risks
  link?: string; // External link (e.g., Jira ticket)
  status?: 'open' | 'locked' | 'completed' | 'cancelled';
  sourcePath?: string; // Source file path
  sourceLineNumber?: number; // Line number in source
}

Task ID Format​

Task IDs follow the pattern {SCOPE}-{NNN}:

  • 1-10 uppercase alphanumeric characters for the scope
  • Hyphen separator
  • 3-digit zero-padded number
AUTH-001   ✓
PAY-042   ✓
CORE-001  ✓
LLM2-007  ✓
auth-001  ✗  (must be uppercase)
AUTH-1    ✗  (must be 3 digits)

Module Metadata​

interface ModuleMetadata {
  id?: string; // Module identifier
  title?: string; // From H1 heading
  path?: string; // Path to spec file
  scope?: string; // Scope prefix for task IDs
  owner?: string; // Person/team responsible
  status?: 'Draft' | 'Ready' | 'In Progress' | 'Complete' | 'Blocked';
  priority?: 'low' | 'medium' | 'high';
  tags?: string[];
  dependencies?: string[]; // Other modules this depends on
}

Parsed Document​

Result of parsing a leaf spec file:

interface ParsedDocument {
  title: string; // From H1 heading
  metadata?: ModuleMetadata;
  tasks: Task[];
  sourcePath?: string;
}

Programmatic Validation​

Use the Zod schemas directly for runtime validation:

import { TaskSchema, ModuleMetadataSchema } from '@eddacraft/anvil-aps';

const result = TaskSchema.safeParse(data);

if (!result.success) {
  console.error(result.error.issues);
}

Validation Errors​

Common validation errors:

Missing Required Field​

ZodError: Required at "intent"

The intent field is required for all tasks.

Invalid Task ID​

ZodError: Invalid at "id" — must match pattern ^[A-Z0-9]{1,10}-\d{3}$

Invalid Status​

ZodError: Invalid enum value at "status"
  Expected: 'open' | 'locked' | 'completed' | 'cancelled'
  Received: 'done'

Next: Examples →