@zq-silk/yui 0.15.8 → 0.15.9

package/dist/storage/migrations/artifactsToGit.js

@@ -0,0 +1,338 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, rmSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { externalProgramConfigViolations, managedGitSync, managedGitSyncSucceeds, requireCommitId } from "../../artifacts/managedGit.js";
+import { safePathSegment, safeRelativeArtifactPath, taskArtifactRepoPath, taskArtifactsRoot } from "../../artifacts/artifactPaths.js";
+import { migrateSubmitIntent } from "./submitIntent.js";
+/**
+ * Storage 18 -> 19: retire the DB-owned immutable Artifact table and move every
+ * historical Artifact into its Task's LOCAL Git artifact repository, then
+ * rewrite the Candidate/completion references that pointed at them so they pin
+ * an exact `commit + relativePath` instead of a mutable DB id.
+ *
+ * Two-class ownership (§3.1/§3.7): after v19 the DB is no longer an authority
+ * for file/directory artifacts — the per-Task repo at
+ * `<YUI_HOME>/task-artifacts/<task-id>/` is. This migration is the ONE-TIME
+ * bridge: it reads the soon-to-be-dropped `artifacts` table, reconstructs the
+ * bytes/descriptor as deterministic Git history, and leaves NO dual read/write
+ * surface behind (the table is dropped in the same transaction).
+ *
+ * Determinism & crash-safety. `migrateData` runs INSIDE the outer
+ * `db.transaction`, which better-sqlite3 requires to be synchronous, so this
+ * builds repositories with the synchronous managed-Git runner. Every commit
+ * (including the empty root) is pinned to a date derived purely from the
+ * Artifact data, and identity/message/tree are fixed, so rebuilding the same
+ * table produces byte-identical commit ids. The DB half is atomic (the upgrade
+ * orchestrator backs up `yui.db` and rolls back on any throw); the Git repos
+ * are the only non-transactional side effect, so each Task repo is built in a
+ * staging directory and atomically renamed into place, and a leftover from a
+ * previously rolled-back attempt is replaced by an identical rebuild.
+ *
+ * Boundaries. Managed Git is fully isolated (no remote, no hooks/filters, no
+ * network/file transport, no ambient config — see managedGit). This migration
+ * NEVER re-accesses a Job receipt tool and NEVER fetches a reference locator: it
+ * moves exactly the bytes/descriptor already frozen in the DB. Reference-kind
+ * Artifacts are preserved as history but are never a reference target (they were
+ * never fixed results). Completion strings that are not Artifact ids (e.g.
+ * `turn:<id>` or an explicit URL) are preserved verbatim.
+ */
+/** The single managed branch, mirroring taskArtifactRepository. */
+const ARTIFACT_BRANCH = "main";
+/** Staging root for in-progress repository builds (hidden; never a Task id). */
+const MIGRATION_STAGING = ".yui-artifact-migration";
+/** Deterministic key for the id->reference map (task id + Artifact id). */
+function refKey(taskId, artifactId) {
+    return `${taskId}\u0000${artifactId}`;
+}
+/** Stable JSON: object keys sorted at every depth, so bytes (and thus commit ids) are deterministic. */
+function stableJson(value) {
+    const canonical = (input) => {
+        if (Array.isArray(input))
+            return input.map(canonical);
+        if (input !== null && typeof input === "object") {
+            const source = input;
+            const result = {};
+            for (const key of Object.keys(source).sort())
+                result[key] = canonical(source[key]);
+            return result;
+        }
+        return input;
+    };
+    return `${JSON.stringify(canonical(value), null, 2)}\n`;
+}
+/** The metadata record written for every migrated Artifact (content lives beside it, if any). */
+function artifactRecord(artifact) {
+    const { content: _content, ...rest } = artifact;
+    return { ...rest, migratedFrom: { store: "artifacts", storageVersion: 18 } };
+}
+export function migrateArtifactsToGit(db) {
+    const home = dirname(db.name);
+    // A pure in-memory database (tests) has no Home to host repositories; there
+    // are no rows to move in that case, so treat it as an empty migration.
+    const rows = db.prepare("SELECT task_id, id, payload FROM artifacts").all();
+    const migrated = new Map();
+    if (rows.length > 0) {
+        if (db.name === ":memory:" || db.name.length === 0) {
+            throw new Error("Cannot migrate Artifacts to Git without an on-disk Home.");
+        }
+        const byTask = new Map();
+        for (const row of rows) {
+            const artifact = JSON.parse(row.payload);
+            const list = byTask.get(row.task_id) ?? [];
+            list.push(artifact);
+            byTask.set(row.task_id, list);
+        }
+        // Deterministic Task order, then deterministic Artifact order within a Task.
+        for (const taskId of [...byTask.keys()].sort()) {
+            const artifacts = byTask.get(taskId).slice().sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+            buildTaskRepository(home, taskId, artifacts, migrated);
+        }
+        // Every Task repo has been atomically renamed out of staging; remove the now
+        // empty staging root so it never masquerades as an entry under task-artifacts.
+        rmSync(join(taskArtifactsRoot(home), MIGRATION_STAGING), { recursive: true, force: true });
+    }
+    rewriteCandidateRefs(db, migrated);
+    rewriteCompletionRefs(db, migrated);
+    // No dual surface: the DB is no longer an authority for file artifacts.
+    db.exec("DROP TABLE artifacts");
+    // Requirement A's independent, deterministic, idempotent backfill runs LAST,
+    // inside this same outer transaction. It touches only events + id_sequences.
+    migrateSubmitIntent(db);
+}
+/**
+ * Build one Task's artifact repository from its historical Artifacts and record
+ * a frozen reference for each. Built in staging, then atomically swapped in.
+ */
+function buildTaskRepository(home, taskId, artifacts, migrated) {
+    const root = taskArtifactsRoot(home);
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    const stagingRoot = join(root, MIGRATION_STAGING);
+    mkdirSync(stagingRoot, { recursive: true, mode: 0o700 });
+    const staging = join(stagingRoot, safePathSegment(taskId, "Task id"));
+    // Discard any partial staging from a previously interrupted attempt.
+    rmSync(staging, { recursive: true, force: true });
+    mkdirSync(staging, { recursive: true, mode: 0o700 });
+    // Root commit date: the earliest Artifact timestamp, so the whole history is a
+    // pure function of the data (no wall-clock, reproducible commit ids).
+    const rootDate = artifacts.reduce((earliest, artifact) => (artifact.createdAt < earliest ? artifact.createdAt : earliest), artifacts[0].createdAt);
+    managedGitSync(staging, ["init", "-b", ARTIFACT_BRANCH]);
+    managedGitSync(staging, ["commit", "--allow-empty", "-m", "init artifact repo"], {
+        commitDates: { author: rootDate, committer: rootDate }
+    });
+    assertManagedBoundary(taskId, staging);
+    for (const artifact of artifacts) {
+        const ref = commitArtifact(staging, artifact);
+        migrated.set(refKey(taskId, artifact.id), ref);
+    }
+    const builtHead = requireCommitId(managedGitSync(staging, ["rev-parse", "HEAD^{commit}"]));
+    // Adopt the freshly built repository WITHOUT ever destroying unknown data.
+    const finalPath = taskArtifactRepoPath(home, taskId);
+    adoptBuiltRepository(taskId, staging, finalPath, builtHead);
+}
+/**
+ * Move the freshly built repository into place WITHOUT ever clearing an unknown
+ * existing directory (fail-closed; no auto-repair).
+ *
+ * - No existing dir: atomic rename — there is nothing to lose.
+ * - Existing dir that is PROVABLY this exact build: a remnant of a previously
+ *   rolled-back attempt. Keep it and discard the redundant staging build. Proof
+ *   is its HEAD commit id (a hash over the whole tree AND commit history,
+ *   reproducible only by this deterministic builder from this exact data), plus
+ *   a clean working tree and the managed boundary (no remote / no
+ *   external-program config) — so a dir with extra or modified files is NOT a
+ *   remnant even if HEAD coincides.
+ * - Anything else: STOP. Preserve the existing directory and the staging build
+ *   untouched and throw, so the outer transaction rolls the DB back and an
+ *   operator can inspect. Never overwrite, clear, or auto-repair.
+ */
+function adoptBuiltRepository(taskId, staging, finalPath, builtHead) {
+    if (!existsSync(finalPath)) {
+        renameSync(staging, finalPath);
+        assertManagedBoundary(taskId, finalPath);
+        return;
+    }
+    if (isProvenIdenticalRemnant(finalPath, builtHead)) {
+        // The existing repo already IS the intended, verified result; drop the build.
+        rmSync(staging, { recursive: true, force: true });
+        return;
+    }
+    throw new Error(`Refusing to overwrite existing artifact directory for ${taskId} at ${finalPath}: it is not a ` +
+        `proven byte-identical remnant of this migration (different HEAD, working-tree changes, or an ` +
+        `external remote/config). No data was modified; resolve it manually and re-run the upgrade.`);
+}
+/**
+ * True ONLY if `finalPath` is a managed Git repo whose HEAD equals `builtHead`,
+ * whose working tree is clean, and which is within the managed boundary. Any
+ * failure (not a repo, differing HEAD, dirty tree, remote/external config) means
+ * "not a remnant", so the caller fails closed rather than deleting it. Read-only.
+ *
+ * ORDER MATTERS: the managed-boundary check (remote + config scan — reads that
+ * never run a filter) runs BEFORE `git status`. `git status` re-hashes a
+ * same-size modified file through a `clean` filter to decide if it really
+ * differs, so running status first on a tampered repo could execute an external
+ * program before we ever reject it. The boundary scan also rejects config
+ * INCLUSION entry points, so a filter hidden behind `include.*` is refused here
+ * too — before status can follow the include.
+ */
+function isProvenIdenticalRemnant(finalPath, builtHead) {
+    if (!managedGitSyncSucceeds(finalPath, ["rev-parse", "--is-inside-work-tree"]))
+        return false;
+    // Fail closed on any remote or external-program/inclusion config BEFORE the
+    // first working-tree inspection, so no `clean`/`smudge` filter can run.
+    if (!isWithinManagedBoundary(finalPath))
+        return false;
+    let head;
+    try {
+        head = requireCommitId(managedGitSync(finalPath, ["rev-parse", "HEAD^{commit}"]));
+    }
+    catch {
+        return false;
+    }
+    // A matching HEAD proves the entire committed history; a clean tree proves
+    // nothing was added or modified on top of that history. Only now that the
+    // boundary is proven is it safe to let `git status` touch the working tree.
+    if (head !== builtHead)
+        return false;
+    if (managedGitSync(finalPath, ["status", "--porcelain=v1", "--untracked-files=all", "-z"]).length > 0) {
+        return false;
+    }
+    return true;
+}
+/** Write one Artifact's files, commit exactly them, and return its frozen reference. */
+function commitArtifact(repoPath, artifact) {
+    const idSegment = safePathSegment(artifact.id, "Artifact id");
+    const base = `migrated/${idSegment}`;
+    const recordPath = safeRelativeArtifactPath(`${base}/record.json`);
+    const files = [
+        { relativePath: recordPath, bytes: Buffer.from(stableJson(artifactRecord(artifact)), "utf8") }
+    ];
+    let target = recordPath;
+    let digest;
+    if ((artifact.kind === "content" || artifact.kind === "receipt") && typeof artifact.content === "string") {
+        const contentPath = safeRelativeArtifactPath(`${base}/content`);
+        const bytes = Buffer.from(artifact.content, "utf8");
+        files.push({ relativePath: contentPath, bytes });
+        target = contentPath;
+        // sha256 of the exact committed bytes; equals the old ref's content digest.
+        digest = createHash("sha256").update(bytes).digest("hex");
+    }
+    for (const file of files) {
+        const absolute = join(repoPath, file.relativePath);
+        mkdirSync(dirname(absolute), { recursive: true, mode: 0o700 });
+        writeFileSync(absolute, file.bytes, { mode: 0o600 });
+    }
+    const pathspecs = files.map((file) => file.relativePath);
+    managedGitSync(repoPath, ["add", "--", ...pathspecs]);
+    managedGitSync(repoPath, ["commit", "--only", "-m", `migrate artifact ${artifact.id}`, "--", ...pathspecs], {
+        commitDates: { author: artifact.createdAt, committer: artifact.createdAt }
+    });
+    const commit = requireCommitId(managedGitSync(repoPath, ["rev-parse", "HEAD^{commit}"]));
+    // A reference target is never a reference-kind Artifact (those were never
+    // fixed results), but such Artifacts are still preserved above as history.
+    return artifact.kind === "reference"
+        ? { commit, relativePath: recordPath }
+        : { commit, relativePath: target, ...(digest === undefined ? {} : { digest }) };
+}
+/** Verify a freshly built repository is within the managed boundary; throw otherwise. */
+function assertManagedBoundary(taskId, repoPath) {
+    const remotes = managedGitSync(repoPath, ["remote"]).split("\n").map((line) => line.trim()).filter(Boolean);
+    if (remotes.length > 0) {
+        throw new Error(`Migrated artifact repository for ${taskId} unexpectedly has a remote: ${remotes.join(", ")}.`);
+    }
+    const configViolations = externalProgramConfigViolations(managedGitSync(repoPath, ["config", "--local", "--list", "-z"]));
+    if (configViolations.length > 0) {
+        throw new Error(`Migrated artifact repository for ${taskId} has repo-local config that can run external ` +
+            `programs: ${configViolations.join(", ")}.`);
+    }
+    // A managed repo must respond to a trivial plumbing query; fail closed otherwise.
+    if (!managedGitSyncSucceeds(repoPath, ["rev-parse", "--is-inside-work-tree"])) {
+        throw new Error(`Migrated artifact repository for ${taskId} did not initialize correctly.`);
+    }
+}
+/** Read-only managed-boundary predicate (no remote, no external-program config). Never throws. */
+function isWithinManagedBoundary(repoPath) {
+    const remotes = managedGitSync(repoPath, ["remote"]).split("\n").map((line) => line.trim()).filter(Boolean);
+    if (remotes.length > 0)
+        return false;
+    return externalProgramConfigViolations(managedGitSync(repoPath, ["config", "--local", "--list", "-z"])).length === 0;
+}
+/** An upgradable Candidate reference resolved to its exact commit and path. */
+function upgradeCandidateRef(taskId, ref, migrated) {
+    if (ref === null || typeof ref !== "object")
+        return ref;
+    const source = ref;
+    // Already a commit-pinned Git reference (defensive; a fresh v18 row is never this).
+    if (typeof source.commit === "string" && typeof source.relativePath === "string")
+        return ref;
+    const refTaskId = typeof source.taskId === "string" ? source.taskId : taskId;
+    const artifactId = source.artifactId;
+    if (typeof artifactId !== "string") {
+        throw new Error("Candidate artifact reference has no artifact id to migrate.");
+    }
+    const found = migrated.get(refKey(refTaskId, artifactId));
+    if (found === undefined) {
+        throw new Error(`Candidate artifact reference has no migrated Artifact: ${refTaskId}/${artifactId}.`);
+    }
+    return {
+        taskId: refTaskId,
+        commit: found.commit,
+        relativePath: found.relativePath,
+        ...(found.digest === undefined ? {} : { digest: found.digest })
+    };
+}
+/** Rewrite Candidate artifactRefs in work_items payloads (and the defensive candidate table). */
+function rewriteCandidateRefs(db, migrated) {
+    for (const row of db.prepare("SELECT task_id, work_item_id, payload FROM work_items").all()) {
+        const item = JSON.parse(row.payload);
+        if (!Array.isArray(item.candidates))
+            continue;
+        item.candidates = item.candidates.map((candidate) => {
+            if (candidate === null || typeof candidate !== "object")
+                return candidate;
+            const record = candidate;
+            if (!Array.isArray(record.artifactRefs))
+                return candidate;
+            return {
+                ...record,
+                artifactRefs: record.artifactRefs.map((ref) => upgradeCandidateRef(row.task_id, ref, migrated))
+            };
+        });
+        const next = JSON.stringify(item);
+        if (next !== row.payload) {
+            db.prepare("UPDATE work_items SET payload = ? WHERE task_id = ? AND work_item_id = ?")
+                .run(next, row.task_id, row.work_item_id);
+        }
+    }
+    // The dedicated candidate table is not written by the current runtime, but a
+    // historical row must still migrate rather than be left with a stale shape.
+    for (const row of db.prepare("SELECT task_id, candidate_id, payload FROM work_item_candidates").all()) {
+        const candidate = JSON.parse(row.payload);
+        if (!Array.isArray(candidate.artifactRefs))
+            continue;
+        candidate.artifactRefs = candidate.artifactRefs.map((ref) => upgradeCandidateRef(row.task_id, ref, migrated));
+        const next = JSON.stringify(candidate);
+        if (next !== row.payload) {
+            db.prepare("UPDATE work_item_candidates SET payload = ? WHERE task_id = ? AND candidate_id = ?")
+                .run(next, row.task_id, row.candidate_id);
+        }
+    }
+}
+/** Rewrite completion artifact refs (string ids) into commit-pinned Git strings. */
+function rewriteCompletionRefs(db, migrated) {
+    for (const row of db.prepare("SELECT task_id, payload FROM task_records").all()) {
+        const task = JSON.parse(row.payload);
+        if (!Array.isArray(task.completionArtifactRefs))
+            continue;
+        task.completionArtifactRefs = task.completionArtifactRefs.map((ref) => {
+            if (typeof ref !== "string" || ref.startsWith("git:"))
+                return ref;
+            const found = migrated.get(refKey(row.task_id, ref));
+            // Preserve non-Artifact completion strings (e.g. turn:<id> or a URL) verbatim.
+            return found === undefined ? ref : `git:${found.commit}:${found.relativePath}`;
+        });
+        const next = JSON.stringify(task);
+        if (next !== row.payload) {
+            db.prepare("UPDATE task_records SET payload = ? WHERE task_id = ?").run(next, row.task_id);
+        }
+    }
+}

