# 0005 — The D8 result-vocabulary re-code and its legacy read mapping

## Context

Before P1b's D8 vocabulary re-code, a task's result `target.kind` used
`"prompt"` for a prepared command/agent-LLM result and one shared
`"command"` for every native (shell/script) result, which conflated two
materially different execution shapes under one label and mislabeled an
LLM-routed dispatch as a literal "prompt". D8 renamed the written
vocabulary; the harder problem was that `task_history` is a durable,
already-populated table — existing rows on disk still carry the OLD labels,
and `readTaskHistory` has to keep returning a coherent shape for both
generations of rows forever.

## Decision

Moved verbatim from `src/tasks/run/task-result.ts`'s module header:

> `TaskRunResult` — the shape every dispatch arm returns — plus the small
> cluster of helpers that build one directly: `preparedResultTarget` (the D8
> result-vocabulary projection of a freshly prepared execution),
> `finishDisabledTask` (the disabled-task short-circuit), and
> `exitCodeForStatus` (the OS-scheduler exit-code mapping). `RunTaskOptions`
> — the public options bag `runTask()`, `load-task.ts`, and every dispatch
> arm read from — lives here too, alongside the other public-surface types
> the compat shim (`src/tasks/runner.ts`) re-exports.
>
> D8 (§5.3, §6 F-2): `preparedResultTarget`'s prepared-command arm now
> returns `{kind:"command", engine}` (formerly `{kind:"prompt", engine}`);
> its native arm now returns the bare `{kind:"shell"}` / `{kind:"script"}`
> (formerly one shared `{kind:"command"}`) — the arm-specific `cmd` is
> added by `run-native-task.ts` once it has actually built the argv,
> mirroring the pre-P1b shape where the bare disabled-task projection never
> carried `cmd` either.

And from `src/tasks/run/task-history.ts`'s module header (the WRITE half —
the READ half's mapping rule is kept in the code itself, not moved; see
below):

> The `task_history` read/write boundary: `appendHistory` (write) and
> `readTaskHistory` / `taskHistoryRowToResult` (read).
>
> D8 (spec §5.3, §6 F-2) result-vocabulary re-code, implemented entirely at
> this read/write boundary. WRITE: every row `appendHistory` writes now
> carries `targetVocab: 2` in its metadata, and the new target_kind strings
> ("command" for a prepared command/agent-LLM result, "shell", "script",
> "workflow" unchanged).

## Consequences

- Every NEW row written after D8 is unambiguous — `targetVocab: 2` plus the
  new `target_kind` strings mean a reader never has to guess which
  generation a row belongs to.
- Every OLD row (written before D8, no `targetVocab` marker at all) must
  keep reading correctly forever — this is not a migration that runs once
  and finishes; there is no "convert task_history in place" step, because
  the table is an append-only historical log, not authoring state. The
  read-side mapping rule is therefore a PERMANENT part of the codebase
  (`docs/plans/specs/p4-deletions-closeout.md` row B-51: "it reads old rows
  forever. Deleting it is a review-blocking violation.").
- The exact legacy mapping — kept in `src/tasks/run/task-history.ts` itself
  as a short invariant comment, not summarized here, because a maintainer
  reading `taskHistoryRowToResult` needs it right there — is: a legacy row
  (no `targetVocab` marker) maps `"prompt"` → `{kind:"command", engine}`,
  `"command"` → `{kind:"shell"}`, `"workflow"` unchanged, and anything else
  (including the new vocabulary's own strings written WITHOUT a marker,
  which no production writer ever does) → `"unknown"`. The P0-pinned null
  fallbacks survive: a workflow row's `ref` falls back to `""`, the
  command/prompt arm's `engine` falls back to `null`.
- `SAFE_TASK_ATTEMPT_ERROR_CODES` (`src/tasks/run/attempt-lifecycle.ts`) is a
  related but separate allowlist — it decides which error CODES are safe to
  surface verbatim in a `detail.error` column, not which result-kind
  strings are legal. Do not conflate the two when reading either file.
- **Removed 2026-08-28** (review finding against this phase's own close-out
  spec, `docs/plans/specs/p4-deletions-closeout.md`): `finishDisabledTask`
  and `preparedResultTarget`, quoted above as part of the moved essay, are no
  longer in `src/tasks/run/task-result.ts`. `finishDisabledTask`'s only
  caller — `run-task.ts`'s `shouldSkipUnactivatedTask` — was deleted by the
  SAME phase's P4-N6 (task source v4 has no document-level `enabled` to skip
  at fire time), which left `finishDisabledTask` fully dead; `preparedResultTarget`
  was in turn `finishDisabledTask`'s only caller, so it went dead with it.
  Deleting them also retired the `"disabled"` `TaskRunStatus` member
  `finishDisabledTask` was the sole producer of, and the now-unreachable
  `result.status === "disabled"` branch in `src/commands/tasks/tasks.ts`.
  This does not touch the D8 vocabulary or the legacy read mapping this ADR
  is about — every OTHER dispatch arm still builds its own
  `TaskRunResult.target` per the Decision above, and `task-history.ts`'s read
  side is unchanged.
- **Superseded 2026-09-01**: the "PERMANENT part of the codebase" ruling
  above (row B-51) is overturned. `task_history` is DB-owned data, and the
  legacy->current remap is deterministic and total, so it belongs in a
  one-time schema migration, not three permanently-recurring read-side
  branches (the mapping had been independently re-implemented at
  `src/tasks/run/task-history.ts`, `src/commands/health/improve-metrics.ts`'s
  `isAgentTaskHistoryRow`, and `src/commands/health/windows.ts`). State
  migration `025-task-history-vocabulary-backfill`
  (`src/core/state/migrations.ts`) now rewrites every legacy row's
  `target_kind` (and stamps `targetVocab: 2`) the first time a pre-migration
  state.db is opened by this or a later release; all three read sites were
  deleted and now read `target_kind` directly in the current vocabulary.

## Provenance

- Source: `src/tasks/run/task-result.ts` module header;
  `src/tasks/run/task-history.ts` module header (WRITE half only — the READ
  half's mapping rule stays in the code as a permanent invariant).
- Spec: `docs/plans/specs/p1b-model-extraction.md` §5.3, §6 F-2.
- Extracted: P4 (`docs/plans/specs/p4-deletions-closeout.md` §4.2), 2026-08-27.