@zq-silk/yui 0.2.0 → 0.4.2

package/dist/worktree/managedWorkspace.js

@@ -0,0 +1,202 @@
+import { resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+/** Every active Task launch is fenced by this durable owner. */
+export function isTaskOwnedWorkspace(workspace, taskId, taskRoot, bindings) {
+    if (workspace === null || workspace === undefined
+        || workspace.owner.type !== "task"
+        || workspace.owner.taskId !== taskId
+        || taskRoot === undefined
+        || workspace.root !== taskRoot) {
+        return false;
+    }
+    const expected = bindings
+        .map(({ projectId, directory }) => `${projectId}\u0000${directory}\u0000write`)
+        .sort();
+    const actual = workspace.entries
+        .map(({ projectId, directory, access }) => `${projectId}\u0000${directory}\u0000${access}`)
+        .sort();
+    return isDeepStrictEqual(actual, expected);
+}
+export function createManagedWorkspace(input, now) {
+    const timestamp = now.toISOString();
+    return validateManagedWorkspace({
+        schemaVersion: 2,
+        owner: validateOwner(input.owner),
+        root: resolve(requireText(input.root, "Managed workspace root")),
+        entries: normalizeEntries(input.entries),
+        createdAt: timestamp,
+        updatedAt: timestamp
+    });
+}
+export function validateManagedWorkspace(workspace) {
+    if (workspace.schemaVersion !== 2) {
+        throw new Error("Managed workspace must use schemaVersion 2.");
+    }
+    validateOwner(workspace.owner);
+    if (resolve(requireText(workspace.root, "Managed workspace root")) !==
+        workspace.root) {
+        throw new Error("Managed workspace root must be absolute and normalized.");
+    }
+    normalizeEntries(workspace.entries);
+    requireTimestamp(workspace.createdAt, "ManagedWorkspace createdAt");
+    requireTimestamp(workspace.updatedAt, "ManagedWorkspace updatedAt");
+    return workspace;
+}
+export function workspaceProjectEntry(workspace, projectId) {
+    return workspace.entries.find((entry) => entry.projectId === projectId);
+}
+/** Stable key used by the aggregate's owner-keyed workspace map. */
+export function managedWorkspaceKey(owner) {
+    const valid = validateOwner(owner);
+    switch (valid.type) {
+        case "task":
+            return `task:${valid.taskId}`;
+        case "work-item":
+            return `work-item:${valid.taskId}:${valid.workItemId}`;
+        case "review-round":
+            return `review-round:${valid.taskId}:${valid.reviewRoundId}`;
+        case "integration-attempt":
+            return `integration-attempt:${valid.taskId}:${valid.integrationAttemptId}`;
+        case "execution-lane":
+            return `execution-lane:${valid.taskId}:${valid.executionGroupId}:${valid.executionLaneId}`;
+    }
+}
+/** Physical worktree names are owner identities, never Role names. */
+export function managedWorktreeName(owner) {
+    switch (owner.type) {
+        case "task":
+            return "main";
+        case "work-item":
+            return owner.workItemId;
+        case "review-round":
+            return owner.reviewRoundId;
+        case "integration-attempt":
+            return `integration-${owner.integrationAttemptId}`;
+        case "execution-lane":
+            return `execution-lane-${owner.executionGroupId}-${owner.executionLaneId}`;
+    }
+}
+function normalizeEntries(entries) {
+    if (!Array.isArray(entries)) {
+        throw new Error("Workspace Project entries are invalid.");
+    }
+    const projectIds = new Set();
+    const directories = new Set();
+    return entries.map((entry) => {
+        const projectId = requireIdentity(entry.projectId, "Project id");
+        const directory = requireIdentity(entry.directory, "Project directory");
+        if (!["read", "write"].includes(entry.access)) {
+            throw new Error(`Workspace Project access is invalid: ${String(entry.access)}.`);
+        }
+        if (projectIds.has(projectId)) {
+            throw new Error(`Workspace Project is duplicated: ${projectId}.`);
+        }
+        if (directories.has(directory)) {
+            throw new Error(`Workspace Project directory is duplicated: ${directory}.`);
+        }
+        projectIds.add(projectId);
+        directories.add(directory);
+        const path = resolve(requireText(entry.path, "Workspace Project path"));
+        if (path !== entry.path) {
+            throw new Error("Workspace Project path must be absolute and normalized.");
+        }
+        return {
+            projectId,
+            directory,
+            access: entry.access,
+            path,
+            branch: requireText(entry.branch, "Workspace Project branch"),
+            baseRef: requireText(entry.baseRef, "Workspace Project base ref"),
+            baseCommit: requireCommit(entry.baseCommit)
+        };
+    });
+}
+function validateOwner(owner) {
+    if (owner.type === "task") {
+        return { type: "task", taskId: requireIdentity(owner.taskId, "Task id") };
+    }
+    if (owner.type === "work-item") {
+        return {
+            type: "work-item",
+            taskId: requireIdentity(owner.taskId, "Task id"),
+            workItemId: requireIdentity(owner.workItemId, "Work item id")
+        };
+    }
+    if (owner.type === "review-round") {
+        return {
+            type: "review-round",
+            taskId: requireIdentity(owner.taskId, "Task id"),
+            reviewRoundId: requireIdentity(owner.reviewRoundId, "ReviewRound id")
+        };
+    }
+    if (owner.type === "integration-attempt") {
+        return {
+            type: "integration-attempt",
+            taskId: requireIdentity(owner.taskId, "Task id"),
+            integrationAttemptId: requireIdentity(owner.integrationAttemptId, "Integration Attempt id")
+        };
+    }
+    if (owner.type === "execution-lane") {
+        const purpose = owner.purpose;
+        if (purpose !== "execution" && purpose !== "review") {
+            throw new Error("Managed execution-lane workspace purpose is invalid.");
+        }
+        const workItemId = owner.workItemId === undefined
+            ? undefined
+            : requireIdentity(owner.workItemId, "Work item id");
+        const reviewRoundId = owner.reviewRoundId === undefined
+            ? undefined
+            : requireIdentity(owner.reviewRoundId, "ReviewRound id");
+        if (purpose === "execution" && workItemId === undefined) {
+            throw new Error("Managed execution-lane workspace requires a Work Item.");
+        }
+        if (purpose === "execution" && reviewRoundId !== undefined) {
+            throw new Error("Managed execution-lane workspace cannot also own a ReviewRound.");
+        }
+        if (purpose === "review" && reviewRoundId === undefined) {
+            throw new Error("Managed execution-lane workspace requires a ReviewRound.");
+        }
+        if (purpose === "review" && workItemId !== undefined) {
+            throw new Error("Managed review-lane workspace cannot also own a Work Item.");
+        }
+        return {
+            type: "execution-lane",
+            taskId: requireIdentity(owner.taskId, "Task id"),
+            executionGroupId: requireIdentity(owner.executionGroupId, "ExecutionGroup id"),
+            executionLaneId: requireIdentity(owner.executionLaneId, "ExecutionLane id"),
+            purpose,
+            ...(workItemId === undefined ? {} : { workItemId }),
+            ...(reviewRoundId === undefined ? {} : { reviewRoundId })
+        };
+    }
+    throw new Error("Managed workspace owner is invalid.");
+}
+function requireIdentity(value, label) {
+    const identity = requireText(value, label);
+    if ([".", "..", "__proto__", "prototype", "constructor"].includes(identity) ||
+        /[\/\\\0]/.test(identity)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return identity;
+}
+function requireCommit(value) {
+    const commit = requireText(value, "Managed workspace base commit").toLowerCase();
+    if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(commit)) {
+        throw new Error("Managed workspace base commit is invalid.");
+    }
+    return commit;
+}
+function requireText(value, label) {
+    if (typeof value !== "string" || value.includes("\0")) {
+        throw new Error(`${label} is invalid.`);
+    }
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}
+function requireTimestamp(value, label) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) {
+        throw new Error(`${label} is invalid.`);
+    }
+}

