agent-apprenticeship 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Apprenticeship
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,217 @@
+# Agent Apprenticeship
+
+The living ecosystem where AI agents learn from real-world work through iterative loops, reusable experience, and training-signal exchange.
+
+As agents move into long-horizon, economically valuable work, Agent Apprenticeship creates the open infrastructure where useful work generates reusable learning signals and challenging tasks improve through automated iterative loops.
+
+Agent Apprenticeship is designed for an infinite exchange of work experience between agents: useful work creates training signals, signals improve future work, and future work creates new signals for the ecosystem.
+
+Agent Apprenticeship is built for loop iterations across domains, from simple tasks to complex specialized workflows. Apprentice agents can work with mentor agents to accomplish long-horizon, real-world tasks across model-assisted, expert-led, and hybrid modes, generating learning signals throughout the process.
+
+The first seed dataset includes:
+
+* 500+ curated seed tasks sourced and grounded from real world
+* 495 reusable agent lessons
+* 1000+ full agent execution traces
+* 1000+ agent work episodes / task rollouts
+
+The seed dataset spans specialized economically valuable tasks across domains and forms the first layer of the Agent Apprenticeship ecosystem.
+
+Agent Apprenticeship is now available for anyone to start using with local agents including Codex, Cursor, Claude Code, OpenClaw, OpenCode, Hermes Agent, and custom agents, alongside different model providers. Users can experience automated iterative loops locally, contribute agent learning signals back to the ecosystem, and access ecosystem learning signals to improve their own agents.
+
+Agent Apprenticeship is also about the future of work and the economic value of agents. For every task executed through Agent Apprenticeship, the system can estimate task-level economic value, especially across specialized domains. It is built for everyday use to improve agent performance and outcome quality, while also enabling users to exchange agent work experience with each other and with domain-expert-led agents in one living ecosystem.
+
+## Install
+
+```bash
+npx agent-apprenticeship init
+```
+
+```bash
+npm install -g agent-apprenticeship
+apprentice init
+```
+
+The installed command is:
+
+```bash
+apprentice
+```
+
+The long-form command also remains available:
+
+```bash
+agent-apprenticeship
+```
+
+## Quickstart
+
+```bash
+apprentice init
+apprentice settings
+apprentice run "Create a short market map for AI procurement tools."
+```
+
+Runs print the artifacts path and Contribution Bundle path.
+
+```bash
+apprentice ecosystem contribute <bundle_path>
+```
+
+Public ecosystem:
+
+https://github.com/Forsy-AI/agent-apprenticeship
+
+## Apprentice Agents
+
+Selected v0 Apprentice Agents:
+
+* Codex
+* Cursor
+* Claude Code
+* OpenClaw
+* OpenCode
+* Hermes Agent
+* Custom
+
+Agent Apprenticeship auto-detects installed CLIs. If multiple are detected, choose one during setup.
+
+Custom lets you provide a command template:
+
+```bash
+apprentice configure agent custom --command-template "my-agent run --workspace {workspace} --prompt-file {prompt_file}"
+```
+
+## Mentor Model Providers
+
+Store local keys in:
+
+```text
+~/.agent-apprenticeship/.env.local
+```
+
+Example:
+
+```bash
+OPENAI_API_KEY=""
+ANTHROPIC_API_KEY=""
+GEMINI_API_KEY=""
+OPENROUTER_API_KEY=""
+```
+
+Configure:
+
+```bash
+apprentice configure model
+apprentice doctor
+```
+
+## Mentor Modes
+
+```bash
+apprentice run "..." --mentor-mode model-assisted
+apprentice run "..." --mentor-mode expert-led
+apprentice run "..." --mentor-mode hybrid
+```
+
+* `model-assisted`: Mentor Model Provider handles the mentor loop.
+* `expert-led`: human expert checkpoints guide the mentor loop.
+* `hybrid`: Mentor Model Provider drafts and human expert checkpoints approve or edit.
+
+## Seed Dataset
+
+The seed dataset is included under:
+
+```text
+seed_dataset/
+```
+
+Explore seed tasks:
+
+```bash
+apprentice ecosystem list
+apprentice ecosystem search cloud
+apprentice ecosystem inspect aa-seed-task-501
+apprentice ecosystem pull aa-seed-task-501
+```
+
+## Ecosystem Learning
+
+Create Experience Packs from ecosystem experience:
+
+```bash
+apprentice learn create aa-seed-task-501
+apprentice learn preview <pack_id>
+apprentice learn replay <pack_id>
+apprentice learn keep <pack_id>
+apprentice run "Create a related incident response checklist." --experience-pack <pack_id>
+apprentice learn revert <pack_id>
+```
+
+Use active packs explicitly:
+
+```bash
+apprentice run "..." --use-active-experience-packs
+apprentice run "..." --no-experience-packs
+```
+
+## Contribution Bundles
+
+Runs produce Contribution Bundles.
+
+Contribute one to the public ecosystem:
+
+```bash
+apprentice ecosystem contribute <bundle_path>
+apprentice bundle contribute <bundle_path>
+```
+
+Public ecosystem:
+
+https://github.com/Forsy-AI/agent-apprenticeship
+
+## Ecosystem Auto-Share
+
+Default mode is Manual.
+
+```bash
+apprentice ecosystem configure --repo Forsy-AI/agent-apprenticeship
+apprentice ecosystem configure --auto-share manual
+apprentice ecosystem configure --auto-share ask
+apprentice ecosystem configure --auto-share automatic
+apprentice ecosystem status
+```
+
+Requirements:
+
+* GitHub CLI installed
+* `gh` authenticated
+* ecosystem repo configured
+
+## Search, Inspect, Pull
+
+Discover and export ecosystem experience:
+
+```bash
+apprentice ecosystem search <query>
+apprentice ecosystem inspect <id>
+apprentice ecosystem pull <id>
+```
+
+## Public Repo Structure
+
+```text
+seed_dataset/
+ecosystem/
+ecosystem/contributions/
+schemas/
+examples/
+```
+
+## Development Commands
+
+```bash
+.venv/bin/python -m pytest -q tests
+PYTHONPATH=src .venv/bin/python -m compileall -q src tests scripts examples
+bash scripts/export_public_repo.sh
+```

