@zq-silk/yui 0.4.2 → 0.5.1

package/dist/storage/migration/productionRegistry.js

@@ -1,10 +1,17 @@
 /** The one production transition registry and its baseline-to-current delivery gate. */
+import { generateHomeIdentity } from "../../repository/homeIdentity.js";
 import { latestStorageVersionState } from "../upgrade/recordVersions.js";
 import { assertBaselineConsistency, baselineStorageVersionState } from "./baseline.js";
 import { planMigration } from "./planner.js";
 import { MigrationRegistry } from "./registry.js";
 const FINAL_REVIEW_AGGREGATE_FROM_VERSION = 16;
 const FINAL_REVIEW_AGGREGATE_TO_VERSION = 17;
+const HOME_IDENTITY_AGGREGATE_FROM_VERSION = 17;
+const HOME_IDENTITY_AGGREGATE_TO_VERSION = 18;
+const PROJECT_FROM_VERSION = 2;
+const PROJECT_TO_VERSION = 3;
+const TASK_FROM_VERSION = 3;
+const TASK_TO_VERSION = 4;
 const WORK_ITEM_FROM_VERSION = 6;
 const WORK_ITEM_TO_VERSION = 7;
 const WORK_ITEM_GIT_SNAPSHOT_FROM_VERSION = 7;
@@ -38,6 +45,16 @@ export function createProductionStorageRegistry() {
         transform: migrateAggregateV16ToV17,
         declaredEffects: []
     })
+        .registerOfflineMigration({
+        axis: "aggregate",
+        fromVersion: HOME_IDENTITY_AGGREGATE_FROM_VERSION,
+        toVersion: HOME_IDENTITY_AGGREGATE_TO_VERSION,
+        preconditions: requireAggregateV17Snapshot,
+        transform: migrateAggregateV17ToV18,
+        declaredEffects: []
+    })
+        .registerOfflineMigration(projectOwnershipStep())
+        .registerOfflineMigration(taskWorkspaceIdentityStep())
         .registerOfflineMigration(recordFamilyStep("workItem", WORK_ITEM_FROM_VERSION, WORK_ITEM_TO_VERSION, "workItems"))
         .registerOfflineMigration(recordFamilyStep("workItem", WORK_ITEM_GIT_SNAPSHOT_FROM_VERSION, WORK_ITEM_GIT_SNAPSHOT_TO_VERSION, "workItems"))
         .registerOfflineMigration(workItemExecutionGroupHistoryStep())
@@ -470,6 +487,169 @@ function requireAggregateV16Snapshot(snapshot) {
         throw new Error("Aggregate 16->17 migration requires state.json schemaVersion 16 to match schema.json.");
     }
 }
