@zq-silk/yui 0.6.0 → 0.6.2

package/dist/executor/fileRoleLaunchPlanner.js

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -14,9 +14,11 @@ import { taskRoleSessionTitle } from "../runtime/sessionTitle.js";
 import { nativeSessionIdForLaunch } from "../runtime/preallocatedNativeSession.js";
 import { isTaskOwnedWorkspace } from "../worktree/managedWorkspace.js";
 import { activeLiveRoleAgentSession } from "./agentExecutor.js";
-import { effectiveLaunchSnapshotsCompatible, effectiveRoleForLaunch, resolveEffectiveLaunch } from "./effectiveLaunch.js";
+import { effectiveLaunchSnapshotsCompatibleForTaskMain, effectiveLaunchSnapshotsCompatible, effectiveRoleForLaunch, resolveEffectiveLaunch } from "./effectiveLaunch.js";
 import { YUI_CONTROL_PLANE_DESCRIPTOR, YUI_TASK_RUNTIME_DESCRIPTOR, assertExactTaskRuntimeState, createExactControlPlaneDescriptor, createExactTaskRuntimeDescriptor, exactControlPlaneCommandPrefix, exactControlPlaneDigest, exactTaskRuntimeDescriptorPath, serializeExactDescriptor } from "../runtime/exactControlPlane.js";
+import { readActiveReleasePointer } from "../release/runtimeRelease.js";
 import { parseTaskRuntimeIsolationDescriptor, taskRuntimeIsolationEnvironment } from "../runtime/taskRuntimeIsolation.js";
+import { ResourceRegistrar } from "../resources/resourceRegistrar.js";
 /** Builds managed native Agent launches from the authoritative Task records. */
 export class FileRoleLaunchPlanner {
     home;
@@ -27,6 +29,7 @@ export class FileRoleLaunchPlanner {
     #createNativeSessionId;
     #cliPath;
     #controlPlane;
+    #resourceRegistrarValue;
     constructor(home, store, options = {}) {
         this.home = home;
         this.store = store;
@@ -46,16 +49,38 @@ export class FileRoleLaunchPlanner {
         // Freeze the complete control identity before any native process exists.
         // This value is immutable for the planner/Controller lifetime and is never
         // rewritten through a shared PATH launcher.
+        // Issue 02: bind the active release build ID so a Session created after a
+        // handover cannot mutate a different control plane.
+        const activeRelease = readActiveReleasePointer(this.home);
         this.#controlPlane = createExactControlPlaneDescriptor({
             executable: process.execPath,
             cliEntry: this.#cliPath,
-            yuiHome: this.home
+            yuiHome: this.home,
+            ...(activeRelease === null
+                ? {}
+                : {
+                    buildId: activeRelease.buildId,
+                    activeReleaseDigest: activeRelease.packageDigest
+                })
         });
     }
+    #resourceRegistrar() {
+        return this.#resourceRegistrarValue ??= new ResourceRegistrar(this.home);
+    }
     refreshAgentEnvironment(refresh) {
         this.#agentEnvironment = patchEnvironment(this.#agentEnvironment, refresh.sourceNames, refresh.sources);
         this.#nativeAgentEnvironment = patchEnvironment(this.#nativeAgentEnvironment, refresh.nativeNames, refresh.nativeSources);
     }
+    /**
+     * Commit the caller key for a task Session only after the runtime host has
+     * confirmed that it created a new native process.  An ensure/resume request
+     * that reuses a live host must keep the old durable hash because its process
+     * still carries the old plaintext key.
+     */
+    commitTaskCallerKey(input) {
+        const hash = createHash("sha256").update(input.callerKey).digest("hex");
+        this.store.setJobCallerKeyHash(input.taskId, input.roleName, input.agentId, hash);
+    }
     /** Re-publishes provider-discovered native identity after its durable fold. */
     refreshTaskRuntimeDescriptor(input) {
         const task = this.store.getTask(input.taskId);
@@ -81,8 +106,20 @@ export class FileRoleLaunchPlanner {
             launchId: session.launchId,
             nativeSessionId: session.nativeSessionId
         });
