biz-a-cli 2.3.80-15390 → 2.3.80-15397

package/bin/hubEvent.js

@@ -28,6 +28,11 @@ import { authorizeRequest, principalForCliScript } from "../security/internalPri
 import { whoami } from "../security/whoami.js";
 import { runDraftAction } from "../engine/cc/draftStore.js";
 import { createPgDraftRepo } from "../engine/cc/pgRepo.js";
+import { runMapAction } from "../engine/cc/mapStore.js";
+import { createMapRepo } from "../engine/cc/mapRepo.js";
+import { createGapRepo } from "../engine/cc/gapRepo.js";
+import { createTraceRepo } from "../engine/cc/traceRepo.js";
+import { createConfigReader } from "../engine/cc/currentConfig.js";
 import { runAiAction } from "../engine/cc/aiTurns.js";
 import { createTurnRepo } from "../engine/cc/turnRepo.js";
 import { createAiGatewayClient } from "../security/aiGatewayClient.js";
@@ -458,6 +463,31 @@ const EngineRegistry = {
 		import("../engine/domain/applicationConfig.js"),
 };
 
+/* Doc 1 step 3 — what a Phase B turn needs: the draft store, the gap list, a draft opener that applies the
+   draft store's own rules (Layer 3, owned by Control Center) for the VERIFIED caller, one transaction, and
+   the publisher's DDL preview. */
+async function phaseBDeps(argv, headers) {
+	const exec = (sql) => execPostgres(sql, argv["dbindex"]);
+	const execStatements = (statements) => execPostgresStatements(statements, argv["dbindex"]);
+	const draftRepo = createPgDraftRepo({ exec, execStatements });
+	const principal = principalForCliScript(headers, { mode: argv["principalMode"] || "observe" });
+	const { buildDomainDdlPreview } = await import("../engine/domain/appConfig.js");
+	return {
+		draftRepo,
+		gapRepo: createGapRepo({ exec }),
+		traceRepo: createTraceRepo({ exec }),
+		openDraft: (kind, name) => runDraftAction({ repo: draftRepo, principal, isPostgres: true, action: "open", args: { kind, name } }),
+		execStatements,
+		ddlWarnings: (content) => buildDomainDdlPreview(JSON.stringify(content), argv["dbindex"]).warnings ?? [],
+	};
+}
+
+/* Doc 1 step 4d — what a derive turn reads: the configs as they are now (the OPEN draft, else published). */
+function deriveDeps(argv) {
+	const draftRepo = createPgDraftRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) });
+	return { draftRepo, readConfig: createConfigReader(draftRepo) };
+}
+
 const handleCliCommand = async (data, cb, argv) => {
 	try {
 		const command = data.command.trim().toLowerCase();
@@ -660,6 +690,13 @@ const handleCliCommand = async (data, cb, argv) => {
 			case "ccai": {
 				const aiResult = await runAiAction({
 					repo: createTurnRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) }),
+					/* Doc 1 step 2: an interview turn commits the process map. Step 4d: a derive turn commits it WITH its
+					   trace links, in one transaction. */
+					mapRepo: createMapRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]), execStatements: (statements) => execPostgresStatements(statements, argv["dbindex"]) }),
+					/* Doc 1 step 4: an interview turn never removes what config implements. */
+					traceRepo: createTraceRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) }),
+					/* Doc 1 step 3: a Phase B turn writes drafts, gaps and trace links in ONE transaction. */
+					config: ["generate", "refine"].includes(data.action) ? await phaseBDeps(argv, data.headers) : data.action === "derive" ? deriveDeps(argv) : undefined,
 					gateway: createAiGatewayClient({ baseUrl: argv["aiGateway"] || argv["server"], subdomain: argv["subdomain"] }),
 					principal: principalForCliScript(data.headers, { mode: argv["principalMode"] || "observe" }),
 					isPostgres: isPostgresIndex(argv["dbindex"]),
@@ -698,6 +735,31 @@ const handleCliCommand = async (data, cb, argv) => {
 				});
 				break;
 			}