+/**
+ * Introduce the durable Home identity. A v18 aggregate always carries one; a
+ * Home with no state.json yet gets its identity when its first state is
+ * written, so this step only mints one when state.json already exists.
+ */
+function migrateAggregateV17ToV18(snapshot) {
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        aggregateSchemaVersion: HOME_IDENTITY_AGGREGATE_TO_VERSION
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const state = snapshot.state;
+    if (state.homeIdentity !== undefined) {
+        throw new Error("Aggregate 17->18 migration found an unexpected homeIdentity.");
+    }
+    return {
+        schemaManifest,
+        state: {
+            ...state,
+            schemaVersion: HOME_IDENTITY_AGGREGATE_TO_VERSION,
+            homeIdentity: generateHomeIdentity(new Date())
+        }
+    };
+}
+function requireAggregateV17Snapshot(snapshot) {
+    if (snapshot.schemaManifest.aggregateSchemaVersion
+        !== HOME_IDENTITY_AGGREGATE_FROM_VERSION) {
+        throw new Error("Aggregate 17->18 migration requires schema.json aggregateSchemaVersion 17.");
+    }
+    if (snapshot.state !== null
+        && snapshot.state.schemaVersion !== HOME_IDENTITY_AGGREGATE_FROM_VERSION) {
+        throw new Error("Aggregate 17->18 migration requires state.json schemaVersion 17 to match schema.json.");
+    }
+}
+/**
+ * Project ownership is a new required field. Every pre-v3 Project is a
+ * user-registered checkout, so the historical binding is `external`; a managed
+ * Home-owned repository is only ever created explicitly by the new binding
+ * path. The version transition is durable and centralized.
+ */
+function projectOwnershipStep() {
+    return {
+        axis: "record",
+        recordKind: "project",
+        fromVersion: PROJECT_FROM_VERSION,
+        toVersion: PROJECT_TO_VERSION,
+        preconditions: requireProjectV2Family,
+        transform: migrateProjectV2ToV3,
+        declaredEffects: []
+    };
+}
+function requireProjectV2Family(snapshot) {
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (manifestVersions.project !== PROJECT_FROM_VERSION) {
+        throw new Error(`Record project migration requires manifest version ${PROJECT_FROM_VERSION}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const projects = snapshot.state.projects;
+    if (projects === undefined)
+        return;
+    const map = asObject(projects, "project map");
+    for (const [projectId, rawProject] of Object.entries(map)) {
+        const project = asObject(rawProject, `Project ${projectId}`);
+        if (project.schemaVersion !== PROJECT_FROM_VERSION) {
+            throw new Error(`Project ${projectId} must use schemaVersion ${PROJECT_FROM_VERSION}.`);
+        }
+    }
+}
+function migrateProjectV2ToV3(snapshot) {
+    requireProjectV2Family(snapshot);
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: { ...manifestVersions, project: PROJECT_TO_VERSION }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const projects = snapshot.state.projects;
+    if (projects === undefined) {
+        return { schemaManifest, state: { ...snapshot.state } };
+    }
+    const map = asObject(projects, "project map");
+    const nextProjects = {};
+    for (const [projectId, rawProject] of Object.entries(map)) {
+        const project = asObject(rawProject, `Project ${projectId}`);
+        nextProjects[projectId] = {
+            ...project,
+            schemaVersion: PROJECT_TO_VERSION,
+            ownership: "external"
+        };
+    }
+    return {
+        schemaManifest,
+        state: { ...snapshot.state, projects: nextProjects }
+    };
+}
+/**
+ * Task v4 adds the optional durable workspace identity. Historical Tasks have
+ * no identity; they keep working against their existing (legacy) refs until the
+ * controlled rebuild mints one. This adjacent step performs no field rewrite,
+ * preserving old records while keeping a pre-v4 Task out of the strict current
+ * parser.
+ */
+function taskWorkspaceIdentityStep() {
+    return {
+        axis: "record",
+        recordKind: "task",
+        fromVersion: TASK_FROM_VERSION,
+        toVersion: TASK_TO_VERSION,
+        preconditions: requireTaskV3Family,
+        transform: migrateTaskV3ToV4,
+        declaredEffects: []
+    };
+}
+function requireTaskV3Family(snapshot) {
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (manifestVersions.task !== TASK_FROM_VERSION) {
+        throw new Error(`Record task migration requires manifest version ${TASK_FROM_VERSION}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const aggregate = asObject(rawTask, `Task aggregate ${taskId}`);
+        const task = aggregate.task;
+        if (task === undefined)
+            continue;
+        const record = asObject(task, `Task ${taskId}`);
+        if (record.schemaVersion !== TASK_FROM_VERSION) {
+            throw new Error(`Task ${taskId} must use schemaVersion ${TASK_FROM_VERSION}.`);
+        }
+    }
+}
+function migrateTaskV3ToV4(snapshot) {
+    requireTaskV3Family(snapshot);
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: { ...manifestVersions, task: TASK_TO_VERSION }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    const nextTasks = {};
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const aggregate = asObject(rawTask, `Task aggregate ${taskId}`);
+        if (aggregate.task === undefined) {
+            nextTasks[taskId] = { ...aggregate };
+            continue;
+        }
+        const task = asObject(aggregate.task, `Task ${taskId}`);
+        nextTasks[taskId] = {
+            ...aggregate,
+            task: { ...task, schemaVersion: TASK_TO_VERSION }
+        };
+    }
+    return {
+        schemaManifest,
+        state: { ...snapshot.state, tasks: nextTasks }
+    };
+}
 /**
  * A version bump is deliverable only when the shared planner resolves the full
  * adjacent path. This also covers target-only record families as explicit 0->1

package/dist/storage/storageVersions.js

@@ -8,4 +8,4 @@
 /** Version of the on-disk layout (`schema.json`, root `state.json`, and locks). */
 export const CURRENT_STORAGE_LAYOUT_VERSION = 6;
 /** Version of the authoritative aggregate stored in `state.json`. */
