@zq-silk/yui 0.6.16 → 0.7.0

package/dist/context/contextSnapshot.js

@@ -0,0 +1,228 @@
+import { createHash } from "node:crypto";
+import { normalizedUniqueText, optionalText, requireIdentity, requirePositiveInteger, requireText, requireTimestamp } from "../domain/validation.js";
+export const CONTEXT_SNAPSHOT_SCHEMA_VERSION = 1;
+export const CONTEXT_SNAPSHOT_MAX_RESOURCES = 256;
+export const CONTEXT_SNAPSHOT_MAX_RESOURCE_BYTES = 4 * 1024 * 1024;
+export const CONTEXT_SNAPSHOT_MAX_BYTES = 8 * 1024 * 1024;
+export const CONTEXT_REF_LAYERS = ["L1", "L2", "L3", "L4"];
+export const CONTEXT_SNAPSHOT_SCOPES = ["task", "workitem", "stage"];
+export function createContextSnapshot(input) {
+    const identity = snapshotIdentity(input);
+    const refs = normalizeContextRefs(input.refs);
+    const resources = normalizeSnapshotResources(input.resources, refs);
+    const acceptRefs = Object.freeze([...normalizedUniqueText(input.acceptRefs, "Context Snapshot acceptance reference")]
+        .sort((left, right) => left.localeCompare(right)));
+    const repoCommit = optionalText(input.repoCommit, "Context Snapshot repository commit");
+    const parentRef = input.parentRef === undefined
+        ? undefined
+        : validateContextSnapshotRef(input.parentRef);
+    if (parentRef !== undefined) {
+        if (parentRef.taskId !== identity.taskId) {
+            throw new Error("Context Snapshot parent belongs to another Task.");
+        }
+        if (parentRef.sequence >= identity.sequence) {
+            throw new Error("Context Snapshot parent sequence must precede its child.");
+        }
+    }
+    if (input.frozenBy !== "leader" && input.frozenBy !== "controller") {
+        throw new Error("Context Snapshot frozenBy is invalid.");
+    }
+    const frozenAt = requireTimestamp(input.frozenAt.toISOString(), "Context Snapshot frozenAt");
+    const digest = contentDigest({
+        taskId: identity.taskId,
+        scope: identity.scope,
+        ...(identity.scopeRef === undefined ? {} : { scopeRef: identity.scopeRef }),
+        sequence: identity.sequence,
+        refs,
+        resources,
+        ...(repoCommit === undefined ? {} : { repoCommit }),
+        acceptRefs,
+        ...(parentRef === undefined ? {} : { parentRef }),
+        frozenAt,
+        frozenBy: input.frozenBy
+    });
+    return Object.freeze({
+        schemaVersion: CONTEXT_SNAPSHOT_SCHEMA_VERSION,
+        ...identity,
+        digest,
+        refs,
+        resources,
+        ...(repoCommit === undefined ? {} : { repoCommit }),
+        acceptRefs,
+        ...(parentRef === undefined ? {} : { parentRef }),
+        frozenAt,
+        frozenBy: input.frozenBy
+    });
+}
+export function validateContextSnapshot(snapshot) {
+    if (snapshot.schemaVersion !== CONTEXT_SNAPSHOT_SCHEMA_VERSION) {
+        throw new Error("Context Snapshot must use schemaVersion 1.");
+    }
+    const identity = snapshotIdentity(snapshot);
+    const refs = normalizeContextRefs(snapshot.refs);
+    if (JSON.stringify(refs) !== JSON.stringify(snapshot.refs)) {
+        throw new Error("Context Snapshot refs must use canonical order.");
+    }
+    const resources = normalizeSnapshotResources(snapshot.resources, refs);
+    if (JSON.stringify(resources) !== JSON.stringify(snapshot.resources)) {
+        throw new Error("Context Snapshot resources must use canonical ref order.");
+    }
+    const acceptRefs = Object.freeze([...normalizedUniqueText(snapshot.acceptRefs, "Context Snapshot acceptance reference")]
+        .sort((left, right) => left.localeCompare(right)));
+    if (JSON.stringify(acceptRefs) !== JSON.stringify(snapshot.acceptRefs)) {
+        throw new Error("Context Snapshot acceptance refs must use canonical order.");
+    }
+    const repoCommit = optionalText(snapshot.repoCommit, "Context Snapshot repository commit");
+    const parentRef = snapshot.parentRef === undefined
+        ? undefined
+        : validateContextSnapshotRef(snapshot.parentRef);
+    if (parentRef !== undefined
+        && (parentRef.taskId !== identity.taskId || parentRef.sequence >= identity.sequence)) {
+        throw new Error("Context Snapshot parent is invalid.");
+    }
+    requireTimestamp(snapshot.frozenAt, "Context Snapshot frozenAt");
+    if (snapshot.frozenBy !== "leader" && snapshot.frozenBy !== "controller") {
+        throw new Error("Context Snapshot frozenBy is invalid.");
+    }
+    requireDigest(snapshot.digest, "Context Snapshot digest");
+    const expected = contentDigest({
+        taskId: identity.taskId,
+        scope: identity.scope,
+        ...(identity.scopeRef === undefined ? {} : { scopeRef: identity.scopeRef }),
+        sequence: identity.sequence,
+        refs,
+        resources,
+        ...(repoCommit === undefined ? {} : { repoCommit }),
+        acceptRefs,
+        ...(parentRef === undefined ? {} : { parentRef }),
+        frozenAt: snapshot.frozenAt,
+        frozenBy: snapshot.frozenBy
+    });
+    if (snapshot.digest !== expected) {
+        throw new Error("Context Snapshot digest does not match its content.");
+    }
+    return snapshot;
+}
+export function contextSnapshotRef(snapshot) {
+    validateContextSnapshot(snapshot);
+    return Object.freeze({
+        schemaVersion: CONTEXT_SNAPSHOT_SCHEMA_VERSION,
+        id: snapshot.id,
+        taskId: snapshot.taskId,
+        scope: snapshot.scope,
+        ...(snapshot.scopeRef === undefined ? {} : { scopeRef: snapshot.scopeRef }),
+        sequence: snapshot.sequence,
+        digest: snapshot.digest
+    });
+}
+export function validateContextSnapshotRef(ref) {
+    if (ref.schemaVersion !== CONTEXT_SNAPSHOT_SCHEMA_VERSION) {
+        throw new Error("Context Snapshot ref must use schemaVersion 1.");
+    }
+    const identity = snapshotIdentity(ref);
+    requireDigest(ref.digest, "Context Snapshot ref digest");
+    return Object.freeze({
+        schemaVersion: CONTEXT_SNAPSHOT_SCHEMA_VERSION,
+        ...identity,
+        digest: ref.digest
+    });
+}
+export function contextContentDigest(value) {
+    return contentDigest(value);
+}
+function snapshotIdentity(input) {
+    const id = requireIdentity(input.id, "Context Snapshot id");
+    const taskId = requireIdentity(input.taskId, "Context Snapshot Task id");
+    if (!CONTEXT_SNAPSHOT_SCOPES.includes(input.scope)) {
+        throw new Error("Context Snapshot scope is invalid.");
+    }
+    const scopeRef = optionalText(input.scopeRef, "Context Snapshot scope ref");
+    if (input.scope === "task" && scopeRef !== undefined) {
+        throw new Error("A task Context Snapshot cannot carry scopeRef.");
+    }
+    if (input.scope !== "task" && scopeRef === undefined) {
+        throw new Error(`A ${input.scope} Context Snapshot requires scopeRef.`);
+    }
+    return {
+        id,
+        taskId,
+        scope: input.scope,
+        ...(scopeRef === undefined ? {} : { scopeRef }),
+        sequence: requirePositiveInteger(input.sequence, "Context Snapshot sequence")
+    };
+}
+function normalizeContextRefs(values) {
+    if (!Array.isArray(values))
+        throw new Error("Context Snapshot refs must be an array.");
+    const refs = values.map(validateContextRef).sort((left, right) => (contextRefKey(left).localeCompare(contextRefKey(right))));
+    const keys = refs.map(contextRefKey);
+    if (new Set(keys).size !== keys.length) {
+        throw new Error("Context Snapshot refs must be unique.");
+    }
+    return Object.freeze(refs);
+}
+function validateContextRef(value) {
+    if (!CONTEXT_REF_LAYERS.includes(value.layer)) {
+        throw new Error("Context ref layer is invalid.");
+    }
+    const store = requireIdentity(value.store, "Context ref store");
+    const refId = requireText(value.refId, "Context ref id");
+    const revision = requireText(value.revision, "Context ref revision");
+    const digest = requireDigest(value.digest, "Context ref digest");
+    const summary = optionalText(value.summary, "Context ref summary");
+    const evidenceOf = optionalText(value.evidenceOf, "Context ref evidence target");
+    return Object.freeze({
+        layer: value.layer,
+        store,
+        refId,
+        revision,
+        digest,
+        ...(summary === undefined ? {} : { summary }),
+        ...(evidenceOf === undefined ? {} : { evidenceOf })
+    });
+}
+function normalizeSnapshotResources(values, refs) {
+    if (!Array.isArray(values))
+        throw new Error("Context Snapshot resources must be an array.");
+    if (values.length > CONTEXT_SNAPSHOT_MAX_RESOURCES) {
+        throw new Error(`Context Snapshot exceeds ${CONTEXT_SNAPSHOT_MAX_RESOURCES} resources.`);
+    }
+    const byRef = new Map(refs.map((ref) => [contextRefKey(ref), ref]));
+    const resources = values.map((resource) => {
+        if (resource === null || typeof resource !== "object" || Array.isArray(resource)) {
+            throw new Error("Context Snapshot resource must be an object.");
+        }
+        const ref = validateContextRef(resource.ref);
+        const exact = byRef.get(contextRefKey(ref));
+        if (exact === undefined || contextContentDigest(resource.value) !== ref.digest) {
+            throw new Error(`Context Snapshot resource does not match its ref: ${ref.store}/${ref.refId}.`);
+        }
+        const serialized = JSON.stringify(resource.value);
+        if (serialized === undefined) {
+            throw new Error("Context Snapshot resource value is not JSON serializable.");
+        }
+        if (Buffer.byteLength(serialized, "utf8") > CONTEXT_SNAPSHOT_MAX_RESOURCE_BYTES) {
+            throw new Error(`Context Snapshot resource exceeds ${CONTEXT_SNAPSHOT_MAX_RESOURCE_BYTES} bytes.`);
+        }
+        return Object.freeze({ ref: exact, value: resource.value });
+    }).sort((left, right) => contextRefKey(left.ref).localeCompare(contextRefKey(right.ref)));
+    if (resources.length !== refs.length
+        || new Set(resources.map(({ ref }) => contextRefKey(ref))).size !== refs.length) {
+        throw new Error("Context Snapshot resources must cover every ref exactly once.");
+    }
+    if (Buffer.byteLength(JSON.stringify(resources), "utf8") > CONTEXT_SNAPSHOT_MAX_BYTES) {
+        throw new Error(`Context Snapshot resources exceed ${CONTEXT_SNAPSHOT_MAX_BYTES} bytes.`);
+    }
+    return Object.freeze(resources);
+}
+function contextRefKey(ref) {
+    return [ref.layer, ref.store, ref.refId, ref.revision, ref.digest].join("\0");
+}
+function requireDigest(value, label) {
+    if (!/^[0-9a-f]{64}$/u.test(value))
+        throw new Error(`${label} must be SHA-256 hex.`);
+    return value;
+}
+function contentDigest(value) {
+    return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}