package/dist/storage/migrations/submitIntent.js

@@ -0,0 +1,126 @@
+import { createTaskEvent } from "../../event/taskEvent.js";
+/**
+ * Storage 18 -> 19 data step for task-32 Requirement A (submit intent & Draft
+ * auto-routing).
+ *
+ * This helper is INDEPENDENT, deterministic and idempotent. The unified 18 -> 19
+ * migration owned by the artifacts WorkItem REGISTERS it (as its `migrateData`)
+ * and bumps `CURRENT_STORAGE_VERSION`; this module neither registers a second
+ * migration nor changes any schema.
+ *
+ * Requirement A adds three optional fields inside `messages.payload`, all part of
+ * this same 18 -> 19 contract even though each is optional — "optional" governs a
+ * single record's shape, not the Home compatibility line, so the version
+ * transition is still declared here and carried by the unified migration:
+ *
+ *  - `intent` (record | discuss | develop): an absent value already reads as
+ *    `discuss` (never `develop`), so historical Messages need no rewrite.
+ *  - `submissionKey`: the client-chosen idempotency key. Only ever set going
+ *    forward; NO historical key is fabricated (task-32 §2.3, message review), so
+ *    old Messages stay keyless and non-idempotent exactly as before.
+ *  - `submissionReceipt`: the frozen disposition a keyed submission replays from.
+ *    Written only alongside a new `submissionKey`, so it too never appears on
+ *    historical data.
+ *
+ * Because none of the three needs a value backfilled onto old rows, the only data
+ * step this migration performs is the planning-entered reconstruction below.
+ *
+ * The one fact old data cannot express is "this Draft already entered planning".
+ * Before Requirement A a Leader-waking user/operator submission on a Draft WAS
+ * the planning discussion, but it left no `task.planning-entered` fact because
+ * that event type did not exist. After the upgrade `develop` auto-activates an
+ * *unplanned* Draft; without this step a Draft that was mid-discussion would be
+ * mis-read as unplanned and snatched into auto-activation (task-32 §2.2, §4).
+ *
+ * So for every Draft that received at least one legitimate historical planning
+ * submission this appends exactly one `task.planning-entered` event, which makes
+ * {@link draftHasEnteredPlanning} derive `true` and routes a later develop to
+ * manual activation. A qualifying submission is an *unaddressed* user/operator
+ * Message that was not save-only (`wakePolicy !== "none"`) — byte-for-byte the
+ * same shape the new discuss path routes through the shared submission service.
+ *
+ * This is deliberately the conservative direction: it can only ever make develop
+ * MORE cautious, never activate a Draft it should not. Save-only Messages (old
+ * `wakePolicy === "none"`, the shape `record` now names) are excluded, so a Draft
+ * that only ever recorded context stays legitimately unplanned and its first
+ * develop may still auto-activate. Non-Draft Tasks are skipped because
+ * {@link draftHasEnteredPlanning} answers only about Drafts, and Activation
+ * requests are left untouched — a legacy request's absent `origin` is the
+ * truthful marker that it stays behind explicit activation.
+ */
+export function migrateSubmitIntent(db) {
+    const drafts = db.prepare("SELECT task_id FROM tasks_catalog WHERE status = 'draft'").all();
+    if (drafts.length === 0)
+        return;
+    const listMessages = db.prepare("SELECT payload FROM messages WHERE task_id = ? ORDER BY seq ASC");
+    const listEventRows = db.prepare("SELECT event_id, type FROM events WHERE task_id = ?");
+    const readHighWater = db.prepare("SELECT high_water FROM id_sequences WHERE task_id = ? AND kind = 'event'");
+    // Advance the per-Task event high-water to exactly the id we just consumed, so
+    // the runtime keeps allocating strictly above every migrated event (mirrors
+    // sqliteStore's id_sequences bookkeeping).
+    const upsertHighWater = db.prepare(`INSERT INTO id_sequences (task_id, kind, high_water) VALUES (?, 'event', ?)
+     ON CONFLICT(task_id, kind) DO UPDATE SET high_water = ?`);
+    const insertEvent = db.prepare("INSERT INTO events (task_id, event_id, type, occurred_at, payload) VALUES (?, ?, ?, ?, ?)");
+    for (const { task_id: taskId } of drafts) {
+        const eventRows = listEventRows.all(taskId);
+        // Idempotent: a Draft that already carries the fact (from a prior run of this
+        // migration, or from a real runtime planning entry) is left untouched.
+        if (eventRows.some((row) => row.type === PLANNING_ENTERED_EVENT_TYPE))
+            continue;
+        const entry = firstPlanningSubmission(listMessages.all(taskId));
+        if (entry === undefined)
+            continue;
+        // Allocate the next event id from the greater of the recorded high-water and
+        // the largest event id actually present, so a fixture or historical database
+        // whose id_sequences lags the events table can never produce a colliding id.
+        const highWater = readHighWater.get(taskId)?.high_water ?? 0;
+        const maxEventSeq = eventRows.reduce((max, row) => Math.max(max, eventSequence(row.event_id)), 0);
+        const seq = Math.max(highWater, maxEventSeq) + 1;
+        // Build through the shared constructor so a migrated event is byte-identical
+        // in shape to one the shared submission service writes at runtime, and dated
+        // to the historical submission rather than the wall-clock upgrade moment.
+        const event = createTaskEvent(`event-${seq}`, taskId, PLANNING_ENTERED_EVENT_TYPE, { messageId: entry.id, intent: "discuss", derivedBy: MIGRATION_PROVENANCE }, new Date(entry.createdAt));
+        insertEvent.run(taskId, event.id, event.type, event.createdAt, JSON.stringify(event));
+        upsertHighWater.run(taskId, seq, seq);
+    }
+}
+/**
+ * The never-compacted event type recording a Draft entered planning. Inlined as a
+ * literal rather than imported so this released migration stays frozen against a
+ * future runtime rename of the constant; `TASK_PLANNING_ENTERED_EVENT` is the
+ * runtime owner, and a tripwire test asserts the two never diverge.
+ */
+const PLANNING_ENTERED_EVENT_TYPE = "task.planning-entered";
+/** Marks the event as reconstructed by this migration, for later audit. */
+const MIGRATION_PROVENANCE = "submit-intent-migration";
+/**
+ * The earliest Message on a Draft that represents a historical planning
+ * submission, or `undefined` if the Draft only ever recorded save-only context.
+ *
+ * A qualifying Message is an unaddressed (`recipient === undefined`) user or
+ * operator Message whose wake policy was not `none`. An absent wake policy
+ * qualifies: before Requirement A that was the default Leader-waking submission,
+ * exactly the shape an omitted intent normalizes to `discuss` today.
+ */
+function firstPlanningSubmission(rows) {
+    for (const row of rows) {
+        const message = JSON.parse(row.payload);
+        if (message.kind !== "user" && message.kind !== "operator")
+            continue;
+        if (message.recipient !== undefined)
+            continue; // an addressed continuation, not a submission
+        if (message.wakePolicy === "none")
+            continue; // old save-only == record, never planning
+        if (typeof message.id !== "string")
+            continue;
+        if (typeof message.createdAt !== "string")
+            continue;
+        return { id: message.id, createdAt: message.createdAt };
+    }
+    return undefined;
+}
+/** The numeric suffix of an `event-<n>` id, or 0 for any unexpected shape. */
+function eventSequence(eventId) {
+    const match = /^event-(\d+)$/.exec(eventId);
+    return match === null ? 0 : Number.parseInt(match[1], 10);
+}