-export const CURRENT_AGGREGATE_SCHEMA_VERSION = 17;
+export const CURRENT_AGGREGATE_SCHEMA_VERSION = 18;

package/dist/storage/taskStore.js

@@ -14,6 +14,7 @@ import { validateReviewConfig } from "../review/reviewConfig.js";
 import { validateReviewRound } from "../review/reviewRound.js";
 import { sameTaskFinalReviewContract } from "../review/taskFinalReviewContract.js";
 import { assertProjectCatalog, validateProject } from "../repository/project.js";
+import { generateHomeIdentity, validateHomeIdentity } from "../repository/homeIdentity.js";
 import { validateAgentProfile } from "../profile/agentProfile.js";
 import { validateChangeSet } from "../integration/changeSet.js";
 import { validateIntegrationAttempt } from "../integration/integrationAttempt.js";
@@ -32,6 +33,7 @@ export const STORAGE_STATE_FILE = "state.json";
 /** The root StorageState schema is the persisted aggregate document version. */
 export const CURRENT_STORAGE_STATE_SCHEMA_VERSION = CURRENT_AGGREGATE_SCHEMA_VERSION;
 export const CURRENT_CONFIG_SCHEMA_VERSION = 1;
+export const CURRENT_HOME_IDENTITY_SCHEMA_VERSION = 1;
 export const CURRENT_ACTIVE_RUN_POINTER_SCHEMA_VERSION = 3;
 /**
  * Persisted StorageState/StoredTask family versions owned by this boundary.
@@ -42,11 +44,11 @@ export const CURRENT_ACTIVE_RUN_POINTER_SCHEMA_VERSION = 3;
  * below, but are not independent record-axis families.
  */
 export const CURRENT_CONFIGURED_AGENT_SCHEMA_VERSION = 2;
-export const CURRENT_PROJECT_SCHEMA_VERSION = 2;
+export const CURRENT_PROJECT_SCHEMA_VERSION = 3;
 export const CURRENT_AGENT_PROFILE_SCHEMA_VERSION = 2;
 export const CURRENT_GLOBAL_ROLE_SCHEMA_VERSION = 3;
 export const CURRENT_GLOBAL_ROLE_SESSION_SET_SCHEMA_VERSION = 3;
-export const CURRENT_TASK_SCHEMA_VERSION = 3;
+export const CURRENT_TASK_SCHEMA_VERSION = 4;
 export const CURRENT_TASK_BRIEF_SCHEMA_VERSION = 2;
 export const CURRENT_TASK_ROLE_SCHEMA_VERSION = 3;
 export const CURRENT_MANAGED_WORKSPACE_SCHEMA_VERSION = 2;