package/docs/task-local-identity.md

@@ -0,0 +1,62 @@
+# Task-local identity
+
+Yui treats a Task as the aggregate boundary for durable workflow records. Each
+Task owns an independent, monotonically increasing sequence for every record
+family:
+
+- WorkItem
+- AgentRun
+- ReviewRound
+- ChangeSet
+- IntegrationAttempt
+- Message
+- InputRequest
+- Decision
+- Milestone
+- Event
+
+The first record of each family in each Task is therefore local `-1`. Deleted,
+cancelled, completed, reopened, and archived records never lower the persisted
+high-water mark, so a local ID is never reused inside its Task. Each allocation
+advances that aggregate high-water mark under the storage process lock.
+
+Candidate identity is narrower: `candidate-N` is a WorkItem-local sequence.
+Every Candidate stores its `taskId` and `workItemId`, in addition to the source
+Run when one exists.
+
+## Reference contract
+
+The portable form of a Task-owned reference is:
+
+```text
+<task-id>/<local-id>
+```
+
+For example, `task-7/work-item-1` and `task-9/work-item-1` are distinct. CLI,
+JSON, mailbox, Controller, Hook, receipt, Web, and error paths retain the Task
+scope. Context-free commands reject a bare local ID instead of searching all
+Tasks, even if that ID currently happens to be unique.
+
+A managed Task session may use `work-item-1` or `agent-run-1` because its
+`YUI_TASK_ID` is explicit. A command that already receives the Task as another
+argument may also use a subordinate local ID. Outside those two cases, use the
+qualified form. Delivery receipts use the same provenance, for example:
+
+```text
+agent-run:task-7/agent-run-1
+input-request:task-7/input-1
+```
+
+There is no compatibility lookup, cross-Task guess, or bare-ID fallback.
+
+## Current-schema boundary
+
+Runtime opens only aggregate v13 / StoredTask v12. It does not convert,
+dual-read, or infer records from an older schema. If an existing `YUI_HOME`
+does not match the current schema, keep it untouched for external archival
+and initialize a fresh home for this runtime.
+
+This hard cut keeps Task-local references, Role desired configuration, and
+immutable AgentRun/RoleSession effective snapshots under one unambiguous
+contract. There is no compatibility lookup, conversion command, or
+intermediate storage format.