package/dist/context/roleSessionContext.js

@@ -4,6 +4,7 @@ import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { SYSTEM_LEADER_ROLE, SYSTEM_OPERATOR_ROLE } from "../role/systemRoles.js";
 const BUILTIN_YUI_SKILLS = new Set([
+    "yui-runtime",
     "yui-operator",
     "yui-leader",
     "yui-worker",
@@ -17,6 +18,7 @@ export function compileRoleSessionContext(yuiHome, role, owner, options = {}) {
     const kind = roleSessionKind(role, owner, options.purpose ?? "execution");
     const builtInSkillId = kind === "global" ? undefined : `yui-${kind}`;
     const skillIds = unique([
+        "yui-runtime",
         ...(builtInSkillId === undefined ? [] : [builtInSkillId]),
         ...(role.skills ?? [])
     ]);
@@ -40,7 +42,7 @@ function renderDeveloperInstructions(kind, role, owner) {
     ].filter((value) => value !== null);
     return [...core, ...profile].join("\n");
 }
-function roleSessionKind(role, owner, purpose) {
+export function roleSessionKind(role, owner, purpose) {
     if (owner.scope === "global") {
         return role.name === SYSTEM_OPERATOR_ROLE ? "operator" : "global";
     }

package/dist/context/runContextContract.js

@@ -0,0 +1,162 @@
+import { normalizedUniqueIdentities, requireIdentity, requireText } from "../domain/validation.js";
+import { validateContextSnapshotRef } from "./contextSnapshot.js";
+export const RUN_CONTEXT_PROTOCOL_VERSION = 1;
+export const RUN_BOOTSTRAP_PROTOCOL = "yui-run/v1";
+export const RUN_BOOTSTRAP_MAX_BYTES = 4 * 1024;
+export const RUN_BOOTSTRAP_MAX_DELTAS = 16;
+export const RUN_ACTIONS = [
+    "lead-task",
+    "leader-wake",
+    "execute-work-item",
+    "repair-work-item",
+    "review-round",
+    "review-delta",
+    "global-request"
+];
+export function createRunAssignment(input) {
+    const common = normalizeCommon(input);
+    return Object.freeze({
+        schemaVersion: RUN_CONTEXT_PROTOCOL_VERSION,
+        ...common,
+        ...(input.directive === undefined
+            ? {}
+            : { directive: requireText(input.directive, "Run assignment directive") })
+    });
+}
+export function validateRunAssignment(value) {
+    if (value.schemaVersion !== RUN_CONTEXT_PROTOCOL_VERSION) {
+        throw new Error("Run assignment must use schemaVersion 1.");
+    }
+    const normalized = createRunAssignment(value);
+    if (JSON.stringify(normalized) !== JSON.stringify(value)) {
+        throw new Error("Run assignment is not canonical.");
+    }
+    return value;
+}
+export function createRunBootstrapEnvelope(assignment) {
+    validateRunAssignment(assignment);
+    return Object.freeze({
+        protocol: RUN_BOOTSTRAP_PROTOCOL,
+        runId: assignment.runId,
+        roleName: assignment.roleName,
+        purpose: assignment.purpose,
+        action: assignment.action,
+        subject: assignment.subject,
+        ...(assignment.contextSnapshotRef === undefined
+            ? {}
+            : { contextSnapshotRef: assignment.contextSnapshotRef }),
+        deltaRefIds: assignment.deltaRefIds
+    });
+}
+export function validateRunBootstrapEnvelope(value) {
+    if (value.protocol !== RUN_BOOTSTRAP_PROTOCOL) {
+        throw new Error("Run bootstrap protocol is unsupported.");
+    }
+    normalizeCommon(value);
+    const serialized = serializeRunBootstrapEnvelope(value);
+    if (Buffer.byteLength(serialized, "utf8") > RUN_BOOTSTRAP_MAX_BYTES) {
+        throw new Error("Run bootstrap envelope exceeds its protocol byte limit.");
+    }
+    return value;
+}
+export function serializeRunBootstrapEnvelope(value) {
+    if (value.protocol !== RUN_BOOTSTRAP_PROTOCOL) {
+        throw new Error("Run bootstrap protocol is unsupported.");
+    }
+    const normalized = normalizeCommon(value);
+    const subject = Object.entries(normalized.subject)
+        .map(([key, id]) => `${key}:${id}`)
+        .join(",");
+    const snapshot = normalized.contextSnapshotRef;
+    const lines = [
+        "Yui managed Run. Follow the Session Manifest and injected Skills.",
+        `${normalized.subject.taskId === undefined ? "" : `task=${normalized.subject.taskId} `}run=${normalized.runId} role=${normalized.roleName} action=${normalized.action}`,
+        `purpose=${normalized.purpose} subject=${subject || "global"} snapshot=${snapshot === undefined ? "none" : `${snapshot.id}@${snapshot.digest}`}`,
+        normalized.deltaRefIds.length === 0
+            ? "delta=none"
+            : `delta=${normalized.deltaRefIds.join(",")}`,
+        "Load the exact Run context before acting; fail closed if it is unavailable or mismatched."
+    ];
+    const serialized = lines.join("\n");
+    if (Buffer.byteLength(serialized, "utf8") > RUN_BOOTSTRAP_MAX_BYTES) {
+        throw new Error("Run bootstrap envelope exceeds its protocol byte limit.");
+    }
+    return serialized;
+}
+/**
+ * Bounded infrastructure-recovery input for an already-pushed Run. It resumes
+ * the provider-native transcript after Host/child replacement and never
+ * replays the Assignment or its directive.
+ */
+export function serializeRunHostRecoveryEnvelope(value) {
+    const normalized = normalizeCommon(value);
+    const serialized = [
+        "Yui managed Host recovery for an existing Run.",
+        `${normalized.subject.taskId === undefined ? "" : `task=${normalized.subject.taskId} `}run=${normalized.runId} role=${normalized.roleName}`,
+        "Resume the same native conversation from its latest durable state. Do not repeat completed work or replay the original Assignment.",
+        "Load the exact Run context or delta only if needed, then continue toward the existing workflow outcome."
+    ].join("\n");
+    if (Buffer.byteLength(serialized, "utf8") > RUN_BOOTSTRAP_MAX_BYTES) {
+        throw new Error("Run Host recovery envelope exceeds its protocol byte limit.");
+    }
+    return serialized;
+}
+function normalizeCommon(input) {
+    if (!["execution", "review", "global"].includes(input.purpose)) {
+        throw new Error("Run assignment purpose is invalid.");
+    }
+    if (!RUN_ACTIONS.includes(input.action)) {
+        throw new Error("Run assignment action is invalid.");
+    }
+    const subject = normalizeSubject(input.subject);
+    const snapshot = input.contextSnapshotRef === undefined
+        ? undefined
+        : validateContextSnapshotRef(input.contextSnapshotRef);
+    if (snapshot !== undefined && snapshot.taskId !== subject.taskId) {
+        throw new Error("Run assignment Context Snapshot belongs to another Task.");
+    }
+    if (input.purpose !== "global" && subject.taskId === undefined) {
+        throw new Error("A Task Run assignment requires a Task subject.");
+    }
+    if (input.purpose === "review" && subject.reviewRoundId === undefined) {
+        throw new Error("A review Run assignment requires a ReviewRound subject.");
+    }
+    const deltaRefIds = normalizedUniqueIdentities(input.deltaRefIds, "Run assignment delta ref");
+    if (deltaRefIds.length > RUN_BOOTSTRAP_MAX_DELTAS) {
+        throw new Error(`Run assignment supports at most ${RUN_BOOTSTRAP_MAX_DELTAS} delta refs.`);
+    }
+    return {
+        runId: requireIdentity(input.runId, "Run assignment Run id"),
+        roleName: requireIdentity(input.roleName, "Run assignment Role name"),
+        purpose: input.purpose,
+        action: input.action,
+        subject,
+        ...(snapshot === undefined ? {} : { contextSnapshotRef: snapshot }),
+        deltaRefIds
+    };
+}
+function normalizeSubject(subject) {
+    const normalized = Object.fromEntries(Object.entries(subject).map(([key, value]) => [
+        key,
+        requireIdentity(value, `Run assignment ${key}`)
+    ]));
+    const allowed = [
+        "taskId",
+        "workItemId",
+        "reviewRoundId",
+        "executionGroupId",
+        "executionLaneId"
+    ];
+    if (Object.keys(normalized).some((key) => !allowed.includes(key))) {
+        throw new Error("Run assignment subject contains an unknown field.");
+    }
+    if ((normalized.executionGroupId === undefined) !== (normalized.executionLaneId === undefined)) {
+        throw new Error("Run assignment execution lineage is incomplete.");
+    }
+    if (normalized.taskId === undefined
+        && (normalized.workItemId !== undefined || normalized.reviewRoundId !== undefined
+            || normalized.executionGroupId !== undefined)) {
+        throw new Error("Run assignment child subject requires a Task id.");
+    }
+    return Object.freeze(normalized);
+}