@@ -134,6 +136,7 @@ export class FileTaskStore {
         });
     }
     getConfig() { return clone(this.#state().config); }
+    getHomeIdentity() { return clone(this.#state().homeIdentity); }
     saveConfig(config) {
         const stored = versioned(config, CURRENT_CONFIG_SCHEMA_VERSION, "Yui config");
         validateYuiConfig(stored);
@@ -1172,6 +1175,7 @@ function emptyState() {
     return {
         schemaVersion: CURRENT_STORAGE_STATE_SCHEMA_VERSION,
         revision: 0,
+        homeIdentity: generateHomeIdentity(new Date()),
         config: { schemaVersion: CURRENT_CONFIG_SCHEMA_VERSION },
         configuredAgents: {},
         projects: {},
@@ -1249,6 +1253,7 @@ function parseState(raw) {
     exact(state, [
         "schemaVersion",
         "revision",
+        "homeIdentity",
         "config",
         "configuredAgents",
         "projects",
@@ -1261,6 +1266,12 @@ function parseState(raw) {
     if (state.schemaVersion !== CURRENT_STORAGE_STATE_SCHEMA_VERSION || !Number.isInteger(state.revision) || state.revision < 0)
         throw new StorageRecordError("Storage state schemaVersion/revision is invalid.");
     const result = clone(state);
+    try {
+        result.homeIdentity = validateHomeIdentity(versioned(result.homeIdentity, CURRENT_HOME_IDENTITY_SCHEMA_VERSION, "Home identity"));
+    }
+    catch (error) {
+        throw new StorageRecordError(error instanceof Error ? error.message : String(error));
+    }
     result.config = versioned(result.config, CURRENT_CONFIG_SCHEMA_VERSION, "Yui config");
     validateYuiConfig(result.config);
     parseMap(result.configuredAgents, (value, key) => {

package/dist/task/task.js

@@ -1,7 +1,8 @@
+import { validateTaskWorkspaceIdentity } from "../repository/taskWorkspaceIdentity.js";
 export function createTask(id, title, now, metadata = {}) {
     const timestamp = now.toISOString();
     return {
-        schemaVersion: 3,
+        schemaVersion: 4,
         id: requireSafeIdentity(id, "Task id"),
         title: requireText(title, "Task title"),
         ...cloneMetadata(metadata),
@@ -10,6 +11,32 @@ export function createTask(id, title, now, metadata = {}) {
         updatedAt: timestamp
     };
 }
+/**
+ * Persist the Task's durable workspace identity. The identity is immutable on
+ * the Task: a second binding is rejected so restart/reconcile/attach can never
+ * silently adopt a different (foreign or legacy) ref namespace.
+ */
+export function bindTaskWorkspaceIdentity(task, identity, now) {
+    validateTask(task);
+    const valid = validateTaskWorkspaceIdentity(identity);
+    if (valid.taskId !== task.id) {
+        throw new Error(`Task workspace identity belongs to another Task: ${valid.taskId}.`);
+    }
+    if (task.workspaceIdentity !== undefined) {
+        const existing = validateTaskWorkspaceIdentity(task.workspaceIdentity);
+        if (existing.token !== valid.token
+            || existing.generatedAt !== valid.generatedAt
+            || existing.homeId !== valid.homeId) {
+            throw new Error(`Task workspace identity is already bound and immutable: ${task.id}.`);
+        }
+        return task;
+    }
+    return validateTask({
+        ...task,
+        workspaceIdentity: valid,
+        updatedAt: now.toISOString()
+    });
+}
 export function activateTask(task, now) {
     if (task.status === "archived")
         throw new Error(`Cannot activate archived Task: ${task.id}.`);
@@ -144,8 +171,8 @@ export function isTaskArchived(task) {
     return task.status === "archived";
 }
 export function validateTask(task) {
-    if (task.schemaVersion !== 3)
-        throw new Error("Task must use schemaVersion 3.");
+    if (task.schemaVersion !== 4)
+        throw new Error("Task must use schemaVersion 4.");
     requireSafeIdentity(task.id, "Task id");
     requireText(task.title, "Task title");
     if (!["draft", "active", "completed", "retired", "archived"].includes(task.status)) {
@@ -156,6 +183,12 @@ export function validateTask(task) {
     if (Date.parse(task.updatedAt) < Date.parse(task.createdAt)) {
         throw new Error("Task updatedAt cannot precede createdAt.");
     }
+    if (task.workspaceIdentity !== undefined) {
+        const identity = validateTaskWorkspaceIdentity(task.workspaceIdentity);
+        if (identity.taskId !== task.id) {
+            throw new Error(`Task workspace identity belongs to another Task: ${identity.taskId}.`);
+        }
+    }
     if (task.priority !== undefined
         && !["low", "medium", "high", "urgent"].includes(task.priority)) {
         throw new Error(`Task priority is invalid: ${String(task.priority)}.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,