+			/*
+			 * Doc 1 step 1 — the Business Process Map behind Process Studio (engine/cc/mapStore.js):
+			 * get / versions / save. A save is a new SYS$CC_PROCESS_MAP version, merged per element.
+			 */
+			case "ccmap": {
+				const mapResult = await runMapAction({
+					repo: createMapRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) }),
+					gapRepo: createGapRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) }),
+					/* Doc 1 step 4: the trace panel — the links, the turns that told the story, the config they point at. */
+					traceRepo: createTraceRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) }),
+					turnRepo: createTurnRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) }),
+					readConfig: createConfigReader(createPgDraftRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) })),
+					principal: principalForCliScript(data.headers, { mode: argv["principalMode"] || "observe" }),
+					isPostgres: isPostgresIndex(argv["dbindex"]),
+					action: data.action,
+					args: data.args,
+				});
+				cb(null, {
+					success: mapResult.ok,
+					...(mapResult.code ? { code: mapResult.code } : {}),
+					problems: mapResult.problems ?? [],
+					data: mapResult.data ?? null,
+				});
+				break;
+			}
 			case "runextcliscript": {
 				// External-access op invoker — enforces the capability boundary (dispatch.js),
 				// unlike raw `runcliscript`. Safe to expose: no valid token -> UNAUTHENTICATED.

package/engine/bpm/workflow-runtime.js

@@ -218,14 +218,14 @@ export async function initiate(payload) {
 		current_state_code: def.initial_state_code,
 		status: "ACTIVE",
 		version_no: def.version,
-		created_by: userId || null,
+		created_by: userId ?? null,
 		SYS$BPM_STATE_HISTORY: [
 			{
 				from_state_code: null,
 				to_state_code: def.initial_state_code,
 				trigger_type: "SYSTEM",
 				actor_type: "USER",
-				actor_id: userId || null,
+				actor_id: userId ?? null,
 				request_id: `START_${entityType}_${entityId}_${new Date().getTime()}`,
 			},
 		],
@@ -773,7 +773,7 @@ export async function terminate(payload) {
 			to_state_code: currentStateCode,
 			trigger_type: "USER_EVENT",
 			actor_type: "USER",
-			actor_id: userId || null,
+			actor_id: userId ?? null,
 			request_id: `TERMINATE_${instanceId}_${new Date().getTime()}`,
 		},
 	};

package/engine/cc/aiTurns.js

@@ -16,12 +16,43 @@
  *   usage   this company's month — limit and spend — from the gateway.
  *   settle  the AI Assist panel reports what it did with a turn's tool calls (COMMITTED / ROLLED_BACK).
  *
+ *   interview  Doc 1 step 2 — a Phase A turn: the CLI runs the whole model <-> map-tools loop and commits the
+ *              map (phaseA.js). Answers AT ONCE with {turnId}; the user is told the outcome when it ends.
+ *   session    the caller's turns of one interview session, oldest first — the chat to show.
+ *   generate   Doc 1 step 3 — Phase B, the initial generation of ONE ready function into Layer 3 drafts of the
+ *              domains the implementor names (phaseB.js). Refused unless the function is ready (§5.6).
+ *   refine     a Phase B refinement turn on the same drafts.
+ *   derive     Doc 1 step 4d — reverse-engineering (Doc 1 §5.7): the map derived from Layer 3 configs ({configs}),
+ *              or — scoped — the implementor's "config is right" for selected elements ({elementIds}, §7.4 item 4):
+ *              they are updated from the configs they link to (derive.js). A phase A turn of kind "derive".
+ *   translate  Doc 1 step 4c — a printout's texts translated (§4.8: for the printout only, never written back):
+ *              collected HERE from the map version (mapPrint.collectStrings), translated in chunks (translate.js);
+ *              the same printout (version, scope, language) is answered from the caller's earlier turn.
+ *
  * Administrators only (ruling 2026-10-01): every call spends the company's AI budget.
  */
-import { requirePrincipal } from "../orm/principalGuards.js";
+import { ccGate } from "./ccGate.js";
+import { buildHistory, runInterviewTurn } from "./phaseA.js";
+import { readiness, tenKCompleteness } from "./processMap.js";
+import { runConfigTurn } from "./phaseB.js";
+import { runDeriveTurn } from "./derive.js";
+import { runTranslateTurn } from "./translate.js";
+import { collectStrings } from "./mapPrint.js";
+import { domainOfEntity, layerOf, tryParse } from "./published.js";
+
+const DOMAIN_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,99}$/;
+const MAX_DOMAINS = 5;
+/* Doc 1 step 4d: what one derive turn reads. */
+const MAX_DERIVE_CONFIGS = 10;
+/* Turns that run many rounds (a normal one ends in a few minutes). */
+const LONG_TURNS = ["interview", "generate", "refine", "derive", "translate"];
 
 /* The gateway gives a job 5 minutes before calling it lost; a turn gets a little longer. */
 export const AI_TURN_LOST_AFTER_MS = 6 * 60 * 1000;
