@mnstry/atelier 0.2.0-alpha.6 → 0.2.0-alpha.8

package/src/commands/skills.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+import path from 'node:path'
+
+import {
+  applySkillSync,
+  auditSkillCatalog,
+  buildSkillCandidates,
+  planSkillSync,
+  recordSkillObservation,
+} from '../skills/steward.mjs'
+
+const USAGE = `Usage: atelier skills <subcommand>
+
+Subcommands:
+  audit [--root DIR] [--peer DIR] [--json]
+      Audit required metadata, bundle safety, relative resources, and peer parity.
+      With no roots, audits the bundled Codex and Claude skill surfaces.
+
+  observe --workflow KEY --signal SIGNAL [--skill NAME] [--outcome OUTCOME]
+      Append one content-free local observation under ignored .atelier-local state.
+      Prompts, transcripts, free-form summaries, and source content are not accepted.
+
+  candidates [--all] [--json]
+      Aggregate local observations into evidence-thresholded create, improve,
+      reconcile, or retire candidates. This command never edits a skill.
+
+  sync [--source DIR] [--target .agents/skills] [--json]
+      Produce a content-bound plan for updating a repo-scoped managed projection.
+      Apply only with --apply --confirm PLAN_DIGEST. Source skills are never changed,
+      unmanaged collisions and locally drifted managed skills block, and removals are
+      moved to ignored quarantine rather than deleted.
+
+Exit codes: 0 clean or applied, 1 findings or blockers, 2 usage error.`
+
+const OPTION_SPEC = {
+  root: 'value',
+  peer: 'value',
+  source: 'value',
+  target: 'value',
+  workflow: 'value',
+  signal: 'value',
+  skill: 'value',
+  outcome: 'value',
+  confirm: 'value',
+  json: 'flag',
+  all: 'flag',
+  apply: 'flag',
+  'dry-run': 'flag',
+}
+
+function usageError(message) {
+  console.error(`${message}\n\n${USAGE}`)
+  process.exit(2)
+}
+
+function parseOptions(argv, allowed) {
+  const options = {}
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--help' || arg === '-h') {
+      console.log(USAGE)
+      process.exit(0)
+    }
+    if (!arg.startsWith('--')) usageError(`unexpected argument: ${arg}`)
+    const [rawName, inline] = arg.slice(2).split(/=(.*)/s, 2)
+    if (!allowed.has(rawName) || !(rawName in OPTION_SPEC)) usageError(`unknown option --${rawName}`)
+    if (OPTION_SPEC[rawName] === 'flag') {
+      if (inline !== undefined) usageError(`--${rawName} does not take a value`)
+      options[rawName] = true
+      continue
+    }
+    let value = inline
+    if (value === undefined) {
+      index += 1
+      value = argv[index]
+    }
+    if (value === undefined || value.startsWith('--')) usageError(`--${rawName} requires a value`)
+    options[rawName] = value
+  }
+  return options
+}
+
+function printAudit(report, json) {
+  if (json) {
+    console.log(JSON.stringify(report, null, 2))
+    return
+  }
+  console.log(`skills: ${report.summary.skills}; errors: ${report.summary.errors}; warnings: ${report.summary.warnings}`)
+  for (const finding of report.findings) {
+    console.log(`${finding.severity}: ${finding.code} ${finding.surface}/${finding.skill ?? '-'} ${finding.path}`)
+  }
+}
+
+function runAudit(argv) {
+  const options = parseOptions(argv, new Set(['root', 'peer', 'json']))
+  if (options.peer && !options.root) usageError('--peer requires --root')
+  const surfaces = options.root
+    ? [
+        { name: 'source', root: path.resolve(options.root) },
+        ...(options.peer ? [{ name: 'peer', root: path.resolve(options.peer) }] : []),
+      ]
+    : undefined
+  const report = auditSkillCatalog({ surfaces, reportRoot: process.cwd() })
+  printAudit(report, options.json)
+  return (process.exitCode = report.ok ? 0 : 1)
+}
+
+function runObserve(argv) {
+  const options = parseOptions(argv, new Set(['workflow', 'signal', 'skill', 'outcome', 'json']))
+  if (!options.workflow) usageError('--workflow is required')
+  if (!options.signal) usageError('--signal is required')
+  try {
+    const receipt = recordSkillObservation({
+      workspaceRoot: process.cwd(),
+      workflowKey: options.workflow,
+      signal: options.signal,
+      skill: options.skill ?? null,
+      outcome: options.outcome ?? 'unknown',
+    })
+    if (options.json) console.log(JSON.stringify(receipt, null, 2))
+    else console.log(`recorded ${receipt.observation.signal} for ${receipt.observation.workflowKey} as local observation ${receipt.observation.id}`)
+    return (process.exitCode = 0)
+  } catch (error) {
+    console.error(error.message)
+    process.exit(1)
+  }
+}
+
+function runCandidates(argv) {
+  const options = parseOptions(argv, new Set(['all', 'json']))
+  try {
+    const report = buildSkillCandidates({ workspaceRoot: process.cwd(), includeInsufficient: Boolean(options.all) })
+    if (options.json) console.log(JSON.stringify(report, null, 2))
+    else if (!report.candidates.length) console.log('no skill candidates meet the evidence threshold')
+    else {
+      for (const candidate of report.candidates) {
+        console.log(`${candidate.status}: ${candidate.kind} ${candidate.workflowKey}${candidate.skill ? ` (${candidate.skill})` : ''} from ${candidate.evidenceCount} observation(s)`)
+      }
+    }
+    return (process.exitCode = 0)
+  } catch (error) {
+    console.error(error.message)
+    process.exit(1)
+  }
+}
+
+function printPlan(plan, json) {
+  if (json) {
+    console.log(JSON.stringify(plan, null, 2))
+    return
+  }
+  console.log(`plan: ${plan.planDigest}`)
+  console.log(`target: ${plan.target.path}`)
+  for (const action of plan.actions) console.log(`${action.type}: ${action.name}`)
+  for (const blocker of plan.blockers) console.log(`blocker: ${blocker}`)
+  if (!plan.actions.length && !plan.blockers.length) console.log('no managed skill changes')
+}
+
+function runSync(argv) {
+  const options = parseOptions(argv, new Set(['source', 'target', 'confirm', 'json', 'apply', 'dry-run']))
+  if (options.apply && options['dry-run']) usageError('--apply and --dry-run are mutually exclusive')
+  if (options.confirm && !options.apply) usageError('--confirm requires --apply')
+  if (options.apply && !options.confirm) usageError('--apply requires --confirm PLAN_DIGEST')
+  const settings = {
+    workspaceRoot: process.cwd(),
+    sourceRoot: options.source ? path.resolve(options.source) : undefined,
+    target: options.target ?? path.join('.agents', 'skills'),
+  }
+  try {
+    if (options.apply) {
+      const result = applySkillSync({ ...settings, confirm: options.confirm })
+      if (options.json) console.log(JSON.stringify(result, null, 2))
+      else {
+        console.log(`applied: ${result.plan.planDigest}`)
+        for (const quarantined of result.quarantined) console.log(`quarantined: ${quarantined}`)
+      }
+      return (process.exitCode = 0)
+    }
+    const plan = planSkillSync(settings)
+    printPlan(plan, options.json)
+    return (process.exitCode = plan.applyAllowed ? 0 : 1)
+  } catch (error) {
+    console.error(error.message)
+    process.exit(1)
+  }
+}
+
+const argv = process.argv.slice(2)
+const subcommand = argv[0]
+if (subcommand === '--help' || subcommand === '-h' || subcommand === 'help') {
+  console.log(USAGE)
+  process.exit(0)
+}
+if (subcommand === 'audit' || subcommand === undefined) runAudit(argv.slice(subcommand ? 1 : 0))
+else if (subcommand === 'observe') runObserve(argv.slice(1))
+else if (subcommand === 'candidates') runCandidates(argv.slice(1))
+else if (subcommand === 'sync') runSync(argv.slice(1))
+else usageError(`unknown skills subcommand: ${subcommand}`)

