@zq-silk/yui 0.4.2 → 0.5.1

package/dist/repository/gitWorkspace.js

@@ -171,6 +171,13 @@ export class NodeGitWorkspace {
             "-C", initial.root,
             "rev-parse", "--verify", "--end-of-options", "FETCH_HEAD^{commit}"
         ])).toLowerCase();
+        // The advertised SHA must match what was fetched. A network race, a ref
+        // that moved mid-fetch, or any inconsistency fails closed: the stable
+        // checkout is never advanced to an unverified commit.
+        const advertisedCommit = await resolveRemoteBranchCommit(remote, stableBranch);
+        if (fetchedCommit !== advertisedCommit) {
+            throw new Error(`Project remote stable branch changed while it was fetched: ${stableBranch}.`);
+        }
         await this.#assertRefreshCheckout(initial.root, stableBranch, initial.baseCommit);
         if (fetchedCommit === initial.baseCommit) {
             return {
@@ -300,6 +307,52 @@ export class NodeGitWorkspace {
             baseCommit: baseCommit.toLowerCase()
         };
     }
+    async refExists(repositoryPath, ref) {
+        const root = (await this.inspect(repositoryPath)).root;
+        return gitSucceeds([
+            "-C", root, "rev-parse", "--verify", "--quiet", "--end-of-options",
+            `${safeRef(ref)}^{commit}`
+        ]);
+    }
+    async listRefs(repositoryPath, pattern) {
+        const root = (await this.inspect(repositoryPath)).root;
+        const output = await git([
+            "-C", root, "for-each-ref", "--format=%(refname)", "--", safeRef(pattern)
+        ]);
+        return output.length === 0 ? [] : output.split("\n").map((line) => line.trim())
+            .filter((line) => line.length > 0);
+    }
+    async archiveRef(input) {
+        const root = (await this.inspect(input.repositoryPath)).root;
+        const source = safeRef(input.sourceRef);
+        const target = safeRef(input.archiveRef);
+        const commit = (await gitLine([
+            "-C", root, "rev-parse", "--verify", "--end-of-options", `${source}^{commit}`
+        ])).toLowerCase();
+        if (await this.refExists(root, target)) {
+            // Resumable: a previous attempt already created the archive ref. Only
+            // the same commit may be resumed; a different archive fails closed.
+            const archived = (await gitLine([
+                "-C", root, "rev-parse", "--verify", "--end-of-options", `${target}^{commit}`
+            ])).toLowerCase();
+            if (archived !== commit) {
+                throw new Error(`Archive ref already exists at a different commit: ${target}.`);
+            }
+        }
+        else {
+            // Create the archive ref only if it does not exist yet (old value zero).
+            await git([
+                "-C", root, "update-ref", "--no-deref", target, commit, "0".repeat(40)
+            ]);
+        }
+        // Delete the source only if it still exists and still points at the
+        // archived commit; an already-deleted source makes the archive a no-op.
+        if (await this.refExists(root, source)) {
+            await git([
+                "-C", root, "update-ref", "-d", "--no-deref", source, commit
+            ]);
+        }
+    }
     async isAncestor(repositoryPath, ancestor, descendant) {
         const root = (await this.inspect(repositoryPath)).root;
         return gitSucceeds([
@@ -387,7 +440,7 @@ export class NodeGitWorkspace {
         return this.#ensureManagedWorktree({
             repositoryPath: input.repositoryPath,
             container: input.container,
-            identity: worktreeIdentity(input.taskId, input.roleName),
+            identity: worktreeIdentity(input.taskSegment, input.roleName),
             baseRef: input.baseRef
         });
     }
@@ -395,7 +448,7 @@ export class NodeGitWorkspace {
         return this.#ensureManagedWorktree({
             repositoryPath: input.repositoryPath,
             container: input.container,
-            identity: integrationWorktreeIdentity(input.taskId, input.integrationId),
+            identity: integrationWorktreeIdentity(input.taskSegment, input.integrationId),
             baseRef: input.baseRef
         });
     }