+        if (descriptor.runId !== input.runId
+            || descriptor.launchId !== input.launchId
+            || descriptor.nativeSessionId !== input.nativeSessionId
+            || descriptor.agentId !== input.agentId
+            || descriptor.adapterId !== input.adapterId
+            || descriptor.workspace !== canonicalPath(input.workspace)) {
+            throw new Error("Prepared Task runtime generation is not current.");
+        }
         assertExactTaskRuntimeState(descriptor, this.store);
-        writeTextFileAtomically(exactTaskRuntimeDescriptorPath(this.home, descriptor), `${serializeExactDescriptor(descriptor)}\n`);
+        // Publish only the current-control source. A reused native pane keeps its
+        // own stable source path; its Hook self-refreshes that source before the
+        // volatile fence instead of the Controller scanning history to find it.
+        const currentSource = exactTaskRuntimeDescriptorPath(this.home, descriptor);
+        this.#writeExactTaskRuntimeDescriptor(descriptor, currentSource);
     }
     plan(input) {
         const task = this.store.getTask(input.taskId);
@@ -175,7 +212,9 @@ export class FileRoleLaunchPlanner {
         const effective = input.effective ?? resolvedEffective;
         const existing = sessionSet?.sessions[effective.agentId];
         const compatibleExisting = existing !== undefined
-            && effectiveLaunchSnapshotsCompatible(existing.effective, effective);
+            && (input.mode === "resume"
+                ? effectiveLaunchSnapshotsCompatibleForTaskMain(existing.effective, effective, runWorkspace ?? workspace)
+                : effectiveLaunchSnapshotsCompatible(existing.effective, effective));
         if (input.mode === "resume" && !compatibleExisting) {
             throw new Error(`Task Role resume effective snapshot drifted: ${task.id}/${role.name}.`);
         }
@@ -309,6 +348,9 @@ export class FileRoleLaunchPlanner {
                 nativeSessionId: resumeNativeSessionId
             })
             : adapter.compileNew(compileInput);
+        if (owner.scope === "task" && sessionContext.managedContextFile !== undefined) {
+            this.#resourceRegistrar().registerSessionContext(sessionContext.managedContextFile, { home: resolve(this.home), taskId: owner.taskId, basis: "descriptor" });
+        }
         let args = [...compiled.argv];
         let session;
         if (binding.adapterId === "codex") {
@@ -365,7 +407,15 @@ export class FileRoleLaunchPlanner {
             ? undefined
             : exactTaskRuntimeDescriptorPath(this.home, runtimeDescriptor);
         if (runtimeDescriptor !== undefined && runtimeDescriptorSource !== undefined) {
-            writeTextFileAtomically(runtimeDescriptorSource, `${serializeExactDescriptor(runtimeDescriptor)}\n`);
+            this.#writeExactTaskRuntimeDescriptor(runtimeDescriptor, runtimeDescriptorSource);
+        }
+        // rr13/rr26: Generate a per-Session DurableJob caller key for every
+        // task-scope launch, including resume.  Resume/ensure may reuse a live
+        // host, so its candidate hash is committed by TmuxSessionHost only when
+        // hostCreated=true; otherwise the live process keeps its existing key.
+        let jobCallerKey;
+        if (owner.scope === "task" && (input.mode === "new" || input.mode === "resume")) {
+            jobCallerKey = randomBytes(32).toString("hex");
         }
         const launch = {
             command: configured.command,
@@ -379,6 +429,7 @@ export class FileRoleLaunchPlanner {
                 YUI_AGENT_ID: configured.id,
                 YUI_ADAPTER_ID: configured.adapterId,
                 YUI_WORKSPACE: effectiveWorkspace,
+                ...(jobCallerKey === undefined ? {} : { YUI_JOB_CALLER_KEY: jobCallerKey }),
                 ...(runtimeDescriptor === undefined
                     ? {}
                     : {
@@ -439,6 +490,10 @@ export class FileRoleLaunchPlanner {
             }
         };
     }
+    #writeExactTaskRuntimeDescriptor(descriptor, sourcePath) {
+        writeTextFileAtomically(sourcePath, `${serializeExactDescriptor(descriptor)}\n`);
+        this.#resourceRegistrar().registerExactTaskRuntimeDescriptor(descriptor, sourcePath);
+    }
     #selectConfiguredAgentEnvironment(source) {
         const selected = {};
         for (const agent of this.store.listConfiguredAgents()) {

package/dist/grant/capabilityGrant.js

@@ -0,0 +1,282 @@
+import { requireIdentity, requireText, requireTimestamp, requirePositiveInteger } from "../domain/validation.js";
+import { validateTaskRecordReference } from "../task/taskRecordReference.js";
+export const CAPABILITY_GRANT_SCHEMA_VERSION = 1;
+const IRREVERSIBILITY_RANK = {
+    none: 0,
+    reversible: 1,
+    irreversible: 2
+};
+export function createCapabilityGrant(id, taskId, input, now) {
+    const timestamp = now.toISOString();
+    return validateCapabilityGrant({
+        schemaVersion: CAPABILITY_GRANT_SCHEMA_VERSION,
+        id: validateTaskRecordReference({ taskId, localId: id }, "capabilityGrant").localId,
+        taskId: requireIdentity(taskId, "Task id"),
+        granter: requireText(input.granter, "Capability grant granter"),
+        scope: normalizeScope(input.scope, taskId),
+        actions: normalizeActions(input.actions),
+        parameterBounds: normalizeParameterBounds(input.parameterBounds),
+        ...(input.expiresAt === undefined ? {} : { expiresAt: requireTimestamp(input.expiresAt, "Capability grant expiresAt") }),
+        ...(input.maxUses === undefined ? {} : { maxUses: requirePositiveInteger(input.maxUses, "Capability grant maxUses") }),
+        usesUsed: 0,
+        irreversibilityCeiling: normalizeCeiling(input.irreversibilityCeiling),
+        createdAt: timestamp,
+        updatedAt: timestamp
+    });
+}
+/**
+ * The pure authorization decision. Every denial carries a distinct
+ * machine-readable reason so a release workflow can fail closed precisely.
+ *
+ * `skipUsesCheck` is used when re-attempting a step that was already running:
+ * the grant use was already consumed for this step before the crash, so the
+ * uses check is skipped to avoid stranding the workflow.
+ */
+export function checkGrant(grant, request, now, options) {
+    validateCapabilityGrant(grant);
+    if (grant.revokedAt !== undefined) {
+        return { allowed: false, reason: "grant-revoked" };
+    }
+    if (grant.expiresAt !== undefined && now.getTime() > Date.parse(grant.expiresAt)) {
+        return { allowed: false, reason: "grant-expired" };
+    }
+    if (!options?.skipUsesCheck && grant.maxUses !== undefined && grant.usesUsed >= grant.maxUses) {
+        return { allowed: false, reason: "grant-uses-exhausted" };
+    }
+    if (!grant.actions.includes(request.action)) {
+        return { allowed: false, reason: "grant-action-not-allowed" };
+    }
+    for (const [name, allowedValues] of Object.entries(grant.parameterBounds)) {
+        const value = request.params?.[name];
+        if (value === undefined) {
+            return { allowed: false, reason: "grant-parameter-missing" };
+        }
+        if (!allowedValues.includes(value)) {
+            return { allowed: false, reason: "grant-parameter-value-not-allowed" };
+        }
+    }
+    const requested = IRREVERSIBILITY_RANK[request.irreversibility ?? "none"];
+    if (requested > IRREVERSIBILITY_RANK[grant.irreversibilityCeiling]) {
+        return { allowed: false, reason: "grant-irreversibility-exceeds-ceiling" };
+    }
+    return { allowed: true };
+}
+/** The reservation keys recorded on a grant, or an empty list for legacy grants. */
+export function grantUseReservations(grant) {
+    return grant.useReservations ?? [];
+}
+/**
+ * Record one use against the grant, failing closed once the limit is reached.
+ * When `reservationKey` is supplied it is appended to the grant's durable
+ * reservations so a later resume can recognize this exact attempt and avoid a
+ * double charge. A use recorded without a key (legacy callers) leaves the
+ * reservation list untouched.
+ */
+export function recordGrantUse(grant, now, reservationKey) {
+    validateCapabilityGrant(grant);
+    if (grant.maxUses !== undefined && grant.usesUsed >= grant.maxUses) {
+        throw new Error(`Capability grant is exhausted: ${grant.id}.`);
+    }
+    return validateCapabilityGrant({
+        ...grant,
+        usesUsed: grant.usesUsed + 1,
+        ...(reservationKey === undefined
+            ? {}
+            : { useReservations: Object.freeze([...grantUseReservations(grant), reservationKey]) }),
+        updatedAt: now.toISOString()
+    });
+}
+/**
+ * Revoke a grant. Re-revoking an already-revoked grant is idempotent: the
+ * original revocation stands and the record is returned unchanged.
+ */
+export function revokeGrant(grant, revokedBy, now) {
+    validateCapabilityGrant(grant);
+    if (grant.revokedAt !== undefined)
+        return grant;
+    const actor = requireText(revokedBy, "Capability grant revokedBy");
+    const timestamp = now.toISOString();
+    return validateCapabilityGrant({
+        ...grant,
+        revokedAt: timestamp,
+        revokedBy: actor,
+        updatedAt: timestamp
+    });
+}
+export function validateCapabilityGrant(grant) {
+    if (grant.schemaVersion !== CAPABILITY_GRANT_SCHEMA_VERSION) {
+        throw new Error("Capability grant must use schemaVersion 1.");
+    }
+    validateTaskRecordReference({ taskId: grant.taskId, localId: grant.id }, "capabilityGrant");
+    requireIdentity(grant.taskId, "Task id");
+    requireText(grant.granter, "Capability grant granter");
+    validateScope(grant.scope, grant.taskId);
+    normalizeActions(grant.actions);
+    normalizeParameterBounds(grant.parameterBounds);
+    if (grant.expiresAt !== undefined) {
+        requireTimestamp(grant.expiresAt, "Capability grant expiresAt");
+    }
+    if (grant.maxUses !== undefined) {
+        requirePositiveInteger(grant.maxUses, "Capability grant maxUses");
+    }
+    if (!Number.isSafeInteger(grant.usesUsed) || grant.usesUsed < 0) {
+        throw new Error("Capability grant usesUsed must be a non-negative integer.");
+    }
+    if (grant.maxUses !== undefined && grant.usesUsed > grant.maxUses) {
+        throw new Error("Capability grant usesUsed cannot exceed maxUses.");
+    }
+    if (grant.useReservations !== undefined) {
+        if (!Array.isArray(grant.useReservations)) {
+            throw new Error("Capability grant useReservations must be an array.");
+        }
+        for (const key of grant.useReservations) {
+            if (typeof key !== "string" || key.length === 0) {
+                throw new Error("Capability grant useReservations must be non-empty strings.");
+            }
+        }
+        if (new Set(grant.useReservations).size !== grant.useReservations.length) {
+            throw new Error("Capability grant useReservations must be unique.");
+        }
+        if (grant.useReservations.length > grant.usesUsed) {
+            throw new Error("Capability grant useReservations cannot outnumber usesUsed.");
+        }
+    }
+    normalizeCeiling(grant.irreversibilityCeiling);
+    if ((grant.revokedAt === undefined) !== (grant.revokedBy === undefined)) {
+        throw new Error("Capability grant revocation requires both revokedAt and revokedBy.");
+    }
+    if (grant.revokedAt !== undefined) {
+        requireTimestamp(grant.revokedAt, "Capability grant revokedAt");
+        requireText(grant.revokedBy, "Capability grant revokedBy");
+    }
+    requireTimestamp(grant.createdAt, "Capability grant createdAt");
+    requireTimestamp(grant.updatedAt, "Capability grant updatedAt");
+    return grant;
+}
+function normalizeCeiling(value) {
+    if (value === undefined)
+        return "none";
+    if (!Object.hasOwn(IRREVERSIBILITY_RANK, value)) {
+        throw new Error(`Capability grant irreversibility ceiling is invalid: ${String(value)}.`);
+    }
+    return value;
+}
+function normalizeActions(actions) {
+    if (!Array.isArray(actions) || actions.length === 0) {
+        throw new Error("Capability grant actions must be a non-empty array.");
+    }
+    const normalized = actions.map((action) => requireText(action, "Capability grant action"));
+    if (new Set(normalized).size !== normalized.length) {
+        throw new Error("Capability grant actions must be unique.");
+    }
+    return Object.freeze(normalized);
+}
+function normalizeParameterBounds(bounds) {
+    if (bounds === undefined)
+        return Object.freeze({});
+    if (typeof bounds !== "object" || bounds === null || Array.isArray(bounds)) {
+        throw new Error("Capability grant parameterBounds must be an object.");
+    }
+    const normalized = {};
+    for (const [name, values] of Object.entries(bounds)) {
+        const key = requireIdentity(name, "Capability grant parameter");
+        if (!Array.isArray(values) || values.length === 0) {
+            throw new Error(`Capability grant parameter bound must list allowed values: ${name}.`);
+        }
+        const allowed = values.map((value) => requireText(value, `Capability grant parameter ${name} value`));
+        if (new Set(allowed).size !== allowed.length) {
+            throw new Error(`Capability grant parameter bound values must be unique: ${name}.`);
+        }
+        normalized[key] = Object.freeze(allowed);
+    }
+    return Object.freeze(normalized);
+}
+function normalizeScope(scope, taskId) {
+    if (scope === undefined)
+        return Object.freeze({ taskId });
+    validateScope(scope, taskId);
+    const normalized = {
+        ...(scope.taskId === undefined ? {} : { taskId: requireIdentity(scope.taskId, "Capability grant scope taskId") }),
+        ...(scope.projectIds === undefined || scope.projectIds.length === 0
+            ? {}
+            : { projectIds: normalizeScopeIdentities(scope.projectIds, "Capability grant scope Project") }),
+        ...(scope.repositories === undefined || scope.repositories.length === 0
+            ? {}
+            : { repositories: normalizeRepositories(scope.repositories) }),
+        ...(scope.packages === undefined || scope.packages.length === 0
+            ? {}
+            : { packages: normalizeScopeText(scope.packages, "Capability grant scope package") }),
+        ...(scope.homePath === undefined ? {} : { homePath: requireText(scope.homePath, "Capability grant scope homePath") })
+    };
+    if (!hasScopeSelector(normalized)) {
+        return Object.freeze({ taskId });
+    }
+    return Object.freeze(normalized);
+}
+function validateScope(scope, taskId) {
+    if (typeof scope !== "object" || scope === null || Array.isArray(scope)) {
+        throw new Error("Capability grant scope must be an object.");
+    }
+    if (scope.taskId !== undefined) {
+        requireIdentity(scope.taskId, "Capability grant scope taskId");
+    }
+    if (scope.projectIds !== undefined) {
+        normalizeScopeIdentities(scope.projectIds, "Capability grant scope Project");
+    }
+    if (scope.repositories !== undefined) {
+        normalizeRepositories(scope.repositories);
+    }
+    if (scope.packages !== undefined) {
+        normalizeScopeText(scope.packages, "Capability grant scope package");
+    }
+    if (scope.homePath !== undefined) {
+        requireText(scope.homePath, "Capability grant scope homePath");
+    }
+    if (!hasScopeSelector(scope) && scope.taskId === undefined) {
+        throw new Error(`Capability grant scope requires at least one selector: ${taskId}.`);
+    }
+}
+function hasScopeSelector(scope) {
+    return scope.taskId !== undefined
+        || (scope.projectIds?.length ?? 0) > 0
+        || (scope.repositories?.length ?? 0) > 0
+        || (scope.packages?.length ?? 0) > 0
+        || scope.homePath !== undefined;
+}
+function normalizeScopeIdentities(values, label) {
+    if (!Array.isArray(values))
+        throw new Error(`${label} ids must be an array.`);
+    const normalized = values.map((value) => requireIdentity(value, label));
+    if (new Set(normalized).size !== normalized.length) {
+        throw new Error(`${label} ids must be unique.`);
+    }
+    return Object.freeze(normalized);
+}
+function normalizeScopeText(values, label) {
+    if (!Array.isArray(values))
+        throw new Error(`${label}s must be an array.`);
+    const normalized = values.map((value) => requireText(value, label));
+    if (new Set(normalized).size !== normalized.length) {
+        throw new Error(`${label}s must be unique.`);
+    }
+    return Object.freeze(normalized);
+}
+function normalizeRepositories(repositories) {
+    if (!Array.isArray(repositories)) {
+        throw new Error("Capability grant scope repositories must be an array.");
+    }
+    const normalized = repositories.map((repository) => {
+        if (typeof repository !== "object" || repository === null) {
+            throw new Error("Capability grant scope repository is invalid.");
+        }
+        return Object.freeze({
+            owner: requireText(repository.owner, "Capability grant scope repository owner"),
+            name: requireText(repository.name, "Capability grant scope repository name")
+        });
+    });
+    const keys = new Set(normalized.map(({ owner, name }) => `${owner}/${name}`));
+    if (keys.size !== normalized.length) {
+        throw new Error("Capability grant scope repositories must be unique.");
+    }
+    return Object.freeze(normalized);
+}

package/dist/integration/changeSet.js

@@ -1,16 +1,20 @@
 import { normalizedUniqueText, requireIdentity, requireText, requireTimestamp } from "../domain/validation.js";
 import { validateTaskRecordReference } from "../task/taskRecordReference.js";
+import { validateChangeSetManifest } from "./changeSetManifest.js";
 export function createWorkItemChangeSet(input, now) {
     return validateChangeSet({
-        schemaVersion: 2,
+        schemaVersion: 3,
         ...input,
         changedPaths: [...input.changedPaths],
+        ...(input.manifest === undefined
+            ? {}
+            : { manifest: validateChangeSetManifest(input.manifest) }),
         createdAt: now.toISOString()
     });
 }
 export function validateChangeSet(changeSet) {
-    if (changeSet.schemaVersion !== 2)
-        throw new Error("ChangeSet must use schemaVersion 2.");
+    if (changeSet.schemaVersion !== 3)
+        throw new Error("ChangeSet must use schemaVersion 3.");
     validateTaskRecordReference({ taskId: changeSet.taskId, localId: changeSet.id }, "changeSet");
     validateTaskRecordReference({
         taskId: changeSet.taskId,
@@ -24,6 +28,15 @@ export function validateChangeSet(changeSet) {
     }
     requireText(changeSet.branch, "ChangeSet branch");
     normalizedUniqueText(changeSet.changedPaths, "ChangeSet path");
+    if (changeSet.manifest !== undefined) {
+        const manifest = validateChangeSetManifest(changeSet.manifest);
+        const changed = new Set(changeSet.changedPaths);
+        for (const deleted of manifest.deletedPaths) {
+            if (!changed.has(deleted)) {
+                throw new Error(`ChangeSet manifest deleted path is not a changed path: ${deleted}.`);
+            }
+        }
+    }
     requireTimestamp(changeSet.createdAt, "ChangeSet createdAt");
     return changeSet;
 }

package/dist/integration/changeSetManifest.js

@@ -0,0 +1,46 @@
+import { normalizedUniqueText, requireText } from "../domain/validation.js";
+export const CHANGE_SET_MANIFEST_SCHEMA_VERSION = 1;
+export const CHANGE_SET_MANIFEST_TAGS = [
+    "contract",
+    "schema",
+    "migration",
+    "command",
+    "test",
+    "snapshot",
+    "package",
+    "deletion"
+];
+export function createChangeSetManifest(input) {
+    return validateChangeSetManifest({
+        schemaVersion: CHANGE_SET_MANIFEST_SCHEMA_VERSION,
+        tags: [...input.tags],
+        deletedPaths: [...input.deletedPaths],
+        evidenceRefs: [...(input.evidenceRefs ?? [])],
+        ...(input.targetRef === undefined ? {} : { targetRef: input.targetRef })
+    });
+}
+export function validateChangeSetManifest(manifest) {
+    if (manifest.schemaVersion !== CHANGE_SET_MANIFEST_SCHEMA_VERSION) {
+        throw new Error("ChangeSet manifest must use schemaVersion 1.");
+    }
+    if (!Array.isArray(manifest.tags)) {
+        throw new Error("ChangeSet manifest tags must be an array.");
+    }
+    for (const tag of manifest.tags) {
+        if (!CHANGE_SET_MANIFEST_TAGS.includes(tag)) {
+            throw new Error(`ChangeSet manifest tag is invalid: ${String(tag)}.`);
+        }
+    }
+    const tags = normalizedUniqueText(manifest.tags, "ChangeSet manifest tag");
+    const deletedPaths = normalizedUniqueText(manifest.deletedPaths, "ChangeSet manifest deleted path");
+    const evidenceRefs = normalizedUniqueText(manifest.evidenceRefs ?? [], "ChangeSet manifest evidence reference");
+    return {
+        schemaVersion: CHANGE_SET_MANIFEST_SCHEMA_VERSION,
+        tags,
+        deletedPaths,
+        evidenceRefs,
+        ...(manifest.targetRef === undefined ? {} : {
+            targetRef: requireText(manifest.targetRef, "ChangeSet manifest target ref")
+        })
+    };
+}