package/bin/agent-apprenticeship.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const packageRoot = path.resolve(__dirname, "..");
+const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+
+function userHome() {
+  return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+
+function expandHome(value) {
+  if (!value) return value;
+  if (value === "~") return userHome();
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return path.join(userHome(), value.slice(2));
+  }
+  return value;
+}
+
+function appHome() {
+  return path.resolve(expandHome(process.env.AA_HOME || path.join(userHome(), ".agent-apprenticeship")));
+}
+
+function runCandidate(command, args) {
+  return spawnSync(command, args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    env: process.env
+  });
+}
+
+function pythonIsUsable(command) {
+  const check = runCandidate(command, [
+    "-c",
+    "import sys; raise SystemExit(0 if sys.version_info >= (3, 11) else 1)"
+  ]);
+  return !check.error && check.status === 0;
+}
+
+function findPython() {
+  const candidates = [];
+  if (process.env.AA_PYTHON) candidates.push(process.env.AA_PYTHON);
+  candidates.push("python3", "python");
+  for (const candidate of candidates) {
+    if (pythonIsUsable(candidate)) return candidate;
+  }
+  return null;
+}
+
+function venvPython(venvDir) {
+  return process.platform === "win32"
+    ? path.join(venvDir, "Scripts", "python.exe")
+    : path.join(venvDir, "bin", "python");
+}
+
+function runQuiet(command, args, label) {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    env: process.env
+  });
+  if (result.error || result.status !== 0) {
+    console.error(`Agent Apprenticeship runtime setup failed while trying to ${label}.`);
+    if (result.error) console.error(String(result.error.message || result.error));
+    const out = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+    if (out) console.error(out);
+    process.exit(result.status || 1);
+  }
+}
+
+function ensureRuntime(python) {
+  const venvDir = path.resolve(process.env.AA_NPM_VENV || path.join(appHome(), "npm-venv", packageJson.version));
+  const py = venvPython(venvDir);
+  const markerPath = path.join(venvDir, ".agent-apprenticeship-npm.json");
+  try {
+    const marker = JSON.parse(fs.readFileSync(markerPath, "utf8"));
+    if (marker.packageVersion === packageJson.version && fs.existsSync(py)) {
+      return py;
+    }
+  } catch (_) {
+    // Fall through and rebuild the runtime.
+  }
+
+  console.error("Installing Agent Apprenticeship runtime...");
+  fs.rmSync(venvDir, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(venvDir), { recursive: true });
+  runQuiet(python, ["-m", "venv", venvDir], "create the Python environment");
+  runQuiet(py, ["-m", "pip", "install", "--disable-pip-version-check", "--no-input", "--quiet", packageRoot], "install the Python package");
+  fs.writeFileSync(markerPath, JSON.stringify({
+    packageName: packageJson.name,
+    packageVersion: packageJson.version,
+    installedAt: new Date().toISOString()
+  }, null, 2) + "\n");
+  console.error("Done.");
+  return py;
+}
+
+function runCli(python, args, usePackagedSource) {
+  const env = { ...process.env };
+  if (usePackagedSource) {
+    const srcPath = path.join(packageRoot, "src");
+    env.PYTHONPATH = env.PYTHONPATH ? `${srcPath}${path.delimiter}${env.PYTHONPATH}` : srcPath;
+  }
+  const result = spawnSync(python, ["-m", "agent_apprenticeship_trace.cli", ...args], {
+    stdio: "inherit",
+    env
+  });
+  if (result.error) {
+    console.error(`Failed to start Agent Apprenticeship: ${result.error.message || result.error}`);
+    process.exit(1);
+  }
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+const python = findPython();
+if (!python) {
+  console.error("Agent Apprenticeship requires Python 3.11 or newer.");
+  console.error("Install python3 or set AA_PYTHON=/path/to/python.");
+  process.exit(1);
+}
+
+if (process.env.AA_NPM_USE_SYSTEM_PYTHON === "1") {
+  runCli(python, process.argv.slice(2), true);
+}
+
+runCli(ensureRuntime(python), process.argv.slice(2), false);

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "agent-apprenticeship",
+  "version": "0.1.0",
+  "description": "The living ecosystem for AI agents learning from real-world work through iterative loops and training-signal exchange.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Forsy-AI/agent-apprenticeship.git"
+  },
+  "bin": {
+    "agent-apprenticeship": "bin/agent-apprenticeship.js",
+    "apprentice": "bin/agent-apprenticeship.js"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+    "src/agent_apprenticeship_trace",
+    "bin"
+  ],
+  "scripts": {
+    "test": ".venv/bin/python -m pytest -q tests",
+    "pack": "npm pack --dry-run",
+    "prepack": "find src bin -name __pycache__ -type d -prune -exec rm -rf {} + && find src bin -name '*.pyc' -delete",
+    "smoke": "PATH=./.venv/bin:$PATH AA_NPM_USE_SYSTEM_PYTHON=1 node ./bin/agent-apprenticeship.js --help"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-apprenticeship"
+version = "0.1.0"
+description = "Open framework for turning real agent work into transferable agent experience"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["pydantic>=2", "typer>=0.12", "openai>=1.0"]
+
+[project.optional-dependencies]
+llm = ["openai>=1.0"]
+test = ["pytest>=8"]
+
+[project.scripts]
+apprentice = "agent_apprenticeship_trace.cli:main"
+agent-apprenticeship = "agent_apprenticeship_trace.cli:main"
+aa-trace = "agent_apprenticeship_trace.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

package/src/agent_apprenticeship_trace/__init__.py

@@ -0,0 +1,2 @@
+"""Agent Apprenticeship framework."""
+__version__ = "0.1.0"

package/src/agent_apprenticeship_trace/actual_outputs_normalizer.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+import json
+from pathlib import Path
+from typing import Any
+from pydantic import BaseModel, Field
+from .schemas import ActualOutputs
+from .io import write_json
+
+CANONICAL_ACTUAL_FIELDS = set(ActualOutputs.model_fields.keys())
+
+class ActualOutputsNormalizationContext(BaseModel):
+    task_id: str
+    attempt_id: str
+    attempt_kind: str
+    package_root: Path
+    required_artifacts: list[str] = Field(default_factory=list)
+
+class ActualOutputsNormalizationReport(BaseModel):
+    task_id: str
+    attempt_id: str
+    attempt_kind: str
+    raw_outputs_ref: str | None = None
+    invalid_outputs_ref: str | None = None
+    normalized_outputs_ref: str | None = None
+    canonical_outputs_ref: str | None = None
+    actual_outputs_schema_valid: bool = False
+    actual_outputs_normalized: bool = False
+    actual_outputs_fallback: bool = False
+    actual_outputs_raw_count: int = 0
+    actual_outputs_normalized_count: int = 0
+    actual_outputs_schema_valid_count: int = 0
+    actual_outputs_fallback_count: int = 0
+    actual_outputs_inferred_artifact_count: int = 0
+    actual_outputs_discarded_field_count: int = 0
+    validation_errors: list[str] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+    metadata_json: dict[str, Any] = Field(default_factory=dict)
+
+class ActualOutputsNormalizationResult(BaseModel):
+    actual_outputs: dict[str, Any] | None = None
+    report: ActualOutputsNormalizationReport
+    fallback_required: bool = False
+    parse_error: str | None = None
+
+
+def _as_list(v: Any) -> list[Any]:
+    if v is None:
+        return []
+    if isinstance(v, list):
+        return v
+    return [v]
+
+
+def _compact(v: Any, max_len: int=2000) -> str:
+    if v is None:
+        return ''
+    if isinstance(v, str):
+        return v[:max_len]
+    try:
+        return json.dumps(v, sort_keys=True)[:max_len]
+    except Exception:
+        return str(v)[:max_len]
+
+
+def _validation_errors(exc: Exception) -> list[str]:
+    if hasattr(exc, 'errors'):
+        try:
+            return [_compact(e, 2000) for e in exc.errors()]
+        except Exception:
+            pass
+    return [str(exc)]
+
+
+def _norm_ref(ref: str, attempt_kind: str) -> str:
+    ref=str(ref)
+    if ref.startswith(f'attempts/{attempt_kind}/'):
+        return ref
+    if ref.startswith('artifacts/'):
+        return f'attempts/{attempt_kind}/{ref}'
+    if '/' not in ref:
+        return f'attempts/{attempt_kind}/artifacts/{ref}'
+    return ref
+
+
+def _artifact_paths_from_raw(raw: dict[str, Any]) -> dict[str, Any]:
+    found={}
+    for k,v in raw.items():
+        if isinstance(k, str) and (k.startswith('artifacts/') or '/artifacts/' in k):
+            found[k]=v
+    return found
+
+
+def _scan_existing_artifacts(ctx: ActualOutputsNormalizationContext) -> list[str]:
+    artifact_dir=ctx.package_root/'attempts'/ctx.attempt_kind/'artifacts'
+    refs=[]
+    if artifact_dir.exists():
+        required_names={Path(x).name for x in ctx.required_artifacts if x}
+        files=[p for p in artifact_dir.iterdir() if p.is_file()]
+        if required_names:
+            files=[p for p in files if p.name in required_names] or files
+        refs=[f'attempts/{ctx.attempt_kind}/artifacts/{p.name}' for p in files]
+    return refs
+
+
+def _extract_refs(raw: dict[str, Any], ctx: ActualOutputsNormalizationContext) -> tuple[list[str], dict[str, Any], list[str]]:
+    warnings=[]
+    refs=[]
+    original_path_fields=_artifact_paths_from_raw(raw)
+    for k in original_path_fields:
+        refs.append(_norm_ref(k, ctx.attempt_kind))
+    for key in ['deliverable_refs','artifact_refs','files_created','outputs','artifacts','output_files']:
+        val=raw.get(key)
+        if isinstance(val, dict):
+            for k in val:
+                if isinstance(k, str) and (k.startswith('artifacts/') or '/artifacts/' in k or '.' in Path(k).name):
+                    refs.append(_norm_ref(k, ctx.attempt_kind))
+        else:
+            for item in _as_list(val):
+                if isinstance(item, str):
+                    refs.append(_norm_ref(item, ctx.attempt_kind))
+    existing=_scan_existing_artifacts(ctx)
+    refs.extend(existing)
+    dedup=[]
+    for r in refs:
+        if r and r not in dedup:
+            dedup.append(r)
+    return dedup, original_path_fields, warnings
+
+
+def normalize_actual_outputs(raw: dict[str, Any] | None, ctx: ActualOutputsNormalizationContext) -> ActualOutputsNormalizationResult:
+    raw = dict(raw or {})
+    report=ActualOutputsNormalizationReport(task_id=ctx.task_id, attempt_id=ctx.attempt_id, attempt_kind=ctx.attempt_kind, actual_outputs_raw_count=1)
+    refs, original_path_fields, warnings = _extract_refs(raw, ctx)
+    original_fields={k:v for k,v in raw.items() if k not in CANONICAL_ACTUAL_FIELDS}
+    raw_status=str(raw.get('status') or '').lower()
+    failure_status=raw_status in {'failed','error','timeout'}
+    status = raw.get('status') if raw.get('status') in {'success','partial','failed','timeout','error'} else None
+    if status is None:
+        status='success' if refs and not failure_status else ('failed' if failure_status else ('partial' if refs else 'failed'))
+    if refs and not failure_status and status == 'failed':
+        status='success'
+    summary=raw.get('output_summary') or raw.get('summary') or raw.get('final_summary') or ('Normalized actual outputs from artifact files.' if refs else 'No canonical actual outputs were produced.')
+    md=dict(raw.get('metadata_json') or {}) if isinstance(raw.get('metadata_json'), dict) else {}
+    if original_fields:
+        md['original_fields']=original_fields
+    if original_path_fields:
+        md['original_artifact_path_fields']=original_path_fields
+    md['raw_actual_outputs']=raw
+    md['actual_outputs_discarded_field_count']=0
+    md['actual_outputs_normalized']=True
+    md['expected_deliverable_items']=[Path(str(x)).name for x in ctx.required_artifacts if x]
+    md['produced_deliverable_items']=[Path(str(x)).name for x in refs]
+    actual={
+        'task_id': str(raw.get('task_id') or ctx.task_id),
+        'attempt_id': str(raw.get('attempt_id') or ctx.attempt_id),
+        'attempt_kind': str(raw.get('attempt_kind') or ctx.attempt_kind),
+        'status': status,
+        'output_summary': str(summary),
+        'primary_output_ref': raw.get('primary_output_ref') or (refs[0] if refs else None),
+        'deliverable_refs': [str(x) for x in (raw.get('deliverable_refs') if isinstance(raw.get('deliverable_refs'), list) else [])] or refs,
+        'final_message_ref': raw.get('final_message_ref') or f'attempts/{ctx.attempt_kind}/final_message.txt',
+        'artifact_refs': [str(x) for x in (raw.get('artifact_refs') if isinstance(raw.get('artifact_refs'), list) else [])] or refs,
+        'files_created': [str(x) for x in (raw.get('files_created') if isinstance(raw.get('files_created'), list) else [])] or refs,
+        'files_modified': [str(x) for x in (raw.get('files_modified') if isinstance(raw.get('files_modified'), list) else [])],
+        'files_deleted': [str(x) for x in (raw.get('files_deleted') if isinstance(raw.get('files_deleted'), list) else [])],
+        'stdout_ref': raw.get('stdout_ref') or f'attempts/{ctx.attempt_kind}/stdout.txt',
+        'stderr_ref': raw.get('stderr_ref') or f'attempts/{ctx.attempt_kind}/stderr.txt',
+        'raw_log_refs': [str(x) for x in (raw.get('raw_log_refs') if isinstance(raw.get('raw_log_refs'), list) else [])] or [f'attempts/{ctx.attempt_kind}/stdout.txt', f'attempts/{ctx.attempt_kind}/stderr.txt', f'attempts/{ctx.attempt_kind}/final_message.txt'],
+        'error_type': raw.get('error_type') if status in {'failed','timeout','error'} else None,
+        'error_message': raw.get('error_message') if status in {'failed','timeout','error'} else None,
+        'metadata_json': md,
+    }
+    try:
+        obj=ActualOutputs.model_validate(actual)
+        normalized=obj.model_dump(mode='json')
+        report.actual_outputs_schema_valid=True
+        report.actual_outputs_schema_valid_count=1
+    except Exception as exc:
+        normalized=actual
+        report.validation_errors.extend(_validation_errors(exc))
+    report.actual_outputs_normalized=True
+    report.actual_outputs_normalized_count=1
+    report.actual_outputs_inferred_artifact_count=len(refs)
+    report.actual_outputs_discarded_field_count=0
+    report.warnings.extend(warnings)
+    return ActualOutputsNormalizationResult(actual_outputs=normalized, report=report, fallback_required=not report.actual_outputs_schema_valid)
+
+
+def repair_actual_outputs_file(path: Path, ctx: ActualOutputsNormalizationContext) -> ActualOutputsNormalizationResult:
+    report=ActualOutputsNormalizationReport(task_id=ctx.task_id, attempt_id=ctx.attempt_id, attempt_kind=ctx.attempt_kind, raw_outputs_ref='actual_outputs.raw.json')
+    if not path.exists():
+        existing=_scan_existing_artifacts(ctx)
+        if existing:
+            result=normalize_actual_outputs({}, ctx)
+            result.report.raw_outputs_ref=None
+            return result
+        report.actual_outputs_fallback=True
+        report.actual_outputs_fallback_count=1
+        report.validation_errors.append('actual_outputs.json missing and no artifact evidence was available')
+        return ActualOutputsNormalizationResult(actual_outputs=None, report=report, fallback_required=True, parse_error='missing actual_outputs.json')
+    text=path.read_text()
+    raw_path=path.with_name('actual_outputs.raw.json')
+    raw_path.write_text(text)
+    try:
+        raw=json.loads(text)
+        if not isinstance(raw, dict):
+            raise ValueError('actual_outputs JSON was not an object')
+    except Exception as exc:
+        report.actual_outputs_fallback=True
+        report.actual_outputs_fallback_count=1
+        report.validation_errors.append(str(exc))
+        return ActualOutputsNormalizationResult(actual_outputs=None, report=report, fallback_required=True, parse_error=str(exc))
+    try:
+        valid=ActualOutputs.model_validate(raw).model_dump(mode='json')
+        result=ActualOutputsNormalizationResult(actual_outputs=valid, report=report)
+        result.report.actual_outputs_raw_count=1
+        result.report.actual_outputs_schema_valid=True
+        result.report.actual_outputs_schema_valid_count=1
+        result.report.actual_outputs_normalized=False
+        result.report.actual_outputs_normalized_count=0
+        result.report.actual_outputs_inferred_artifact_count=len(valid.get('deliverable_refs') or [])
+        return result
+    except Exception as exc:
+        path.with_name('actual_outputs.invalid.json').write_text(text)
+        result=normalize_actual_outputs(raw, ctx)
+        result.report.raw_outputs_ref='actual_outputs.raw.json'
+        result.report.invalid_outputs_ref='actual_outputs.invalid.json'
+        result.report.normalized_outputs_ref='actual_outputs.normalized.json'
+        result.report.canonical_outputs_ref='actual_outputs.json'
+        result.report.validation_errors.extend(_validation_errors(exc))
+        return result
+
+
+def write_actual_outputs_normalization(attempt_dir: Path, result: ActualOutputsNormalizationResult) -> None:
+    if result.actual_outputs is not None:
+        write_json(attempt_dir/'actual_outputs.normalized.json', result.actual_outputs)
+        write_json(attempt_dir/'actual_outputs.json', result.actual_outputs)
+        result.report.normalized_outputs_ref=result.report.normalized_outputs_ref or 'actual_outputs.normalized.json'
+        result.report.canonical_outputs_ref=result.report.canonical_outputs_ref or 'actual_outputs.json'
+    write_json(attempt_dir/'actual_outputs_normalization_report.json', result.report)