feat(runtime): add governance-aware runtime bundle preparation

packages/interfacectl-cli/dist/adapter/bundle.d.ts

@@ -26,6 +26,7 @@ export interface LoadedCompiledSurfaceBundle {
         components: LoadedJsonFile;
         constraints: LoadedJsonFile;
         repairMap: LoadedJsonFile;
+        runtime?: LoadedJsonFile;
         authoring?: LoadedJsonFile;
     };
 }

packages/interfacectl-cli/dist/adapter/bundle.js

@@ -116,6 +116,17 @@ export function loadCompiledSurfaceBundle(bundleRootInput, surfaceId, cwd) {
             value: readJsonFile(authoringPath, "Authoring bundle"),
         };
     }
+    let runtime;
+    const runtimeRef = typeof refs.runtime === "string" && refs.runtime.trim().length > 0
+        ? refs.runtime
+        : "./runtime.json";
+    const runtimePath = path.resolve(path.dirname(generationPath), runtimeRef);
+    if (fs.existsSync(runtimePath) && fs.statSync(runtimePath).isFile()) {
+        runtime = {
+            path: runtimePath,
+            value: readJsonFile(runtimePath, "Runtime bundle"),
+        };
+    }
     const generationProvenance = isRecord(generation.value.provenance)
         ? generation.value.provenance
         : undefined;
@@ -147,6 +158,7 @@ export function loadCompiledSurfaceBundle(bundleRootInput, surfaceId, cwd) {
             components,
             constraints,
             repairMap,
+            ...(runtime ? { runtime } : {}),
             ...(authoring ? { authoring } : {}),
         },
     };

packages/interfacectl-cli/dist/commands/compile.js

@@ -53,6 +53,119 @@ function uniqueStrings(values) {
     }
     return result;
 }