+/* An interview turn runs up to 12 rounds of at most 4 minutes each, though a normal one ends in a few minutes. */
+export const INTERVIEW_TURN_LOST_AFTER_MS = 20 * 60 * 1000;
+const MAX_PROMPT = 20000;
+const MAX_SELECTED = 50;
 const MAX_TOKENS_CAP = 32000;
 
 const refuse = (message, code, data) => ({ ok: false, code, problems: [message], ...(data !== undefined ? { data } : {}) });
@@ -136,7 +167,8 @@ const actions = {
 		/* Another user's turn is indistinguishable from no turn. */
 		if (!turn || turn.userId !== userId) return refuse("There is no such AI turn.", "AI_TURN_NOT_FOUND");
 		const startedAt = turn.startedAt ? new Date(turn.startedAt).getTime() : now();
-		if (turn.outcome === "RUNNING" && !turn.toolCalls && now() - startedAt > AI_TURN_LOST_AFTER_MS) {
+		const lostAfter = LONG_TURNS.includes(turn.context?.kind) ? INTERVIEW_TURN_LOST_AFTER_MS : AI_TURN_LOST_AFTER_MS;
+		if (turn.outcome === "RUNNING" && !turn.toolCalls && now() - startedAt > lostAfter) {
 			return done((await repo.failTurn(turn.id, "AI_TURN_LOST")) ?? (await repo.getTurn(turn.id)));
 		}
 		return done(turn);
@@ -144,6 +176,137 @@ const actions = {
 
 	usage: async ({ gateway }) => done(await gateway.usage()),
 
+	interview: async ({ repo, mapRepo, traceRepo, gateway, userId, args, notify, schedule, now, logger }) => {
+		const { sessionId, functionId = null, prompt, selectedIds = [] } = args;
+		if (typeof sessionId !== "string" || !/^[A-Za-z0-9_.:-]{1,100}$/.test(sessionId)) return refuse("sessionId is required (letters, digits, . _ : -, at most 100).", "AI_BAD_REQUEST");
+		if (typeof prompt !== "string" || !prompt.trim() || prompt.length > MAX_PROMPT) return refuse(`Write a message (at most ${MAX_PROMPT} characters).`, "AI_BAD_REQUEST");
+		if (functionId !== null && typeof functionId !== "string") return refuse("functionId is a FUNCTION element id.", "AI_BAD_REQUEST");
+		if (!Array.isArray(selectedIds) || selectedIds.length > MAX_SELECTED || !selectedIds.every((id) => typeof id === "string")) {
+			return refuse(`selectedIds is a list of at most ${MAX_SELECTED} element ids.`, "AI_BAD_REQUEST");
+		}
+		/* Doc 1 §5.3 (ruling 2026-10-03): no function goes to 5,000 ft before the 10,000 ft map is complete —
+		   unless the implementor chooses to go on anyway (override). */
+		if (functionId && args.override !== true) {
+			const { complete, missing, open } = tenKCompleteness(((await mapRepo.latest()) ?? { map: { elements: {} } }).map);
+			if (!complete) {
+				return refuse(
+					`The 10,000 ft map is not complete yet (missing: ${missing.map((m) => m.type).join(", ") || "—"}${open.length ? `; open: ${open.join(", ")}` : ""}). Complete it first, or choose to detail this function anyway.`,
+					"AI_TEN_K_INCOMPLETE",
+					{ missing, open },
+				);
+			}
+		}
+		/* The conversation so far, rebuilt here — never taken from the caller (Doc 1 §2.4: the map is the memory). */
+		const history = buildHistory(await repo.listTurns({ userId, sessionId, limit: 20 }), now());
+		const turn = await repo.insertTurn({ sessionId, phase: "A", functionId, userId, prompt: prompt.trim(), context: { kind: "interview" } });
+
+		schedule(async () => {
+			const outcome = await runInterviewTurn({ turnRepo: repo, mapRepo, traceRepo, gateway, userId, turnId: turn.id, functionId, prompt: prompt.trim(), selectedIds, history, logger });
+			try {
+				await notify(userId, `CC_AI_TURN_${turn.id}`, { turnId: turn.id, outcome });
+			} catch (error) {
+				logger?.error?.(`[ccai] could not tell user ${userId} turn ${turn.id} ended: ${error?.message ?? error}`);
+			}
+		});
+		return done({ turnId: turn.id });
+	},
+
+	translate: async ({ repo, mapRepo, gateway, userId, args, notify, schedule, logger }) => {
+		const { sessionId, version = null, functionIds = [], to } = args;
+		if (typeof sessionId !== "string" || !/^[A-Za-z0-9_.:-]{1,100}$/.test(sessionId)) return refuse("sessionId is required (letters, digits, . _ : -, at most 100).", "AI_BAD_REQUEST");
+		if (!["en", "id"].includes(to)) return refuse('to is "en" (English) or "id" (Indonesian).', "AI_BAD_REQUEST");
+		if (!Array.isArray(functionIds) || functionIds.length > MAX_SELECTED || !functionIds.every((id) => typeof id === "string")) return refuse("functionIds is a list of FUNCTION element ids.", "AI_BAD_REQUEST");
+		const row = version === null ? await mapRepo.latest() : await mapRepo.get(version);
+		if (!row) return refuse(`Map version ${version} does not exist.`, "AI_BAD_REQUEST");
+		const scope = [...new Set(functionIds)].sort();
+		const cacheKey = `${row.version}|${to}|${scope.join(",")}`;
+		/* A map version never changes: the same printout in the same language is translated once. */
+		const cached = await repo.findTranslation?.(cacheKey, userId);
+		if (cached) return done({ turnId: cached, cached: true });
+		const context = { kind: "translate", cacheKey, version: row.version, functionIds: scope, to };
+		const turn = await repo.insertTurn({ sessionId, phase: "A", functionId: null, userId, prompt: `Translate the printout of map version ${row.version} into ${to === "en" ? "English" : "Indonesian"}.`, context });
+		const strings = collectStrings(row.map, scope);
+		schedule(async () => {
+			const outcome = await runTranslateTurn({ turnRepo: repo, gateway, turnId: turn.id, strings, to, context, logger });
+			try {
+				await notify(userId, `CC_AI_TURN_${turn.id}`, { turnId: turn.id, outcome });
+			} catch (error) {
+				logger?.error?.(`[ccai] could not tell user ${userId} turn ${turn.id} ended: ${error?.message ?? error}`);
+			}
+		});
+		return done({ turnId: turn.id, cached: false });
+	},
+
+	generate: (ctx) => configTurn(ctx, "generate"),
+	refine: (ctx) => configTurn(ctx, "refine"),
+
+	derive: async ({ repo, mapRepo, traceRepo, config, gateway, userId, args, notify, schedule, now, logger }) => {
+		const { sessionId, configs = null, elementIds = null, prompt = null } = args;
+		if (typeof sessionId !== "string" || !/^[A-Za-z0-9_.:-]{1,100}$/.test(sessionId)) return refuse("sessionId is required (letters, digits, . _ : -, at most 100).", "AI_BAD_REQUEST");
+		if ((configs === null) === (elementIds === null)) return refuse("Name the configs to derive the map from, or the elements whose configuration is right — one of the two.", "AI_BAD_REQUEST");
+		if (prompt !== null && (typeof prompt !== "string" || prompt.length > MAX_PROMPT)) return refuse(`The message is at most ${MAX_PROMPT} characters.`, "AI_BAD_REQUEST");
+		const latest = (await mapRepo.latest()) ?? { map: { elements: {} } };
+
+		let wanted;
+		if (configs !== null) {
+			const ok = Array.isArray(configs) && configs.length > 0 && configs.length <= MAX_DERIVE_CONFIGS && configs.every((c) => isPlainObject(c) && ["DOMAIN", "WORKFLOW"].includes(c.kind) && typeof c.name === "string" && c.name);
+			if (!ok) return refuse(`configs is a list of 1 to ${MAX_DERIVE_CONFIGS} {kind: DOMAIN | WORKFLOW, name}.`, "AI_BAD_REQUEST");
+			wanted = configs.map(({ kind, name }) => ({ kind, name }));
+		} else {
+			const ok = Array.isArray(elementIds) && elementIds.length > 0 && elementIds.length <= MAX_SELECTED && elementIds.every((id) => typeof id === "string" && latest.map.elements?.[id]);
+			if (!ok) return refuse(`elementIds lists 1 to ${MAX_SELECTED} elements of the map.`, "AI_BAD_REQUEST");
+			/* "Config is right": what the elements link to is what they are updated from. */
+			wanted = [];
+			for (const link of (await Promise.all(elementIds.map((id) => traceRepo.forElement(id)))).flat()) {
+				if (!wanted.some((w) => w.kind === link.configKind && w.name === link.configName)) wanted.push({ kind: link.configKind, name: link.configName });
+			}
+			if (!wanted.length) return refuse("No configuration implements these elements yet — there is nothing to update them from.", "AI_NOTHING_LINKED");
+		}
+		const { problems, configs: read } = await deriveConfigs(wanted, config);
+		if (problems.length) return refuse(problems.join(" "), "AI_CONFIG_NOT_DERIVABLE", { problems });
+
+		const scoped = elementIds !== null;
+		const said =
+			prompt?.trim() ||
+			(scoped
+				? `The configuration is right for ${elementIds.map((id) => `"${latest.map.elements[id].name}" (${id})`).join(", ")}: update ${elementIds.length === 1 ? "it" : "them"} from it.`
+				: `Derive the map from ${wanted.map((c) => `${c.kind} ${c.name}`).join(", ")}.`);
+		const history = buildHistory(await repo.listTurns({ userId, sessionId, limit: 20 }), now());
+		const turn = await repo.insertTurn({ sessionId, phase: "A", functionId: null, userId, prompt: said, context: { kind: "derive" } });
+		schedule(async () => {
+			const outcome = await runDeriveTurn({ turnRepo: repo, mapRepo, traceRepo, gateway, userId, turnId: turn.id, configs: read, selectedIds: elementIds ?? [], scoped, prompt: said, history, logger });
+			try {
+				await notify(userId, `CC_AI_TURN_${turn.id}`, { turnId: turn.id, outcome });
+			} catch (error) {
+				logger?.error?.(`[ccai] could not tell user ${userId} turn ${turn.id} ended: ${error?.message ?? error}`);
+			}
+		});
+		return done({ turnId: turn.id });
+	},
+
+	session: async ({ repo, userId, args }) => {
+		const turns = await repo.listTurns({ userId, sessionId: String(args.sessionId ?? ""), limit: 50 });
+		return done(
+			[...turns].reverse().map((t) => ({
+				id: t.id,
+				prompt: t.prompt,
+				modelText: t.modelText,
+				outcome: t.outcome,
+				error: t.error ?? null,
+				costUsd: t.costUsd ?? null,
+				startedAt: t.startedAt ?? null,
+				finishedAt: t.finishedAt ?? null,
+				mapVersion: t.context?.result?.mapVersion ?? null,
+				changed: t.context?.result?.changed ?? null,
+				/* Doc 1 step 3 — a Phase B turn's function summary (§6.3 item 4). */
+				kind: t.context?.kind ?? null,
+				drafts: t.context?.result?.drafts ?? null,
+				gaps: t.context?.result?.gaps ?? null,
+				unimplemented: t.context?.result?.unimplemented ?? null,
+			})),
+		);
+	},
+
 	settle: async ({ repo, userId, args }) => {
 		const settled = await repo.settleTurn(Number(args.turnId), userId, args.outcome);
 		return settled ? done(settled) : refuse("Only your own turn that is waiting on its tool calls can be settled.", "AI_TURN_NOT_SETTLEABLE");
@@ -152,16 +315,80 @@ const actions = {
 
 export const AI_ACTIONS = Object.freeze(Object.keys(actions));
 
-export const runAiAction = async ({ repo, gateway, principal, isPostgres, action, args = {}, notify, schedule = (fn) => setImmediate(fn), now = Date.now, logger }) => {
-	if (!isPostgres) {
-		throw new Error("Control Center AI needs a PostgreSQL tenant; this database index is not one.");
+/* A workflow is Layer 3 when the domain it belongs to is: its own `domain` key, else the published domain of its
+   entity (published.js domainOfEntity — the draft store's rule). */
+const workflowLayer = async (content, { readConfig, draftRepo }) => {
+	if (content?.domain) return layerOf((await readConfig("DOMAIN", content.domain)).content);
+	const published = ((await draftRepo?.publishedDomains?.()) ?? []).map((r) => ({ name: r.name, content: tryParse("DOMAIN", r.text) })).filter((d) => d.content);
+	const owner = domainOfEntity(content?.entityType, published);
+	return owner ? layerOf(owner.content) : null;
+};
+
+/* Doc 1 step 4d — what a derive turn reads: each config as it is now (the OPEN draft, else what is published),
+   checked Layer 3 HERE — never trusted to the picker — and the application config, for its menus. */
+const deriveConfigs = async (wanted, config) => {
+	const problems = [];
+	const read = [];
+	for (const { kind, name } of wanted) {
+		const { content } = await config.readConfig(kind, name);
+		if (!content) {
+			problems.push(`${kind} ${name} is neither an open draft nor published.`);
+			continue;
+		}
+		if (kind !== "APPLICATION") {
+			const layer = kind === "DOMAIN" ? layerOf(content) : await workflowLayer(content, config);
+			if (layer !== "3") {
+				problems.push(`${kind} ${name} is not Layer 3 configuration (layer ${layer ?? "unknown"}): only Layer 3 is derived into the map.`);
+				continue;
+			}
+		}
+		read.push({ kind, name, content });
 	}
-	const userId = requirePrincipal(principal, "Control Center AI requires a verified principal. Sign in again.");
-	/* ⚠️ Authority first, before anything is read or spent. */
-	if (!(await repo.isAdministrator(userId))) {
-		throw new Error(`user ${userId} is not an administrator; only administrators may use Control Center AI.`);
+	if (!read.some((c) => c.kind === "APPLICATION")) {
+		const app = (await config.readConfig("APPLICATION", "APPLICATION_CONFIG")).content;
+		if (app) read.push({ kind: "APPLICATION", name: "APPLICATION_CONFIG", content: app });
+	}
+	return { problems, configs: read };
+};
+
+/* Doc 1 step 3 — a Phase B turn (generate / refine). */
+async function configTurn({ repo, mapRepo, config, gateway, userId, args, notify, schedule, logger }, mode) {
+	const { sessionId, functionId, domains, prompt = null } = args;
+	if (typeof sessionId !== "string" || !/^[A-Za-z0-9_.:-]{1,100}$/.test(sessionId)) return refuse("sessionId is required (letters, digits, . _ : -, at most 100).", "AI_BAD_REQUEST");
+	if (!Array.isArray(domains) || domains.length === 0 || domains.length > MAX_DOMAINS || !domains.every((d) => typeof d === "string" && DOMAIN_NAME.test(d))) {
+		return refuse(`Name 1 to ${MAX_DOMAINS} Layer 3 domains to write (letters, digits, _ and -).`, "AI_BAD_REQUEST");
 	}
+	if (mode === "refine" && (typeof prompt !== "string" || !prompt.trim() || prompt.length > MAX_PROMPT)) return refuse("Write what to change.", "AI_BAD_REQUEST");
+	const latest = (await mapRepo.latest()) ?? { map: { elements: {} } };
+	if (latest.map.elements?.[functionId]?.type !== "FUNCTION") return refuse(`${JSON.stringify(functionId)} is not a function of the map.`, "AI_BAD_REQUEST");
+	if (mode === "generate") {
+		/* Doc 1 §5.6: readiness is a hard gate — no override. */
+		const ready = readiness(latest.map, functionId);
+		if (!ready.ready) return refuse("The function is not ready for build yet.", "AI_NOT_READY", { blocking: ready.blocking });
+	}
+	/* A domain that is published must be editable here (Layer 3, owned by Control Center). */
+	for (const name of domains) {
+		if (!(await config.draftRepo.publishedDomain(name))) continue;
+		const opened = await config.openDraft("DOMAIN", name);
+		if (!opened?.ok) return refuse(`Domain ${name}: ${(opened?.problems ?? ["it cannot be edited in Control Center."]).join(" ")}`, "AI_DOMAIN_NOT_WRITABLE");
+	}
+	const history = mode === "refine" ? buildHistory(await repo.listTurns({ userId, sessionId, limit: 20 })) : [];
+	const turn = await repo.insertTurn({ sessionId, phase: "B", functionId, userId, prompt: prompt?.trim() ?? `generate ${functionId}`, context: { kind: mode } });
+	schedule(async () => {
+		const outcome = await runConfigTurn({ turnRepo: repo, mapRepo, ...config, gateway, userId, turnId: turn.id, functionId, domains, mode, prompt: prompt?.trim() ?? null, history, logger });
+		try {
+			await notify(userId, `CC_AI_TURN_${turn.id}`, { turnId: turn.id, outcome });
+		} catch (error) {
+			logger?.error?.(`[ccai] could not tell user ${userId} turn ${turn.id} ended: ${error?.message ?? error}`);
+		}
+	});
+	return done({ turnId: turn.id });
+}
+
+export const runAiAction = async ({ repo, mapRepo, traceRepo, config, gateway, principal, isPostgres, action, args = {}, notify, schedule = (fn) => setImmediate(fn), now = Date.now, logger }) => {
+	/* ⚠️ Authority first, before anything is read or spent. */
+	const userId = await ccGate({ repo, principal, isPostgres, feature: "Control Center AI" });
 	const handler = actions[action];
 	if (!handler) throw new Error(`Unknown ccai action "${action}". Use one of ${AI_ACTIONS.join(", ")}.`);
-	return handler({ repo, gateway, userId, args: args ?? {}, notify, schedule, now, logger });
+	return handler({ repo, mapRepo, traceRepo, config, gateway, userId, args: args ?? {}, notify, schedule, now, logger });
 };

package/engine/cc/appMenus.d.ts

@@ -21,5 +21,7 @@ export function linkFor(type: ScreenType, entryPoint: string): (string | null)[]
 export function resolveDomainKey(ref: unknown, domains: Record<string, { source?: string; alias?: string }> | undefined): string | null;
 export function menuProblems(app: Record<string, any>, index: DomainIndex): MenuProblem[];
 export function menuUsages(app: Record<string, any>, index: DomainIndex): Record<string, number>;
+export function menuKeyOf(node: unknown): string;
+export function findMenuNode(menus: unknown, key: string): { node: Record<string, any>; path: string; domain: string | null } | null;
 export function entryPointsOf(domainContent: unknown): Record<string, ScreenType>;
 export function domainIndexOf(domains: Record<string, any> | undefined, contentOf: (name: string) => unknown): DomainIndex;

package/engine/cc/appMenus.js

@@ -117,6 +117,20 @@ export function menuProblems(app, index) {
 	return problems;
 }
 
+/* Doc 1 step 3 — a menu node's key (Doc 7 §4.4, Supertail's defaultMenuKey): its `menuKey`, else its caption
+   upper-cased with `_` for spaces. */
+export const menuKeyOf = (node) => node?.menuKey ?? String(node?.caption ?? "").trim().toUpperCase().replace(/\s+/g, "_");
+
+/* Doc 1 step 4 — the node a key names (a trace link's `menu:<KEY>`), with its pointer and the domain it
+   inherits; null when no node has that key. */
+export function findMenuNode(menus, key) {
+	let found = null;
+	walk(menus, (node, path, domain) => {
+		if (!found && menuKeyOf(node) === key) found = { node, path, domain: domain ?? null };
+	});
+	return found;
+}
+
 /* How many menus use each domain and each domain's entry point (keys "domain" and "domain/entryPoint"). */
 export function menuUsages(app, index) {
 	const out = {};

package/engine/cc/ccGate.js

@@ -0,0 +1,15 @@
+/*
+ * The one door every Control Center command goes through (ccdraft, ccai, ccmap): a PostgreSQL tenant, a
+ * VERIFIED principal (never an id from the request), and an administrator — checked before anything is
+ * read, so a refusal reveals nothing. These are refusals of the caller itself, so they are thrown.
+ */
+import { requirePrincipal } from "../orm/principalGuards.js";
+
+export const ccGate = async ({ repo, principal, isPostgres, feature }) => {
+	if (!isPostgres) throw new Error(`${feature} needs a PostgreSQL tenant; this database index is not one.`);
+	const userId = requirePrincipal(principal, `${feature} requires a verified principal. Sign in again.`);
+	if (!(await repo.isAdministrator(userId))) {
+		throw new Error(`user ${userId} is not an administrator; only administrators may use ${feature}.`);
+	}
+	return userId;
+};