package/dist/storage/sqliteSchema.js

@@ -23,6 +23,7 @@
 import { createHash } from "node:crypto";
 import { REMOVE_RUNTIME_GENERATION_SQL, removeRuntimeGenerationRecords } from "./migrations/removeRuntimeGeneration.js";
 import { migrateAgentRunContract } from "./migrations/agentRunContract.js";
+import { migrateArtifactsToGit } from "./migrations/artifactsToGit.js";
 import { CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION } from "./storageVersions.js";
 /** Telemetry retention bounds (§4.4). Open question 3 in §11; defaults from the design. */
 export const TELEMETRY_KEEP_PER_RUN = 200;
@@ -1117,6 +1118,31 @@ UPDATE review_rounds SET payload = json_set(payload, '$.executionGroup.lanes', j
         // now retain explicit replacement intent; OS owner records may identify
         // the dedicated execution child, independently of a disposable Host.
         sql: "SELECT 1; -- Replacement intent, independent retained native control evidence/process custody, and optional fixed TaskWake refs"
+    },
+    {
+        version: 19,
+        name: "task-artifacts-local-git",
+        introducedIn: "0.16.0",
+        // Retire the DB-owned immutable Artifact store: file/directory artifacts now
+        // live in a per-Task local Git repository, referenced by a self-certifying
+        // `commit + relativePath`. The whole rewrite is payload work that must READ
+        // the `artifacts` table before it is dropped, so it runs entirely in
+        // `migrateData` (which executes after this `sql`) — the table is dropped
+        // there, last, once its rows have been moved. Requirement A's independent,
+        // deterministic submit-intent backfill (events + id_sequences only) is the
+        // final step inside that same transaction. This `sql` is intentionally a
+        // no-op: dropping the table here would destroy the rows before they move.
+        //
+        // The 18->19 contract also DECLARES three optional `messages.payload` fields
+        // added by Requirement A — `intent` (record|discuss|develop), an optional
+        // client idempotency `submissionKey`, and a frozen `submissionReceipt`
+        // disposition. They add no column and no table and are only ever written
+        // going forward (absent `intent` reads as discuss; absent key is keyless;
+        // absent receipt is a pre-19 message), so NO historical row is rewritten and
+        // no key or receipt is ever fabricated for old data — declaring them here
+        // satisfies "optional still requires a migration declaration".
+        sql: "SELECT 1; -- artifacts move to per-Task local Git; see migrateArtifactsToGit",
+        migrateData: migrateArtifactsToGit
     }
 ]);
 for (let index = 0; index < MIGRATIONS.length; index += 1) {
@@ -1350,7 +1376,12 @@ export function migrateSqliteSchema(db, options) {
             throw new SqliteSchemaMigrationError(`storage version ${applied.currentVersion} is older than the minimum supported `
                 + `${MIN_SUPPORTED_STORAGE_VERSION}`, "admission");
         }
-        const pending = MIGRATIONS.filter((migration) => !applied.versions.has(migration.version));
+        // Production callers omit `throughVersion`, so the effective target is head
+        // and behavior is unchanged; a partial target is honored only in apply mode.
+        const effectiveTarget = options.mode === "apply" && options.throughVersion !== undefined
+            ? options.throughVersion
+            : CURRENT_STORAGE_VERSION;
+        const pending = MIGRATIONS.filter((migration) => !applied.versions.has(migration.version) && migration.version <= effectiveTarget);
         if (!ledgerWasCreated && pending.length > 0 && options.mode === "validate") {
             throw new SqliteSchemaMigrationError(`Storage version ${applied.currentVersion} requires an explicit upgrade to `
                 + `${CURRENT_STORAGE_VERSION}`, "admission");
@@ -1364,7 +1395,11 @@ export function migrateSqliteSchema(db, options) {
          VALUES (?, ?, ?, ?)`).run(migration.version, migration.name, appliedAt, checksum(migration.sql));
             newlyApplied.push(migration.version);
         }
-        validateSchemaObjects(db);
+        // The table/index inventory describes the HEAD shape; only assert it once the
+        // migration has actually advanced to head (a deliberate partial target stops
+        // earlier and is validated when the real upgrade later completes it).
+        if (effectiveTarget >= CURRENT_STORAGE_VERSION)
+            validateSchemaObjects(db);
         return newlyApplied;
     };
     const newlyApplied = options.mode === "apply" && !db.inTransaction
@@ -1376,7 +1411,6 @@ export function migrateSqliteSchema(db, options) {
 export const SQLITE_SCHEMA_TABLES = [
     "plugin_intents",
     "plugin_validations",
-    "artifacts",
     "local_resources",
     "environment_preparations",
     "schema_migrations",

package/dist/storage/sqliteStore.js

@@ -40,7 +40,7 @@ import { isDeepStrictEqual } from "node:util";
 import Database from "better-sqlite3";
 import { validatePluginValidation } from "../plugins/pluginPackage.js";
 import { validatePluginIntent, validatePluginIntentFailure } from "../plugins/pluginIntent.js";
-import { validateArtifact, validateLocalResource, validateEnvironmentPreparation } from "../resources/projectResource.js";
+import { validateLocalResource, validateEnvironmentPreparation } from "../resources/projectResource.js";
 import { validateConfiguredAgent } from "../agent/agent.js";
 import { validateTaskBrief } from "../brief/taskBrief.js";
 import { consumePendingBatch, mailboxTargetKey, validateWorkMailbox } from "../coordination/workMailbox.js";
@@ -614,26 +614,6 @@ export class SqliteTaskStore {
         });
     }
     // -- projects ---------------------------------------------------------------
-    saveArtifact(artifact) {
-        validateArtifact(artifact);
-        this.#mutate(() => {
-            const previous = this.getArtifact(artifact.taskId, artifact.id);
-            if (previous !== null) {
-                if (!isDeepStrictEqual(previous, artifact))
-                    throw new StorageRecordError("Artifacts are immutable.");
-                return;
-            }
-            this.#db.prepare("INSERT INTO artifacts (task_id, id, payload) VALUES (?, ?, ?)")
-                .run(artifact.taskId, artifact.id, this.#json(artifact));
-        });
-    }
-    getArtifact(taskId, artifactId) {
-        const artifact = this.#getPayload("artifacts", "task_id = ? AND id = ?", [taskId, artifactId]);
-        return artifact === null ? null : validateArtifact(artifact);
-    }
-    listArtifacts(taskId) {
-        return this.#listPayload("artifacts", "task_id = ?", [taskId]).map(validateArtifact);
-    }
     savePluginValidation(validation) {
         validatePluginValidation(validation);
         this.#mutate(() => {

package/dist/storage/storageVersions.js

@@ -13,4 +13,4 @@
  * intermediate Yui releases.
  */
 export const MIN_SUPPORTED_STORAGE_VERSION = 1;
-export const CURRENT_STORAGE_VERSION = 18;
+export const CURRENT_STORAGE_VERSION = 19;

package/dist/storage/storeRpc.js

@@ -29,7 +29,7 @@ import { StorageCancelledError, StorageConflictError, StorageRecordError } from
  */
 const READ_ONLY_STORE_METHODS = new Set([
     "getPluginIntent", "listPluginIntents",
-    "getPluginValidation", "getArtifact", "listArtifacts", "getLocalResource", "listLocalResources",
+    "getPluginValidation", "getLocalResource", "listLocalResources",
     "getEnvironmentPreparation", "listEnvironmentPreparations",
     "rootDirectory",
     "getConfig",

package/dist/task/taskActivation.js

@@ -22,6 +22,7 @@ export const TASK_ACTIVATION_EVENT = Object.freeze({
     adopted: "task.activation-adopted",
     failed: "task.activation-failed"
 });
+export const TASK_ACTIVATION_ORIGINS = Object.freeze(["explicit", "submit-develop"]);
 /**
  * The digest that decides whether a repeated requestId is the same request.
  *
@@ -63,6 +64,7 @@ export function createTaskActivationRequest(taskId, input, now) {
             partialResultRefs: []
         },
         startMode: input.startMode,
+        ...(input.origin === undefined ? {} : { origin: input.origin }),
         ...(input.afterPlanningRun === undefined
             ? {}
             : { afterPlanningRun: input.afterPlanningRun }),
@@ -194,6 +196,26 @@ export function admitTaskActivationRequest(task, request, planningRunIsActive) {
     }
     return { disposition: "ready", request };
 }
+/**
+ * Whether the Controller may continue (auto-adopt) a released request without an
+ * explicit activation boundary call (task-32 §2.4).
+ *
+ * A deferred request already holds activation authority and is released by its
+ * planning Turn ending, so it is adoptable regardless of origin. An immediate
+ * request is auto-continued only when it carries a recognised provable origin:
+ * an explicit activation action, or a develop submission the shared transaction
+ * accepted while the Task was unplanned. A request with no origin — every one
+ * migrated from before the field existed — is deliberately held back so an
+ * upgrade cannot turn a historical pending request into a silent activation; it
+ * still adopts through the explicit `yui task activate` boundary, which does not
+ * consult origin. This replaces the old actor heuristic that both dropped legal
+ * Operator/user immediate requests and could not distinguish provenance.
+ */
+export function activationRequestIsControllerAdoptable(request) {
+    if (request.startMode === "after-planning-turn")
+        return true;
+    return request.origin !== undefined;
+}
 /**
  * The durable terminal outcome for a requestId, read from the activation event
  * ledger.
@@ -236,6 +258,10 @@ export function validateTaskActivationRequest(request) {
     if (!["immediate", "after-planning-turn"].includes(request.startMode)) {
         throw new Error(`Activation start mode is invalid: ${String(request.startMode)}.`);
     }
+    if (request.origin !== undefined
+        && !TASK_ACTIVATION_ORIGINS.includes(request.origin)) {
+        throw new Error(`Activation origin is invalid: ${String(request.origin)}.`);
+    }
     if ((request.startMode === "after-planning-turn")
         !== (request.afterPlanningRun !== undefined)) {
         throw new Error("Activation deferral must name exactly the planning Turn it waits for.");