+function getPolicyRank(policy) {
+    switch (policy) {
+        case "strict":
+            return 2;
+        case "warn":
+            return 1;
+        case "off":
+        default:
+            return 0;
+    }
+}
+function maxPolicy(...policies) {
+    let strongest = "off";
+    for (const policy of policies) {
+        if (getPolicyRank(policy) > getPolicyRank(strongest)) {
+            strongest = policy ?? "off";
+        }
+    }
+    return strongest;
+}
+function buildGovernancePayload(surface) {
+    return {
+        owner: surface.owner ?? null,
+        domain: surface.domain ?? null,
+        phase0: surface.phase0 ?? null,
+        status: surface.governance?.status ?? "draft",
+        roles: surface.governance?.roles ?? {},
+        approvals: surface.governance?.approvals ?? [],
+    };
+}
+function inferMutationMode(surface, sections) {
+    const explicitMode = surface.runtime?.mutationEnvelope?.mode;
+    if (explicitMode)
+        return explicitMode;
+    const sectionModes = uniqueStrings(sections.map((section) => section.editPolicy?.mode));
+    const allowedOperations = uniqueStrings(sections.flatMap((section) => section.editPolicy?.allowedOperations ?? []));
+    if (sectionModes.length > 0 && sectionModes.every((mode) => mode === "locked")) {
+        return "locked";
+    }
+    if (sectionModes.includes("freeform")) {
+        return "freeform";
+    }
+    if (allowedOperations.includes("adjust-layout")) {
+        return "layout-tuning";
+    }
+    if (sectionModes.includes("slot-bound")) {
+        return "slot-bound";
+    }
+    return "content-only";
+}
+function inferMutationScopes(actions) {
+    return uniqueStrings(actions.flatMap((action) => {
+        switch (action) {
+            case "update-copy":
+            case "change-media":
+            case "bind-data":
+                return ["content"];
+            case "swap-variant":
+            case "swap-component":
+                return ["components"];
+            case "adjust-layout":
+                return ["layout"];
+            case "add-section":
+            case "remove-section":
+            case "reorder-sections":
+                return ["sections"];
+            case "wire-interaction":
+                return ["interactions"];
+            case "reorder-items":
+                return ["content", "layout"];
+            default:
+                return [];
+        }
+    }));
+}
+function buildMutationEnvelope(surface, sections) {
+    const explicit = surface.runtime?.mutationEnvelope;
+    const inferredActions = uniqueStrings(sections.flatMap((section) => section.editPolicy?.allowedOperations ?? []));
+    const allowedActions = uniqueStrings([
+        ...(explicit?.allowedActions ?? []),
+        ...(explicit?.allowedActions ? [] : inferredActions),
+        inferredActions.length === 0 ? "update-copy" : undefined,
+    ]);
+    const scopes = uniqueStrings([
+        ...(explicit?.scopes ?? []),
+        ...(explicit?.scopes ? [] : inferMutationScopes(allowedActions)),
+    ]);
+    return {
+        mode: inferMutationMode(surface, sections),
+        ...(scopes.length > 0 ? { scopes } : {}),
+        ...(allowedActions.length > 0 ? { allowedActions } : {}),
+        ...(explicit?.allowedSections ? { allowedSections: explicit.allowedSections } : {}),
+        ...(explicit?.prohibitedSections ? { prohibitedSections: explicit.prohibitedSections } : {}),
+    };
+}
+function buildPolicySeverities(contract, surface) {
+    const boundary = surface.mustNotEmit?.length || contract.shell?.owns?.length
+        ? "strict"
+        : "off";
+    const structure = maxPolicy(surface.requiredSections.length > 0 ? "strict" : "off", surface.layout.landingPattern?.policy);
+    const layout = maxPolicy(surface.layout.pageFrame?.enforcement, surface.layout.chromePolicy?.policy, surface.layout.landingPattern?.policy, surface.layout.landingPattern?.marketingLayoutPolicy);
+    const visual = maxPolicy(contract.color.policy, surface.icons?.policy, contract.tokens?.typography?.policy, contract.tokens?.motion?.policy, surface.marketingTypographyPolicy);
+    const interaction = surface.flows?.policy ?? "off";
+    const runtime = maxPolicy(surface.runtime?.policy, boundary, structure, layout, visual, interaction);
+    return {
+        boundary,
+        structure,
+        layout,
+        visual,
+        interaction,
+        runtime,
+    };
+}
 function collectComponentIdsFromSlots(slots) {
     if (!slots)
         return [];
@@ -262,6 +375,12 @@ function buildGenerationPayload(contract, surface, sections) {
     const requiredSections = surface.requiredSections;
     const landingPattern = surface.layout.landingPattern;
     const observationRefs = buildObservationRefs(contract);
+    const governance = buildGovernancePayload(surface);
+    const adaptation = {
+        policy: surface.runtime?.policy ?? buildPolicySeverities(contract, surface).runtime,
+        mutationEnvelope: buildMutationEnvelope(surface, sections),
+        contextIds: (surface.runtime?.contexts ?? []).map((context) => context.id),
+    };
     return {
         identity: {
             surfaceId: surface.id,
@@ -318,6 +437,8 @@ function buildGenerationPayload(contract, surface, sections) {
                 tokenPolicyCategories: Object.keys(contract.tokens ?? {}),
             },
         },
+        governance,
+        adaptation,
         guidance: buildGuidance(contract, surface, sections),
         refs: {
             contract: "../../contract/normalized.json",
@@ -326,6 +447,7 @@ function buildGenerationPayload(contract, surface, sections) {
             constraints: "./constraints.json",
             ...(surface.authoring ? { authoring: "./authoring.json" } : {}),
             repairMap: "./repair-map.json",
+            runtime: "./runtime.json",
             ...(observationRefs.length > 0 ? { evidence: observationRefs } : {}),
         },
     };
@@ -485,6 +607,59 @@ function buildRepairMapPayload(contract, surface, sections) {
         repairs,
     };
 }
+function buildRuntimePayload(contract, surface, sections, components) {
+    const policySeverities = buildPolicySeverities(contract, surface);
+    const mutationEnvelope = buildMutationEnvelope(surface, sections);
+    return {
+        provenance: makeBundleProvenance(contract, surface.id),
+        identity: {
+            surfaceId: surface.id,
+            displayName: surface.displayName,
+            type: surface.type,
+        },
+        governance: buildGovernancePayload(surface),
+        runtime: {
+            policy: surface.runtime?.policy ?? policySeverities.runtime,
+            policySeverities,
+            mutationEnvelope,
+            contexts: surface.runtime?.contexts ?? [],
+            boundary: {
+                shellOwns: contract.shell?.owns ?? [],
+                contentSlot: contract.shell?.contentSlot ?? null,
+                mustNotEmit: surface.mustNotEmit ?? [],
+                allowSources: surface.shellOwnedPrimitiveAllowSources ?? [],
+            },
+            structure: {
+                requiredSections: surface.requiredSections,
+                allowedSections: sections.map((section) => section.id),
+                allowedComponents: components.map((component) => component.id),
+            },
+            layout: {
+                maxContentWidth: surface.layout.maxContentWidth,
+                requiredContainers: surface.layout.requiredContainers ?? [],
+                ...(surface.layout.pageFrame ? { pageFrame: surface.layout.pageFrame } : {}),
+                ...(surface.layout.chromePolicy ? { chromePolicy: surface.layout.chromePolicy } : {}),
+                ...(surface.layout.landingPattern ? { landingPattern: surface.layout.landingPattern } : {}),
+                ...(surface.viewports ? { viewports: surface.viewports } : {}),
+            },
+            visual: {
+                allowedFonts: surface.allowedFonts,
+                color: contract.color,
+                motion: contract.constraints.motion,
+                ...(contract.tokens ? { tokens: contract.tokens } : {}),
+                ...(surface.icons ? { icons: surface.icons } : {}),
+            },
+            ...(surface.flows ? { interaction: { flows: surface.flows } } : {}),
+        },
+        refs: {
+            contract: "../../contract/normalized.json",
+            sections: "./sections.json",
+            components: "./components.json",
+            constraints: "./constraints.json",
+            repairMap: "./repair-map.json",
+        },
+    };
+}
 function buildSurfaceBundleFiles(contract, surface) {
     const surfaceDir = `surfaces/${surface.id}`;
     const sections = resolveSurfaceSections(contract, surface);
@@ -495,6 +670,7 @@ function buildSurfaceBundleFiles(contract, surface) {
     const componentsPayload = buildComponentsPayload(contract, surface, components);
     const repairMapPayload = buildRepairMapPayload(contract, surface, sections);
     const authoringPayload = buildAuthoringPayload(contract, surface);
+    const runtimePayload = buildRuntimePayload(contract, surface, sections, components);
     const files = [
         {
             path: `${surfaceDir}/generation.json`,
@@ -516,6 +692,10 @@ function buildSurfaceBundleFiles(contract, surface) {
             path: `${surfaceDir}/repair-map.json`,
             content: stringifyDeterministic(repairMapPayload),
         },
+        {
+            path: `${surfaceDir}/runtime.json`,
+            content: stringifyDeterministic(runtimePayload),
+        },
     ];
     if (authoringPayload) {
         files.push({

packages/interfacectl-cli/dist/commands/prepare-generation.d.ts

@@ -14,6 +14,7 @@ interface SummaryRepairItem {
 export declare function buildPreparedGenerationPayload(bundle: LoadedCompiledSurfaceBundle): {
     evidenceRefs: any[];
     authoring?: JsonRecord | undefined;
+    runtime?: JsonRecord | undefined;
     surface: {
         surfaceId: string;
         displayName: string;
@@ -25,6 +26,7 @@ export declare function buildPreparedGenerationPayload(bundle: LoadedCompiledSur
         manifestPath: string;
         sourcePaths: {
             authoring?: string | undefined;
+            runtime?: string | undefined;
             contract: string;
             generation: string;
             sections: string;
@@ -55,6 +57,8 @@ export declare function buildPreparedGenerationPayload(bundle: LoadedCompiledSur
         structure: JsonRecord;
         layout: JsonRecord;
         visual: JsonRecord;
+        governance: JsonRecord;
+        adaptation: JsonRecord;
         guidance: JsonRecord;
     };
     sections: any[];
@@ -65,6 +69,7 @@ export declare function buildPreparedGenerationPayload(bundle: LoadedCompiledSur
 export declare function loadPreparedGenerationPayload(bundleRoot: string, surfaceId: string, cwd?: string): {
     evidenceRefs: any[];
     authoring?: JsonRecord | undefined;
+    runtime?: JsonRecord | undefined;
     surface: {
         surfaceId: string;
         displayName: string;
@@ -76,6 +81,7 @@ export declare function loadPreparedGenerationPayload(bundleRoot: string, surfac
         manifestPath: string;
         sourcePaths: {
             authoring?: string | undefined;
+            runtime?: string | undefined;
             contract: string;
             generation: string;
             sections: string;
@@ -106,6 +112,8 @@ export declare function loadPreparedGenerationPayload(bundleRoot: string, surfac
         structure: JsonRecord;
         layout: JsonRecord;
         visual: JsonRecord;
+        governance: JsonRecord;
+        adaptation: JsonRecord;
         guidance: JsonRecord;
     };
     sections: any[];