@@ -441,7 +494,7 @@ export class NodeGitWorkspace {
         if (state === "dirty")
             return state;
         const container = resolve(input.container);
-        const identity = worktreeIdentity(input.taskId, input.roleName);
+        const identity = worktreeIdentity(input.taskSegment, input.roleName);
         const path = managedPath(container, identity.directory);
         const project = await this.inspect(input.repositoryPath);
         if (state === "missing") {
@@ -459,7 +512,7 @@ export class NodeGitWorkspace {
     }
     async inspectWorktree(input) {
         const container = resolve(input.container);
-        const path = managedPath(container, worktreeIdentity(input.taskId, input.roleName).directory);
+        const path = managedPath(container, worktreeIdentity(input.taskSegment, input.roleName).directory);
         const kind = await pathKind(path);
         if (kind === undefined)
             return "missing";
@@ -475,7 +528,7 @@ export class NodeGitWorkspace {
         return this.#removeManagedWorktree({
             repositoryPath: input.repositoryPath,
             container: input.container,
-            identity: integrationWorktreeIdentity(input.taskId, input.integrationId),
+            identity: integrationWorktreeIdentity(input.taskSegment, input.integrationId),
             discardChanges: input.discardChanges
         });
     }

package/dist/repository/homeIdentity.js

@@ -0,0 +1,28 @@
+import { randomBytes } from "node:crypto";
+export const HOME_IDENTITY_PATTERN = /^home-[a-f0-9]{16}$/;
+const HOME_ENTROPY_BYTES = 16;
+export function generateHomeIdentity(now, source = () => randomBytes(HOME_ENTROPY_BYTES)) {
+    const entropy = source().toString("hex");
+    const homeId = `home-${randomBytes(8).toString("hex")}`;
+    return validateHomeIdentity({
+        schemaVersion: 1,
+        homeId,
+        createdAt: now.toISOString(),
+        entropy
+    });
+}
+export function validateHomeIdentity(identity) {
+    if (identity.schemaVersion !== 1) {
+        throw new Error("Home identity must use schemaVersion 1.");
+    }
+    if (typeof identity.homeId !== "string" || !HOME_IDENTITY_PATTERN.test(identity.homeId)) {
+        throw new Error("Home identity id is invalid.");
+    }
+    if (typeof identity.entropy !== "string" || !/^[a-f0-9]{32}$/.test(identity.entropy)) {
+        throw new Error("Home identity entropy is invalid.");
+    }
+    if (typeof identity.createdAt !== "string" || !Number.isFinite(Date.parse(identity.createdAt))) {
+        throw new Error("Home identity createdAt is invalid.");
+    }
+    return identity;
+}

package/dist/repository/project.js

@@ -1,12 +1,18 @@
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
+/** The Yui-owned directory holding a managed Project's canonical repository. */
+export function managedProjectPath(home, projectId) {
+    const id = requireIdentity(projectId, "Project id");
+    return join(resolve(home), "projects", id);
+}
 export function createProject(id, name, path, branches, now, metadata = {}) {
     const timestamp = now.toISOString();
     return validateProject({
-        schemaVersion: 2,
+        schemaVersion: 3,
         id: requireIdentity(id, "Project id"),
         name: validateProjectName(name),
         aliases: normalizeAliases(metadata.aliases ?? [], name),
         path: resolve(requireText(path, "Project path")),
+        ownership: metadata.ownership ?? "external",
         ...(metadata.remoteUrl === undefined
             ? {}
             : { remoteUrl: requireText(metadata.remoteUrl, "Project remote URL") }),
@@ -132,12 +138,15 @@ export function assertProjectCatalog(projects) {
     }
 }
 export function validateProject(project) {
-    if (project.schemaVersion !== 2) {
-        throw new Error("Project must use schemaVersion 2.");
+    if (project.schemaVersion !== 3) {
+        throw new Error("Project must use schemaVersion 3.");
     }
     requireIdentity(project.id, "Project id");
     requireIdentity(project.name, "Project name");
     normalizeAliases(project.aliases, project.name);
+    if (project.ownership !== "managed" && project.ownership !== "external") {
+        throw new Error(`Project ownership is invalid: ${String(project.ownership)}.`);
+    }
     const references = new Set();
     for (const reference of [project.id, project.name, ...project.aliases]) {
         const folded = reference.toLocaleLowerCase();

package/dist/repository/taskWorkspaceIdentity.js

@@ -0,0 +1,158 @@
+import { createHash, randomBytes } from "node:crypto";
+export const TASK_WORKSPACE_TOKEN_PATTERN = /^[a-f0-9]{8}$/;
+/** Strict on-disk ref segment for a Task's managed worktrees. */
+export const TASK_WORKSPACE_REF_SEGMENT_PATTERN = /^(task-[0-9]+)-[a-f0-9]{8}$/;
+const TASK_WORKSPACE_ENTROPY_BYTES = 16;
+const TASK_WORKSPACE_IDENTITY_DOMAIN = "yui-task-workspace-identity/v1";
+/** Unambiguous length-prefixed encoding: every field is `<byteLen>:<value>`. */
+function lengthPrefixedEncoding(parts) {
+    return parts
+        .map((part) => `${Buffer.byteLength(part, "utf8")}:${part}`)
+        .join("\n");
+}
+export function deriveTaskWorkspaceToken(input) {
+    const encoding = lengthPrefixedEncoding([
+        TASK_WORKSPACE_IDENTITY_DOMAIN,
+        input.homeId,
+        input.taskId,
+        input.generatedAt,
+        input.entropy
+    ]);
+    return createHash("sha256").update(encoding, "utf8").digest("hex").slice(0, 8);
+}
+export function generateTaskWorkspaceIdentity(input) {
+    const homeId = requireIdentityPart(input.home.homeId, "Home id");
+    const taskId = requireIdentityPart(input.taskId, "Task id");
+    const generatedAt = input.now.toISOString();
+    const entropy = (input.entropy ?? randomBytes(TASK_WORKSPACE_ENTROPY_BYTES))
+        .toString("hex");
+    const token = deriveTaskWorkspaceToken({ homeId, taskId, generatedAt, entropy });
+    return validateTaskWorkspaceIdentity({
+        schemaVersion: 1,
+        homeId,
+        taskId,
+        token,
+        generatedAt,
+        entropy
+    });
+}
+/**
+ * The ref segment shared by every managed worktree of one Task, e.g.
+ * `task-2-a1b2c3d4`. Git refs and worktree directories are derived from this
+ * segment, never from the bare Task id.
+ */
+export function taskWorkspaceRefSegmentFromIdentity(identity) {
+    const valid = validateTaskWorkspaceIdentity(identity);
+    return `${valid.taskId}-${valid.token}`;
+}
+/**
+ * The durable ref segment for a Task. A Task with a persisted workspace
+ * identity always uses its token-bearing segment; a pre-identity record (a
+ * valid v4 Task that never had a managed Git workspace, or one awaiting the
+ * controlled rebuild) keeps its bare Task id so its existing worktrees remain
+ * addressable until they are rebuilt.
+ */
+export function taskWorkspaceRefSegment(task) {
+    if (task.workspaceIdentity === undefined)
+        return task.id;
+    return taskWorkspaceRefSegmentFromIdentity(task.workspaceIdentity);
+}
+/**
+ * The strict main-branch ref for a Task workspace. The main branch is always
+ * `yui/task-N-<8hex>/main`; any other shape is a foreign or legacy ref.
+ */
+export function taskMainBranch(refSegment) {
+    if (!TASK_WORKSPACE_REF_SEGMENT_PATTERN.test(refSegment)) {
+        throw new Error(`Task workspace ref segment is invalid: ${refSegment}.`);
+    }
+    return `yui/${refSegment}/main`;
+}
+/**
+ * A derived managed branch for one Task workspace member (WorkItem,
+ * ReviewRound, or execution lane worktree name). Every derived ref stays
+ * under the Task's token-bearing segment, so capture, review, integration,
+ * and cleanup fences all resolve through the same persisted identity.
+ */
+export function taskDerivedBranch(refSegment, member) {
+    if (!TASK_WORKSPACE_REF_SEGMENT_PATTERN.test(refSegment)) {
+        throw new Error(`Task workspace ref segment is invalid: ${refSegment}.`);
+    }
+    const memberSegment = member.trim();
+    if (memberSegment.length === 0 || /[~^:?*[\]\s]/.test(memberSegment)
+        || memberSegment.includes("..") || memberSegment.startsWith("-")) {
+        throw new Error(`Task workspace member is invalid: ${member}.`);
+    }
+    return `yui/${refSegment}/${memberSegment}`;
+}
+/** The Integration Attempt branch derived from the Task workspace identity. */
+export function taskIntegrationBranch(refSegment, integrationId) {
+    return taskDerivedBranch(refSegment, `integration/${integrationId}`);
+}
+/**
+ * The non-colliding, auditable archive ref for a legacy Task ref. The Home id
+ * in the path keeps two Homes' archives apart even when they share a Project
+ * repository; the full original ref name is preserved verbatim.
+ * Legacy refs live at `refs/heads/yui/task-N/...`; archives at
+ * `refs/yui/archive/<homeId>/heads/yui/task-N/...`.
+ */
+export function taskArchiveRef(homeId, sourceRef) {
+    const id = requireIdentityPart(homeId, "Home id");
+    const ref = sourceRef.trim();
+    if (!ref.startsWith("refs/")
+        || ref.includes("..")
+        || /[~^:?*[\]\s]/.test(ref)) {
+        throw new Error(`Archive source ref is invalid: ${sourceRef}.`);
+    }
+    return `refs/yui/archive/${id}/${ref.slice("refs/".length)}`;
+}
+/**
+ * Whether a managed branch belongs to the legacy (pre-identity) layout:
+ * `yui/task-N/...` with a bare Task id segment. Identity-bearing branches
+ * (`yui/task-N-<8hex>/...`) are never legacy.
+ */
+export function isLegacyTaskRef(refName) {
+    const match = /^refs\/heads\/(yui\/(task-[0-9]+)\/.+)$/.exec(refName);
+    return match !== null && !TASK_WORKSPACE_REF_SEGMENT_PATTERN.test(match[2]);
+}
+export function validateTaskWorkspaceIdentity(identity) {
+    if (identity.schemaVersion !== 1) {
+        throw new Error("Task workspace identity must use schemaVersion 1.");
+    }
+    const homeId = requireIdentityPart(identity.homeId, "Home id");
+    const taskId = requireIdentityPart(identity.taskId, "Task id");
+    if (typeof identity.generatedAt !== "string"
+        || !Number.isFinite(Date.parse(identity.generatedAt))) {
+        throw new Error("Task workspace identity generatedAt is invalid.");
+    }
+    if (typeof identity.entropy !== "string"
+        || !/^[a-f0-9]{32}$/.test(identity.entropy)) {
+        throw new Error("Task workspace identity entropy is invalid.");
+    }
+    if (typeof identity.token !== "string"
+        || !TASK_WORKSPACE_TOKEN_PATTERN.test(identity.token)) {
+        throw new Error("Task workspace identity token is invalid.");
+    }
+    // The token must be the exact SHA-256 discriminator of the persisted fields;
+    // a mismatched token is malformed state and is rejected, never repaired.
+    const expected = deriveTaskWorkspaceToken({
+        homeId,
+        taskId,
+        generatedAt: identity.generatedAt,
+        entropy: identity.entropy
+    });
+    if (expected !== identity.token) {
+        throw new Error("Task workspace identity token does not match its persisted fields.");
+    }
+    return identity;
+}
+function requireIdentityPart(value, label) {
+    if (typeof value !== "string" || value.includes("\0")) {
+        throw new Error(`${label} is invalid.`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        throw new Error(`${label} is required.`);
+    if (/[\/\\]/.test(trimmed))
+        throw new Error(`${label} must not contain a path separator.`);
+    return trimmed;
+}