@yansirplus/cli 0.5.17

package/dist/build/agent-authoring/manifest-compiler.js

@@ -0,0 +1,737 @@
+import { isAgentSchema } from "@yansirplus/core/agent-schema";
+import { authoredValue } from "@yansirplus/core/authored-value";
+import { isAuthorityRef } from "@yansirplus/core/effect-claim";
+import { isMaterialRef } from "@yansirplus/core/material-ref";
+import { BUILTIN_HANDLER_KINDS } from "@yansirplus/core/runtime-protocol";
+import { WORKSPACE_TOOL_DEFAULT_DECLARATIONS, } from "@yansirplus/runtime";
+import { AUTHORING_DEFAULTS_VERSION, digestText, findFunctionPath, hasFunction, isNonEmptyString, isRecord, isWorkspaceToolName, } from "./shared.js";
+const defaultOrigin = (factKey) => `default:${AUTHORING_DEFAULTS_VERSION}#${factKey}`;
+export const workspaceManifestMacroOrigin = (factKey) => `macro(workspace@1)#${factKey}`;
+const authoredPath = (path) => (path.startsWith("agent/") ? path : `agent/${path}`);
+const authorOrigin = (path, pointer) => `author:${authoredPath(path)}#${pointer}`;
+const pathOrigin = (path) => `path:${authoredPath(path)}`;
+const isManifestMapId = (value) => value.length > 0 && !value.includes("/") && value !== "." && value !== "..";
+const isExtensionHandlerKind = (value) => {
+    const separator = value.indexOf(".");
+    return separator > 0 && separator < value.length - 1;
+};
+const isHandlerKind = (value) => typeof value === "string" &&
+    (BUILTIN_HANDLER_KINDS.includes(value) ||
+        isExtensionHandlerKind(value));
+const invalidAuthoredValue = (state, path, field, reason) => {
+    state.issues.push({ kind: "invalid_authored_value", path, field, reason });
+};
+const parseStringField = (state, path, field, value) => {
+    if (!isNonEmptyString(value)) {
+        invalidAuthoredValue(state, path, field, "non_empty_string_required");
+        return null;
+    }
+    return value;
+};
+const parseOptionalStringField = (state, path, field, value) => {
+    if (value === undefined)
+        return undefined;
+    return parseStringField(state, path, field, value) ?? undefined;
+};
+const parseStringArrayField = (state, path, field, value) => {
+    if (!Array.isArray(value)) {
+        invalidAuthoredValue(state, path, field, "array_required");
+        return null;
+    }
+    const out = [];
+    for (let index = 0; index < value.length; index += 1) {
+        const item = parseStringField(state, path, `${field}[${index}]`, value[index]);
+        if (item !== null)
+            out.push(item);
+    }
+    return out;
+};
+const parseHandlers = (state, path, value) => {
+    if (!Array.isArray(value)) {
+        invalidAuthoredValue(state, path, "/handlers", "array_required");
+        return null;
+    }
+    const handlers = [];
+    for (let index = 0; index < value.length; index += 1) {
+        const item = value[index];
+        if (!isHandlerKind(item)) {
+            invalidAuthoredValue(state, path, `/handlers/${index}`, "handler_kind_invalid");
+            continue;
+        }
+        handlers.push(item);
+    }
+    return handlers;
+};
+const parseScope = (state, path, value) => {
+    if (!isRecord(value)) {
+        invalidAuthoredValue(state, path, "/scope", "object_required");
+        return null;
+    }
+    assertAllowedFields(state, path, value, new Set(["kind", "idSource", "stableScopeId"]));
+    const kind = value.kind;
+    if (kind !== "realm" && kind !== "conversation" && kind !== "session" && kind !== "artifact") {
+        invalidAuthoredValue(state, path, "/scope/kind", "scope_kind_invalid");
+        return null;
+    }
+    const idSource = value.idSource;
+    if (idSource !== "submit_scope" && idSource !== "manifest" && idSource !== "extension") {
+        invalidAuthoredValue(state, path, "/scope/idSource", "scope_id_source_invalid");
+        return null;
+    }
+    const stableScopeId = parseOptionalStringField(state, path, "/scope/stableScopeId", value.stableScopeId);
+    return {
+        kind,
+        idSource,
+        ...(stableScopeId === undefined ? {} : { stableScopeId }),
+    };
+};
+const parseBindingRefObject = (state, path, field, value) => {
+    if (!isRecord(value)) {
+        invalidAuthoredValue(state, path, field, "object_required");
+        return null;
+    }
+    assertAllowedFields(state, path, value, new Set(["bindingRef"]));
+    const bindingRef = parseStringField(state, path, `${field}/bindingRef`, value.bindingRef);
+    return bindingRef === null ? null : { bindingRef };
+};
+const parseRecordMap = (state, path, field, value, parse) => {
+    if (!isRecord(value)) {
+        invalidAuthoredValue(state, path, field, "object_required");
+        return null;
+    }
+    const out = {};
+    for (const [id, child] of Object.entries(value)) {
+        if (!isManifestMapId(id)) {
+            invalidAuthoredValue(state, path, `${field}/${id}`, "id_invalid");
+            continue;
+        }
+        const parsed = parse(id, child);
+        if (parsed !== null)
+            out[id] = parsed;
+    }
+    return out;
+};
+const parseMaterialRef = (state, path, field, value) => {
+    if (!isMaterialRef(value)) {
+        invalidAuthoredValue(state, path, field, "material_ref_invalid");
+        return null;
+    }
+    return value;
+};
+const parseOutputSchema = (state, path, value) => {
+    if (!isRecord(value)) {
+        invalidAuthoredValue(state, path, "/outputSchema", "object_required");
+        return null;
+    }
+    assertAllowedFields(state, path, value, new Set(["agentSchema", "fingerprint"]));
+    if (!isAgentSchema(value.agentSchema) || !isNonEmptyString(value.fingerprint)) {
+        invalidAuthoredValue(state, path, "/outputSchema", "agent_schema_spec_invalid");
+        return null;
+    }
+    return {
+        agentSchema: value.agentSchema,
+        fingerprint: value.fingerprint,
+    };
+};
+const stripAgentPrefix = (path) => path.startsWith("agent/") ? path.slice("agent/".length) : path;
+const normalizePath = (path) => {
+    if (path.length === 0 || path.startsWith("/") || path.includes("\\"))
+        return null;
+    const parts = stripAgentPrefix(path).split("/");
+    if (parts.some((part) => part.length === 0 || part === "." || part === ".."))
+        return null;
+    return parts.join("/");
+};
+const registerPath = (state, path) => {
+    const normalized = normalizePath(path);
+    if (normalized === null) {
+        state.issues.push({ kind: "unsupported_path", path, reason: "path_not_normalized" });
+        return null;
+    }
+    const lower = normalized.toLocaleLowerCase();
+    const existing = state.pathKeys.get(lower);
+    if (existing !== undefined) {
+        state.issues.push({ kind: "duplicate_path", path: normalized, existingPath: existing });
+        return null;
+    }
+    state.pathKeys.set(lower, normalized);
+    return normalized;
+};
+const putFact = (state, factKey, value, origin, layer, overrideable) => {
+    const existing = state.facts.get(factKey);
+    if (existing === undefined) {
+        state.facts.set(factKey, { value, origin, layer, overrideable });
+        return;
+    }
+    if (existing.layer === layer) {
+        state.issues.push({ kind: "duplicate_fact", factKey, origins: [existing.origin, origin] });
+        return;
+    }
+    if (existing.layer > layer)
+        return;
+    if (!existing.overrideable) {
+        state.issues.push({
+            kind: "non_overrideable_fact",
+            factKey,
+            origins: [existing.origin, origin],
+        });
+        return;
+    }
+    state.facts.set(factKey, { value, origin, layer, overrideable });
+};
+const putDefault = (state, factKey, value) => putFact(state, factKey, value, defaultOrigin(factKey), 1, true);
+const putAuthored = (state, factKey, value, origin, overrideable = false) => putFact(state, factKey, value, origin, 3, overrideable);
+const assertAllowedFields = (state, path, value, allowed) => {
+    for (const field of Object.keys(value)) {
+        if (!allowed.has(field))
+            state.issues.push({ kind: "unknown_field", path, field });
+    }
+};
+const assertNoRuntimeFactFields = (state, path, value) => {
+    const forbidden = new Set([
+        "continuation",
+        "continuationRef",
+        "inputRequestRef",
+        "snapshot",
+        "actualTriggerTime",
+        "resumePayload",
+        "resolvedMaterial",
+        "secret",
+        "credential",
+    ]);
+    const visit = (record, fieldPrefix) => {
+        for (const [field, child] of Object.entries(record)) {
+            const fieldPath = fieldPrefix.length === 0 ? field : `${fieldPrefix}.${field}`;
+            if (forbidden.has(field)) {
+                state.issues.push({ kind: "runtime_fact_forbidden", path, field: fieldPath });
+            }
+            if (isRecord(child))
+                visit(child, fieldPath);
+            if (Array.isArray(child)) {
+                for (let index = 0; index < child.length; index += 1) {
+                    const item = child[index];
+                    if (isRecord(item))
+                        visit(item, `${fieldPath}[${index}]`);
+                }
+            }
+        }
+    };
+    visit(value, "");
+};
+const assertNoPathIdentityFields = (state, path, value) => {
+    for (const field of ["id", "name"]) {
+        if (Object.prototype.hasOwnProperty.call(value, field)) {
+            state.issues.push({ kind: "identity_field_forbidden", path, field });
+        }
+    }
+};
+const toolAllowedFields = new Set([
+    "bindingRef",
+    "executionDomain",
+    "interaction",
+    "materialRefs",
+    "effects",
+    "receiptPolicy",
+]);
+const domainAllowedFields = new Set(["bindingRef"]);
+const interactionAllowedFields = new Set(["bindingRef"]);
+const agentAllowedFields = new Set([
+    "agentId",
+    "version",
+    "scope",
+    "effectAuthorityRef",
+    "handlers",
+    "llmRoutes",
+    "tools",
+    "materials",
+    "executionDomains",
+    "interactions",
+    "outputSchema",
+]);
+const materialEffectNames = new Set(["material", "provider_call"]);
+const workspaceDefaultToolByName = new Map(WORKSPACE_TOOL_DEFAULT_DECLARATIONS.map((tool) => [tool.name, tool]));
+const workspaceInteractionRank = {
+    never: 0,
+    approval: 1,
+};
+const isEffectfulTool = (tool) => (tool.effects?.length ?? 0) > 0 || (tool.materialRefs?.length ?? 0) > 0;
+const requiresMaterial = (tool) => tool.materialRefs !== undefined ||
+    (tool.effects?.some((effect) => materialEffectNames.has(effect)) ?? false);
+const parseWorkspaceDefaultToolInteraction = (state, path, toolId, value) => {
+    if (value !== "never" && value !== "approval") {
+        invalidAuthoredValue(state, path, `/tools/${toolId}/interaction`, "interaction_invalid");
+        return null;
+    }
+    return value;
+};
+const recordWorkspaceDefaultToolControl = (state, path, toolId, control) => {
+    if (!isWorkspaceToolName(toolId)) {
+        state.issues.push({ kind: "unknown_workspace_default_tool_control", path, toolId });
+        return;
+    }
+    if (control === false) {
+        state.workspaceToolControls.set(toolId, {
+            kind: "disabled",
+            origin: authorOrigin(path, `/tools/${toolId}`),
+        });
+        return;
+    }
+    if (!isRecord(control)) {
+        invalidAuthoredValue(state, path, `/tools/${toolId}`, "object_or_false_required");
+        return;
+    }
+    for (const field of Object.keys(control)) {
+        if (field !== "interaction") {
+            state.issues.push({
+                kind: "workspace_default_tool_control_field_forbidden",
+                path,
+                toolId,
+                field,
+            });
+        }
+    }
+    const defaultTool = workspaceDefaultToolByName.get(toolId);
+    if (defaultTool === undefined) {
+        state.issues.push({ kind: "unknown_workspace_default_tool_control", path, toolId });
+        return;
+    }
+    const next = {
+        kind: "override",
+    };
+    if (Object.prototype.hasOwnProperty.call(control, "interaction")) {
+        const attempted = parseWorkspaceDefaultToolInteraction(state, path, toolId, control.interaction);
+        if (attempted !== null) {
+            if (workspaceInteractionRank[attempted] < workspaceInteractionRank[defaultTool.interaction]) {
+                state.issues.push({
+                    kind: "workspace_default_tool_interaction_weakened",
+                    path,
+                    toolId,
+                    floor: defaultTool.interaction,
+                    attempted,
+                });
+            }
+            else {
+                state.workspaceToolControls.set(toolId, {
+                    ...next,
+                    interaction: {
+                        value: attempted,
+                        origin: authorOrigin(path, `/tools/${toolId}/interaction`),
+                    },
+                });
+            }
+        }
+    }
+    else {
+        state.workspaceToolControls.set(toolId, next);
+    }
+};
+const recordToolFacts = (state, toolId, path, declaration, originFor) => {
+    state.toolIds.add(toolId);
+    const declarationRecord = declaration;
+    assertNoPathIdentityFields(state, path, declarationRecord);
+    if (Object.prototype.hasOwnProperty.call(declarationRecord, "kind")) {
+        state.issues.push({ kind: "identity_field_forbidden", path, field: "kind" });
+    }
+    assertAllowedFields(state, path, declarationRecord, toolAllowedFields);
+    assertNoRuntimeFactFields(state, path, declarationRecord);
+    const bindingRef = parseOptionalStringField(state, path, "/bindingRef", declaration.bindingRef);
+    const executionDomain = parseOptionalStringField(state, path, "/executionDomain", declaration.executionDomain);
+    const interaction = parseOptionalStringField(state, path, "/interaction", declaration.interaction);
+    const materialRefs = declaration.materialRefs === undefined
+        ? undefined
+        : parseStringArrayField(state, path, "/materialRefs", declaration.materialRefs);
+    const effects = declaration.effects === undefined
+        ? undefined
+        : parseStringArrayField(state, path, "/effects", declaration.effects);
+    const receiptPolicy = parseOptionalStringField(state, path, "/receiptPolicy", declaration.receiptPolicy);
+    putAuthored(state, `/tools/${toolId}/bindingRef`, bindingRef ?? `tool.${toolId}`, bindingRef === undefined ? pathOrigin(path) : originFor("bindingRef"));
+    if (executionDomain !== undefined) {
+        putAuthored(state, `/tools/${toolId}/executionDomain`, executionDomain, originFor("executionDomain"));
+    }
+    if (interaction !== undefined) {
+        putAuthored(state, `/tools/${toolId}/interaction`, interaction, originFor("interaction"));
+    }
+    if (materialRefs !== undefined) {
+        putAuthored(state, `/tools/${toolId}/materialRefs`, materialRefs, originFor("materialRefs"));
+    }
+    if (effects !== undefined) {
+        putAuthored(state, `/tools/${toolId}/effects`, effects, originFor("effects"));
+    }
+    if (receiptPolicy !== undefined) {
+        putAuthored(state, `/tools/${toolId}/receiptPolicy`, receiptPolicy, originFor("receiptPolicy"));
+    }
+};
+const recordAgentJson = (state, path, value) => {
+    if (!isRecord(value)) {
+        state.issues.push({ kind: "invalid_json_file", path, reason: "agent_json_not_object" });
+        return;
+    }
+    assertAllowedFields(state, path, value, agentAllowedFields);
+    assertNoRuntimeFactFields(state, path, value);
+    const agentId = parseOptionalStringField(state, path, "/agentId", value.agentId);
+    const version = parseOptionalStringField(state, path, "/version", value.version);
+    const scope = value.scope === undefined ? undefined : parseScope(state, path, value.scope);
+    const effectAuthorityRef = value.effectAuthorityRef === undefined
+        ? undefined
+        : isAuthorityRef(value.effectAuthorityRef)
+            ? value.effectAuthorityRef
+            : null;
+    if (value.effectAuthorityRef !== undefined && effectAuthorityRef === null) {
+        invalidAuthoredValue(state, path, "/effectAuthorityRef", "authority_ref_invalid");
+    }
+    const handlers = value.handlers === undefined ? undefined : parseHandlers(state, path, value.handlers);
+    const llmRoutes = value.llmRoutes === undefined
+        ? undefined
+        : parseRecordMap(state, path, "/llmRoutes", value.llmRoutes, (_route, child) => parseBindingRefObject(state, path, "/llmRoutes", child));
+    const outputSchema = value.outputSchema === undefined
+        ? undefined
+        : parseOutputSchema(state, path, value.outputSchema);
+    const materials = value.materials === undefined
+        ? undefined
+        : parseRecordMap(state, path, "/materials", value.materials, (_id, child) => parseMaterialRef(state, path, "/materials", child));
+    const executionDomains = value.executionDomains === undefined
+        ? undefined
+        : parseRecordMap(state, path, "/executionDomains", value.executionDomains, (_domainId, child) => parseBindingRefObject(state, path, "/executionDomains", child));
+    const interactions = value.interactions === undefined
+        ? undefined
+        : parseRecordMap(state, path, "/interactions", value.interactions, (_interactionId, child) => parseBindingRefObject(state, path, "/interactions", child));
+    if (value.tools !== undefined) {
+        if (!isRecord(value.tools)) {
+            invalidAuthoredValue(state, path, "/tools", "object_required");
+        }
+        else {
+            for (const [toolId, child] of Object.entries(value.tools)) {
+                if (!isManifestMapId(toolId)) {
+                    invalidAuthoredValue(state, path, `/tools/${toolId}`, "id_invalid");
+                    continue;
+                }
+                recordWorkspaceDefaultToolControl(state, path, toolId, child);
+            }
+        }
+    }
+    if (agentId !== undefined)
+        putAuthored(state, "/agentId", agentId, authorOrigin(path, "/agentId"));
+    if (version !== undefined)
+        putAuthored(state, "/version", version, authorOrigin(path, "/version"));
+    if (scope !== undefined && scope !== null) {
+        putAuthored(state, "/scope", scope, authorOrigin(path, "/scope"));
+    }
+    if (effectAuthorityRef !== undefined && effectAuthorityRef !== null) {
+        putAuthored(state, "/effectAuthorityRef", effectAuthorityRef, authorOrigin(path, "/effectAuthorityRef"));
+    }
+    if (handlers !== undefined && handlers !== null)
+        putAuthored(state, "/handlers", handlers, authorOrigin(path, "/handlers"));
+    if (llmRoutes !== undefined && llmRoutes !== null) {
+        for (const [route, ref] of Object.entries(llmRoutes)) {
+            putAuthored(state, `/llmRoutes/${route}/bindingRef`, ref.bindingRef, authorOrigin(path, `/llmRoutes/${route}/bindingRef`));
+        }
+    }
+    if (outputSchema !== undefined && outputSchema !== null) {
+        putAuthored(state, "/outputSchema", outputSchema, authorOrigin(path, "/outputSchema"));
+    }
+    if (materials !== undefined && materials !== null) {
+        for (const [materialId, materialRef] of Object.entries(materials)) {
+            putAuthored(state, `/materials/${materialId}`, materialRef, authorOrigin(path, `/materials/${materialId}`));
+        }
+    }
+    if (executionDomains !== undefined && executionDomains !== null) {
+        for (const [domainId, domainRef] of Object.entries(executionDomains)) {
+            putAuthored(state, `/executionDomains/${domainId}/bindingRef`, domainRef.bindingRef, authorOrigin(path, `/executionDomains/${domainId}/bindingRef`));
+        }
+    }
+    if (interactions !== undefined && interactions !== null) {
+        for (const [interactionId, interactionRef] of Object.entries(interactions)) {
+            putAuthored(state, `/interactions/${interactionId}/bindingRef`, interactionRef.bindingRef, authorOrigin(path, `/interactions/${interactionId}/bindingRef`));
+        }
+    }
+};
+const recordJsonFile = (state, path, value) => {
+    const parts = path.split("/");
+    if (path === "agent.json") {
+        recordAgentJson(state, path, value);
+        return;
+    }
+    if (parts.length !== 2 || !parts[1]?.endsWith(".json")) {
+        state.issues.push({ kind: "unsupported_path", path, reason: "json_path_not_in_grammar" });
+        return;
+    }
+    const id = parts[1].slice(0, -".json".length);
+    if (id.length === 0) {
+        state.issues.push({ kind: "unsupported_path", path, reason: "empty_path_identity" });
+        return;
+    }
+    if (!isRecord(value)) {
+        state.issues.push({ kind: "invalid_json_file", path, reason: "json_value_not_object" });
+        return;
+    }
+    assertNoPathIdentityFields(state, path, value);
+    assertNoRuntimeFactFields(state, path, value);
+    switch (parts[0]) {
+        case "materials": {
+            if (!isMaterialRef(value)) {
+                state.issues.push({ kind: "invalid_json_file", path, reason: "material_ref_invalid" });
+                return;
+            }
+            putAuthored(state, `/materials/${id}`, value, pathOrigin(path));
+            return;
+        }
+        case "domains":
+            if (Object.prototype.hasOwnProperty.call(value, "kind")) {
+                state.issues.push({ kind: "identity_field_forbidden", path, field: "kind" });
+            }
+            assertAllowedFields(state, path, value, domainAllowedFields);
+            const domainBindingRef = Object.prototype.hasOwnProperty.call(value, "bindingRef")
+                ? parseStringField(state, path, "/bindingRef", value.bindingRef)
+                : id;
+            putAuthored(state, `/executionDomains/${id}/bindingRef`, domainBindingRef ?? id, Object.prototype.hasOwnProperty.call(value, "bindingRef")
+                ? authorOrigin(path, "/bindingRef")
+                : pathOrigin(path));
+            return;
+        case "interactions":
+            if (Object.prototype.hasOwnProperty.call(value, "kind")) {
+                state.issues.push({ kind: "identity_field_forbidden", path, field: "kind" });
+            }
+            assertAllowedFields(state, path, value, interactionAllowedFields);
+            const interactionBindingRef = Object.prototype.hasOwnProperty.call(value, "bindingRef")
+                ? parseStringField(state, path, "/bindingRef", value.bindingRef)
+                : id;
+            putAuthored(state, `/interactions/${id}/bindingRef`, interactionBindingRef ?? id, Object.prototype.hasOwnProperty.call(value, "bindingRef")
+                ? authorOrigin(path, "/bindingRef")
+                : pathOrigin(path));
+            return;
+        default:
+            state.issues.push({ kind: "unsupported_path", path, reason: "json_path_not_in_grammar" });
+    }
+};
+const recordMarkdownFile = (state, path, text) => {
+    if (path !== "instructions.md") {
+        state.issues.push({ kind: "unsupported_path", path, reason: "markdown_path_not_in_grammar" });
+        return;
+    }
+    if (text.trim().length === 0)
+        state.issues.push({ kind: "empty_instructions", path });
+    const instructions = {
+        path: "agent/instructions.md",
+        digest: digestText(text),
+    };
+    putAuthored(state, "/instructions", instructions, pathOrigin(path));
+};
+const recordToolFile = (state, path, declaration) => {
+    const parts = path.split("/");
+    if (parts.length !== 2 || parts[0] !== "tools" || !parts[1]?.endsWith(".ts")) {
+        state.issues.push({ kind: "unsupported_path", path, reason: "tool_path_not_in_grammar" });
+        return;
+    }
+    const toolId = parts[1].slice(0, -".ts".length);
+    if (toolId.length === 0) {
+        state.issues.push({ kind: "unsupported_path", path, reason: "empty_path_identity" });
+        return;
+    }
+    state.toolFilePaths.set(toolId, path);
+    recordToolFacts(state, toolId, path, declaration ?? {}, (field) => authorOrigin(path, field));
+};
+const applyDefaults = (state) => {
+    putDefault(state, "/agentId", "agent");
+    const agentId = state.facts.get("/agentId")?.value;
+    putDefault(state, "/scope", { kind: "conversation", idSource: "submit_scope" });
+    putDefault(state, "/llmRoutes/default/bindingRef", "llm.default");
+    putDefault(state, "/handlers", []);
+    putDefault(state, "/executionDomains/app-runtime/bindingRef", "app-runtime");
+    putDefault(state, "/interactions/never/bindingRef", "never");
+    putDefault(state, "/interactions/approval/bindingRef", "approval");
+    putDefault(state, "/effectAuthorityRef", {
+        authorityClass: "agent",
+        authorityId: typeof agentId === "string" ? agentId : "agent",
+    });
+    for (const toolId of [...state.toolIds].sort()) {
+        const tool = collectToolConstraintState(state, toolId);
+        if (!tool.effectful) {
+            putDefault(state, `/tools/${toolId}/executionDomain`, "app-runtime");
+            putDefault(state, `/tools/${toolId}/interaction`, "never");
+        }
+    }
+};
+const enforceL0 = (state) => {
+    if (!state.facts.has("/instructions")) {
+        state.issues.push({ kind: "missing_required_file", path: "agent/instructions.md" });
+    }
+    for (const toolId of [...state.toolIds].sort()) {
+        const tool = collectToolConstraintState(state, toolId);
+        if (!tool.effectful)
+            continue;
+        if (tool.needsMaterial && (tool.materialRefs?.length ?? 0) === 0) {
+            state.issues.push({ kind: "effectful_tool_missing_material", toolId });
+        }
+        if (tool.executionDomain === undefined) {
+            state.issues.push({ kind: "effectful_tool_missing_execution_domain", toolId });
+        }
+        if (tool.interaction === undefined) {
+            state.issues.push({ kind: "effectful_tool_missing_interaction", toolId });
+        }
+        if (tool.receiptPolicy === undefined) {
+            state.issues.push({ kind: "effectful_tool_missing_receipt_policy", toolId });
+        }
+    }
+};
+const factValue = (state, factKey) => state.facts.get(factKey)?.value;
+const collectRecord = (state, prefix, make) => {
+    const ids = new Set();
+    for (const key of state.facts.keys()) {
+        if (!key.startsWith(prefix))
+            continue;
+        const rest = key.slice(prefix.length);
+        const id = rest.split("/")[0];
+        if (id.length > 0)
+            ids.add(id);
+    }
+    if (ids.size === 0)
+        return undefined;
+    const out = {};
+    for (const id of [...ids].sort()) {
+        const value = make(id);
+        if (value !== null)
+            out[id] = value;
+    }
+    return out;
+};
+const collectToolConstraintState = (state, toolId) => {
+    const effects = factValue(state, `/tools/${toolId}/effects`) ?? [];
+    const materialRefs = factValue(state, `/tools/${toolId}/materialRefs`);
+    const tool = { effects, materialRefs };
+    return {
+        executionDomain: factValue(state, `/tools/${toolId}/executionDomain`),
+        interaction: factValue(state, `/tools/${toolId}/interaction`),
+        materialRefs,
+        receiptPolicy: factValue(state, `/tools/${toolId}/receiptPolicy`),
+        effectful: isEffectfulTool(tool),
+        needsMaterial: requiresMaterial(tool),
+    };
+};
+const collectTool = (state, toolId) => {
+    const executionDomain = factValue(state, `/tools/${toolId}/executionDomain`);
+    const interaction = factValue(state, `/tools/${toolId}/interaction`);
+    const materialRefs = factValue(state, `/tools/${toolId}/materialRefs`);
+    const effects = factValue(state, `/tools/${toolId}/effects`);
+    const receiptPolicy = factValue(state, `/tools/${toolId}/receiptPolicy`);
+    return {
+        bindingRef: factValue(state, `/tools/${toolId}/bindingRef`) ?? `tool.${toolId}`,
+        ...(executionDomain === undefined ? {} : { executionDomain }),
+        ...(interaction === undefined ? {} : { interaction }),
+        ...(materialRefs === undefined ? {} : { materialRefs }),
+        ...(effects === undefined ? {} : { effects }),
+        ...(receiptPolicy === undefined ? {} : { receiptPolicy }),
+    };
+};
+const buildManifest = (state) => {
+    const version = factValue(state, "/version");
+    const instructions = factValue(state, "/instructions");
+    const llmRoutes = collectRecord(state, "/llmRoutes/", (id) => {
+        const bindingRef = factValue(state, `/llmRoutes/${id}/bindingRef`);
+        return bindingRef === undefined ? null : { bindingRef };
+    });
+    const tools = collectRecord(state, "/tools/", (id) => collectTool(state, id));
+    const materials = collectRecord(state, "/materials/", (id) => factValue(state, `/materials/${id}`) ?? null);
+    const executionDomains = collectRecord(state, "/executionDomains/", (id) => {
+        const bindingRef = factValue(state, `/executionDomains/${id}/bindingRef`);
+        return bindingRef === undefined ? null : { bindingRef };
+    });
+    const interactions = collectRecord(state, "/interactions/", (id) => {
+        const bindingRef = factValue(state, `/interactions/${id}/bindingRef`);
+        return bindingRef === undefined ? null : { bindingRef };
+    });
+    const outputSchema = factValue(state, "/outputSchema");
+    return {
+        agentId: factValue(state, "/agentId") ?? "agent",
+        scope: factValue(state, "/scope") ??
+            { kind: "conversation", idSource: "submit_scope" },
+        effectAuthorityRef: factValue(state, "/effectAuthorityRef") ??
+            { authorityClass: "agent", authorityId: "agent" },
+        handlers: factValue(state, "/handlers") ?? [],
+        ...(version === undefined ? {} : { version }),
+        ...(instructions === undefined ? {} : { instructions }),
+        ...(llmRoutes === undefined ? {} : { llmRoutes }),
+        ...(tools === undefined ? {} : { tools }),
+        ...(materials === undefined ? {} : { materials }),
+        ...(executionDomains === undefined ? {} : { executionDomains }),
+        ...(interactions === undefined ? {} : { interactions }),
+        ...(outputSchema === undefined ? {} : { outputSchema }),
+    };
+};
+const buildProvenance = (state) => {
+    const provenance = {};
+    for (const [key, fact] of [...state.facts.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+        provenance[key] = fact.origin;
+    }
+    return provenance;
+};
+const buildWorkspaceToolControls = (state) => {
+    const controls = {};
+    for (const [toolId, control] of [...state.workspaceToolControls.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+        controls[toolId] = control;
+    }
+    return controls;
+};
+const buildToolFilePaths = (state) => {
+    const paths = {};
+    for (const [toolId, path] of [...state.toolFilePaths.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+        paths[toolId] = path;
+    }
+    return paths;
+};
+/**
+ * Compile an authored `agent/` tree into one normalized manifest plus
+ * provenance. This is the app-author entrypoint; runtime facts and provider
+ * material are rejected before they can become manifest truth.
+ *
+ * @agentosPrimitive primitive.agent-authoring.compileAgentTree
+ * @agentosInvariant invariant.docs.agent-projection
+ * @agentosInvariant invariant.algebra.single-code-source
+ * @agentosDocs docs/guides/build-natural-language-workspace-agent.md
+ */
+export const compileAgentTree = (tree) => {
+    const state = {
+        facts: new Map(),
+        issues: [],
+        pathKeys: new Map(),
+        toolIds: new Set(),
+        toolFilePaths: new Map(),
+        workspaceToolControls: new Map(),
+    };
+    for (const file of tree.files) {
+        const path = registerPath(state, file.path);
+        if (path === null)
+            continue;
+        switch (file.kind) {
+            case "markdown":
+                recordMarkdownFile(state, path, file.text);
+                break;
+            case "json":
+                recordJsonFile(state, path, file.value);
+                break;
+            case "tool":
+                recordToolFile(state, path, file.declaration);
+                break;
+        }
+    }
+    applyDefaults(state);
+    enforceL0(state);
+    if (state.issues.length > 0)
+        return { ok: false, issues: state.issues };
+    const manifest = buildManifest(state);
+    const functionPath = findFunctionPath(manifest, "manifest");
+    if (functionPath !== null || hasFunction(manifest)) {
+        return {
+            ok: false,
+            issues: [{ kind: "function_in_manifest", path: functionPath ?? "manifest" }],
+        };
+    }
+    return {
+        ok: true,
+        value: {
+            manifest: authoredValue(manifest),
+            provenance: buildProvenance(state),
+            workspaceToolControls: buildWorkspaceToolControls(state),
+            toolFilePaths: buildToolFilePaths(state),
+        },
+    };
+};