package/src/commands/sync.mjs

@@ -2,6 +2,7 @@
 import {
   enrollRepository,
   executeUserConfirmedCommit,
+  obsidianMaintenanceNotice,
   operationTrace,
   planUserConfirmedCommit,
   reconcileRepository,
@@ -35,6 +36,12 @@ function print(value) {
   console.log(JSON.stringify(value, null, 2))
 }
 
+// Status only gains a member when the enrolled project enables Obsidian maintenance; otherwise it is unchanged.
+function withMaintenanceNotice(result) {
+  const notice = obsidianMaintenanceNotice({ repoPath })
+  return notice === null ? result : { ...result, obsidianMaintenance: notice }
+}
+
 async function runLoop({ repoPath, intervalMs, fetchAttempts, once }) {
   do {
     const result = reconcileRepository({ repoPath, fetchAttempts })
@@ -56,7 +63,7 @@ try {
     process.exitCode = result.ok ? 0 : 1
   } else if (subcommand === 'status' || subcommand === 'audit') {
     const result = runtimeStatus({ repoPath })
-    print(result)
+    print(withMaintenanceNotice(result))
     process.exitCode = result.ok ? 0 : 1
   } else if (subcommand === 'reconcile') {
     const result = reconcileRepository({ repoPath, fetchAttempts: integer(args.retries, 3) })

package/src/composition/registry.mjs

@@ -0,0 +1,27 @@
+import { createHash } from 'node:crypto';
+import { parseDefinition, parsePlacement, need, isRef, deepFreeze } from './wire.mjs';
+export const digestBytes = bytes => createHash('sha256').update(bytes).digest('hex');
+
+// A host-owned immutable snapshot, not a mutable catalogue or remote importer.
+export function createRegistrySnapshot({ definitionBytes, rendererBytes, revision, lifecycle = 'active', allowDeprecated = false, validateProps, validateIntent }) {
+  const definition = deepFreeze(parseDefinition(definitionBytes));
+  need(isRef(revision) && ['active', 'deprecated', 'withdrawn', 'revoked'].includes(lifecycle));
+  need(typeof validateProps === 'function' && typeof validateIntent === 'function');
+  const definitionDigest = digestBytes(definitionBytes), rendererDigest = digestBytes(rendererBytes);
+  return Object.freeze({ definition, revision, definitionDigest, rendererDigest, lifecycle,
+    resolve({ sourceBytes, sourceRef, request, operationRef, serviceRef }) {
+      need(lifecycle === 'active' || (lifecycle === 'deprecated' && allowDeprecated));
+      const placement = deepFreeze(parsePlacement(sourceBytes));
+      need(isRef(sourceRef) && isRef(serviceRef) && isRef(operationRef));
+      need(placement.componentId === definition.componentId && placement.componentVersion === definition.version);
+      need(placement.placementId === request.placementId && digestBytes(sourceBytes) === request.sourceDigest);
+      need(definition.previewModes.includes(request.mode) && definition.projections.includes('web'));
+      need(validateProps(placement.props) === true);
+      need(placement.dataBindings.length === 1 && definition.dataContractRefs.includes(placement.dataBindings[0].contractRef));
+      if (request.intentRef) need(validateIntent(request.intentRef, request.payload) === true);
+      return deepFreeze({ resourceRef: placement.dataBindings[0].resourceRef, operationRef, serviceRef, sourceRef,
+        placementRef: placement.placementId, sourceDigest: request.sourceDigest, descriptorDigest: definitionDigest,
+        rendererDigest, registryRevision: revision, warning: lifecycle === 'deprecated' ? 'deprecated' : null });
+    },
+  });
+}

package/src/composition/wire.mjs

@@ -0,0 +1,122 @@
+// Opt-in experimental wire parser. No identity, URL resolution or execution.
+export const MODES = Object.freeze(['synthetic', 'connected-read-only', 'sandbox-interactive']);
+const REF = /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,159}$/;
+const HASH = /^[a-f0-9]{64}$/;
+const VERSION = /^\d+\.\d+\.\d+$/;
+const forbidden = new Set(['__proto__', 'constructor', 'prototype']);
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+export function need(value, message = 'Invalid bounded composition data') { if (!value) throw new TypeError(message); }
+export const isRef = value => typeof value === 'string' && REF.test(value);
+export const isDigest = value => typeof value === 'string' && HASH.test(value);
+export function closed(value, required, optional = []) {
+  need(value && typeof value === 'object' && !Array.isArray(value));
+  need(required.every(key => Object.hasOwn(value, key)) && Object.keys(value).every(key => required.includes(key) || optional.includes(key)));
+}
+
+// JSON.parse alone accepts duplicate keys. This small JSON grammar refuses them
+// at every depth, before schema validation; it never evaluates source text.
+export function parseBoundedJSON(input) {
+  need(typeof input === 'string' || input instanceof Uint8Array);
+  const bytes = typeof input === 'string' ? encoder.encode(input) : input;
+  need(bytes.byteLength <= 65536);
+  let text = decoder.decode(bytes);
+  if (typeof input === 'string') need(text === input, 'Lossy Unicode refused');
+  if (text.charCodeAt(0) === 0xfeff) text = text.slice(1);
+  let i = 0;
+  const ws = () => { while (/[\x20\t\r\n]/.test(text[i] || '\0')) i++; };
+  const string = () => {
+    const start = i++;
+    while (i < text.length) {
+      const c = text[i++];
+      if (c === '\\') { i++; continue; }
+      if (c === '"') {
+        const value = JSON.parse(text.slice(start, i));
+        need(decoder.decode(encoder.encode(value)) === value, 'Lossy Unicode refused');
+        return value;
+      }
+    }
+    throw new TypeError('Unterminated JSON string');
+  };
+  function value(depth) {
+    need(depth <= 8); ws();
+    if (text[i] === '"') return string();
+    if (text[i] === '{') {
+      i++; ws(); const result = Object.create(null);
+      if (text[i] === '}') { i++; return result; }
+      while (i < text.length) {
+        ws(); need(text[i] === '"'); const key = string();
+        need(!Object.hasOwn(result, key), 'Duplicate JSON key refused');
+        ws(); need(text[i++] === ':'); result[key] = value(depth + 1); ws();
+        if (text[i] === '}') { i++; return result; }
+        need(text[i++] === ',');
+      }
+    } else if (text[i] === '[') {
+      i++; ws(); const result = [];
+      if (text[i] === ']') { i++; return result; }
+      while (i < text.length) {
+        result.push(value(depth + 1)); ws();
+        if (text[i] === ']') { i++; return result; }
+        need(text[i++] === ',');
+      }
+    } else {
+      const match = /^(?:true|false|null|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)/.exec(text.slice(i));
+      need(match); i += match[0].length;
+      const result = JSON.parse(match[0]); need(typeof result !== 'number' || Number.isFinite(result)); return result;
+    }
+    throw new TypeError('Invalid JSON');
+  }
+  const result = value(0); ws(); need(i === text.length); return result;
+}
+export function scalarMap(value) {
+  need(value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length <= 64);
+  for (const [key, v] of Object.entries(value)) {
+    need(/^[a-z][a-zA-Z0-9_]{0,79}$/.test(key) && !forbidden.has(key));
+    need(v === null || typeof v === 'boolean' || (typeof v === 'number' && Number.isFinite(v)) || (typeof v === 'string' && v.length <= 4096));
+  }
+  return value;
+}
+function refs(values, maximum, allowed) {
+  need(Array.isArray(values) && values.length <= maximum && new Set(values).size === values.length);
+  need(values.every(v => allowed ? allowed.includes(v) : isRef(v)));
+}
+function version(v) { need(typeof v === 'string' && v.length <= 32 && VERSION.test(v)); }
+export function parseDefinition(bytes) {
+  const v = parseBoundedJSON(bytes);
+  closed(v, ['schema', 'componentId', 'version', 'rendererRef', 'propsSchemaRef', 'dataContractRefs', 'projections', 'previewModes']);
+  need(v.schema === 'atelier-component-definition/proposal-v1');
+  for (const key of ['componentId', 'rendererRef', 'propsSchemaRef']) need(isRef(v[key]));
+  version(v.version); refs(v.dataContractRefs, 16); refs(v.projections, 4, ['web', 'native', 'desktop', 'document']); refs(v.previewModes, 3, MODES);
+  return v;
+}
+export function parsePlacement(bytes) {
+  const v = parseBoundedJSON(bytes);
+  closed(v, ['schema', 'placementId', 'componentId', 'componentVersion', 'slotRef', 'props', 'dataBindings']);
+  need(v.schema === 'atelier-component-placement/proposal-v1');
+  for (const key of ['placementId', 'componentId', 'slotRef']) need(isRef(v[key]));
+  version(v.componentVersion); scalarMap(v.props);
+  need(Array.isArray(v.dataBindings) && v.dataBindings.length <= 16);
+  const seen = new Set();
+  for (const binding of v.dataBindings) {
+    closed(binding, ['contractRef', 'resourceRef']); need(isRef(binding.contractRef) && isRef(binding.resourceRef) && !seen.has(binding.contractRef)); seen.add(binding.contractRef);
+  }
+  return v;
+}
+export function parseRequest(bytes) {
+  const v = parseBoundedJSON(bytes);
+  const action = v?.schema === 'atelier-component-intent/proposal-v1';
+  closed(v, ['schema', 'status', 'requestId', 'placementId', 'sourceDigest', 'mode', ...(action ? ['intentRef', 'payload'] : [])]);
+  need(action || v.schema === 'atelier-preview-request/proposal-v1'); need(v.status === 'proposed' && MODES.includes(v.mode));
+  need(isRef(v.requestId) && isRef(v.placementId) && isDigest(v.sourceDigest));
+  if (action) { need(isRef(v.intentRef)); scalarMap(v.payload); need(v.mode === 'sandbox-interactive'); }
+  return v;
+}
+export function deepFreeze(value) {
+  if (value && typeof value === 'object') { for (const item of Object.values(value)) deepFreeze(item); Object.freeze(value); }
+  return value;
+}
+export function canonical(value) {
+  if (Array.isArray(value)) return '[' + value.map(canonical).join(',') + ']';
+  if (value && typeof value === 'object') return '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':' + canonical(value[key])).join(',') + '}';
+  return JSON.stringify(value);
+}

package/src/contracts/corpus.mjs

@@ -26,6 +26,25 @@ import { fileURLToPath } from 'node:url'
 // document, not a schema, and is deliberately absent.
 
 export const CONTRACT_CORPUS = [
+  { name: 'atelier-decision-request', contractFile: 'contracts/atelier-decision-request.v1.schema.json', fixtureRoot: 'fixtures/decisions/request', registry: false },
+  { name: 'atelier-decision-result', contractFile: 'contracts/atelier-decision-result.v1.schema.json', fixtureRoot: 'fixtures/decisions/result', registry: false },
+  { name: 'atelier-adoption-policy-v1', contractFile: 'contracts/atelier-adoption-policy.v1.schema.json', fixtureRoot: 'fixtures/atelier-upgrade-transaction/adoption-policy', registry: false },
+  { name: 'atelier-migration-v2', contractFile: 'contracts/atelier-migration.v2.schema.json', fixtureRoot: 'fixtures/atelier-upgrade-transaction/migration', registry: false },
+  { name: 'atelier-upgrade-plan-v2', contractFile: 'contracts/atelier-upgrade-plan.v2.schema.json', fixtureRoot: 'fixtures/atelier-upgrade-transaction/upgrade-plan', registry: false },
+  { name: 'atelier-upgrade-receipt-v1', contractFile: 'contracts/atelier-upgrade-receipt.v1.schema.json', fixtureRoot: 'fixtures/atelier-upgrade-transaction/upgrade-receipt', registry: false },
+  { name: 'atelier-presentation', contractFile: 'contracts/atelier-presentation.v1.schema.json', validFiles: ['fixtures/ui/presentation/reference.v1.json'], registry: false },
+  { name: 'atelier-pane-presentation', contractFile: 'contracts/atelier-pane-presentation.v1.schema.json', validFiles: ['fixtures/ui/presentation/pane.v1.json'], registry: false },
+  { name: 'atelier-vault-publication', contractFile: 'contracts/atelier-vault-publication.v1.schema.json', fixtureRoot: 'fixtures/atelier-vault-publication', registry: true },
+  ...['guide', 'intake'].map(kind => ({
+    name: `atelier-${kind}`, contractFile: `contracts/atelier-${kind}.v1.schema.json`,
+    fixtureRoot: `fixtures/atelier-${kind}`, registry: true,
+  })),
+  ...[['audit', 'auditReport'], ['candidates', 'candidateReport'], ['plan', 'syncPlan'], ['lock', 'syncLock']].map(([kind, definition]) => ({
+    name: `atelier-skill-${kind}`, contractFile: 'contracts/atelier-skill-steward.v1.schema.json',
+    docPointer: `#/$defs/${definition}`, fixtureRoot: `fixtures/atelier-skill-steward/${kind}`, registry: true,
+  })),
+  {name: 'atelier-coauthor', contractFile: 'contracts/atelier-coauthor.v1.schema.json', fixtureRoot: 'fixtures/atelier-coauthor', registry: true},
+  {name: 'atelier-review', contractFile: 'contracts/atelier-review.v1.schema.json', fixtureRoot: 'fixtures/atelier-review', registry: false},
   {
     name: 'atelier-repository-observation',
     contractFile: 'contracts/atelier-repository-observation.v1.schema.json',
@@ -142,6 +161,16 @@ export const CONTRACT_CORPUS = [
     invalidFiles: ['fixtures/analysis-adapter/invalid/manifest-hidden-provider.v1.json'],
     registry: true,
   },
+  // Obsidian projection contracts. test/obsidian-contract.test.mjs owns their
+  // positive and negative coverage (several refusals are semantic, beyond what
+  // a schema matcher can express), so they carry registry: false.
+  ...[
+    'corpus-profile', 'scope', 'source-snapshot', 'generation-manifest', 'publication-journal', 'service-state',
+    'edit-operation', 'apply-policy', 'proposal-receipt', 'acceptance-receipt', 'ext-settings',
+  ].map((shape) => ({
+    name: `atelier-obsidian-${shape}`, contractFile: `contracts/atelier-obsidian-${shape}.v1.schema.json`,
+    fixtureRoot: `fixtures/obsidian/contracts/${shape}`, registry: false,
+  })),
   {
     name: 'analysis-adapter-claim-output',
     contractFile: 'contracts/analysis-adapter.v1.schema.json',

package/src/decisions/contracts.d.mts

@@ -0,0 +1,96 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject
+export interface JsonObject { [key: string]: JsonValue }
+export interface DecisionExtension { ext?: JsonObject }
+export interface DecisionScope extends DecisionExtension {
+  workspaceId: string
+  /** Host-reported provenance; this reference does not grant authorization. */
+  authorizationRef: string
+}
+export interface DecisionEvidence extends DecisionExtension {
+  id: string
+  sourceRef: string
+}
+export interface DecisionQuestionBase extends DecisionExtension {
+  instructions: string
+  evidenceIds: string[]
+}
+export interface ChoiceQuestion extends DecisionQuestionBase {
+  type: 'choice'
+  criteria: Record<string, string>
+}
+export interface ScoreQuestion extends DecisionQuestionBase {
+  type: 'score'
+  criteria: string[]
+}
+export interface BooleanQuestion extends DecisionQuestionBase {
+  type: 'boolean'
+  criteria: DecisionExtension & { true: string; false: string }
+}
+export type DecisionQuestion = ChoiceQuestion | ScoreQuestion | BooleanQuestion
+export interface DecisionRequest extends DecisionExtension {
+  schema: 'atelier-decision-request@v1'
+  contractVersion?: `1.${number}.${number}`
+  id: string
+  task: string
+  rubricVersion: string
+  scope: DecisionScope
+  state: string
+  evidence: DecisionEvidence[]
+  questions: Record<string, DecisionQuestion>
+}
+export interface ChoiceAnswer extends DecisionExtension {
+  type: 'choice'
+  choice: string
+  probabilities: Record<string, number>
+  /** A provider statistic, not a measured probability of semantic correctness. */
+  confidence: number
+}
+export interface ScoreAnswer extends DecisionExtension {
+  type: 'score'
+  /** The zero-index weighted expectation of the ordered criteria. */
+  score: number
+  probabilities: number[]
+  confidence: number
+}
+export interface BooleanAnswer extends DecisionExtension {
+  type: 'boolean'
+  probability: number
+}
+export type DecisionAnswer = ChoiceAnswer | ScoreAnswer | BooleanAnswer
+export interface DecisionUsage extends DecisionExtension {
+  inputTokens: number
+  outputTokens: number
+}
+export interface DecisionResultBase extends DecisionExtension {
+  schema: 'atelier-decision-result@v1'
+  contractVersion?: `1.${number}.${number}`
+  requestId: string
+  requestDigest: string
+  task: string
+  rubricVersion: string
+  scope: DecisionScope
+  provider: DecisionExtension & { id: string; model: string }
+  authority: 'proposal-only'
+  mode: 'shadow' | 'advisory'
+  usage: DecisionUsage | null
+  elapsedMs: number
+}
+export interface AssessedDecisionResult extends DecisionResultBase {
+  status: 'assessed'
+  answers: Record<string, DecisionAnswer>
+  reason?: never
+}
+export type DecisionAbstentionReason = 'insufficient-evidence' | 'ambiguous' | 'no-match' | 'budget-exhausted' | 'provider-unavailable' | 'timeout' | 'invalid-response' | 'unauthorized'
+export interface AbstainedDecisionResult extends DecisionResultBase {
+  status: 'abstained'
+  answers: Record<string, never>
+  reason: DecisionAbstentionReason
+}
+export type DecisionResult = AssessedDecisionResult | AbstainedDecisionResult
+export interface DecisionValidation { ok: boolean; errors: string[] }
+export function validateDecisionRequest(input: unknown): DecisionValidation
+export function validateDecisionResult(request: unknown, result: unknown): DecisionValidation
+/** Checks questions and answers without state, hashing, or evidence membership. */
+export function validateDecisionAnswers(questions: unknown, answers: unknown): DecisionValidation
+/** Throws a generic TypeError for invalid input. The digest is lowercase SHA-256. */
+export function decisionRequestDigest(request: unknown): string