@duckcodeailabs/dql-cli 1.13.1 → 1.13.2

package/dist/apps-api.js

@@ -6,7 +6,7 @@
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join, dirname, relative, basename } from 'node:path';
-import { loadAppDocument, findAppDocuments, loadDashboardDocument, findDashboardsForApp, parseAppDocument, parseDashboardDocument, normalizeDqlArtifactReference, suggestAppId, } from '@duckcodeailabs/dql-core';
+import { loadAppDocument, findAppDocuments, loadDashboardDocument, findDashboardsForApp, parseAppDocument, parseDashboardDocument, normalizeDqlArtifactReference, suggestAppId, createAppBuildDraft, applyAppBuildDraftOperations, } from '@duckcodeailabs/dql-core';
 import { defaultPersonaRegistry, defaultLocalAppsDbPath, LocalAppStorage, personaFromMember, } from '@duckcodeailabs/dql-project';
 export async function handleAppsApi(ctx) {
     const { req, res, path, projectRoot } = ctx;
@@ -26,6 +26,188 @@ export async function handleAppsApi(ctx) {
         return true;
     }
     // ── Apps ────────────────────────────────────────────────────────────────
+    if (req.method === 'POST' && path === '/api/app-builds') {
+        try {
+            const body = await readJson(req);
+            const draft = createStoredAppBuildDraft(projectRoot, body);
+            sendJson(res, 201, { ok: true, draft });
+        }
+        catch (err) {
+            sendJson(res, 400, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return true;
+    }
+    if (req.method === 'GET' && path === '/api/app-builds') {
+        const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+        try {
+            sendJson(res, 200, { ok: true, drafts: storage.listAppBuildDrafts() });
+        }
+        finally {
+            storage.close();
+        }
+        return true;
+    }
+    let buildMatch = path.match(/^\/api\/app-builds\/([^/]+)$/);
+    if (buildMatch && req.method === 'GET') {
+        const draft = loadStoredAppBuildDraft(projectRoot, decodeURIComponent(buildMatch[1]));
+        sendJson(res, draft ? 200 : 404, draft ? { ok: true, draft } : { ok: false, error: 'App Build Draft not found.' });
+        return true;
+    }
+    if (buildMatch && req.method === 'PATCH') {
+        try {
+            const id = decodeURIComponent(buildMatch[1]);
+            const current = loadStoredAppBuildDraft(projectRoot, id);
+            if (!current) {
+                sendJson(res, 404, { ok: false, error: 'App Build Draft not found.' });
+                return true;
+            }
+            const body = await readJson(req);
+            if (body.expectedProposalHash && body.expectedProposalHash !== current.proposalHash) {
+                sendJson(res, 409, { ok: false, error: 'APP_BUILD_PROPOSAL_CONFLICT: refresh the local draft before applying changes.' });
+                return true;
+            }
+            const next = applyAppBuildDraftOperations(current, body.expectedRevision ?? -1, body.operations ?? []);
+            writeStoredAppBuildDraft(projectRoot, next, {
+                expectedRevision: current.revision,
+                operations: body.operations ?? [],
+            });
+            sendJson(res, 200, { ok: true, draft: next });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            sendJson(res, message.includes('APP_BUILD_REVISION_CONFLICT') ? 409 : 400, { ok: false, error: message });
+        }
+        return true;
+    }
+    if (buildMatch && req.method === 'DELETE') {
+        try {
+            const id = decodeURIComponent(buildMatch[1]);
+            const current = loadStoredAppBuildDraft(projectRoot, id);
+            if (!current) {
+                sendJson(res, 404, { ok: false, error: 'App Build Draft not found.' });
+                return true;
+            }
+            const body = await readJson(req);
+            if (body.expectedRevision !== current.revision || body.proposalHash !== current.proposalHash) {
+                sendJson(res, 409, { ok: false, error: 'APP_BUILD_REVISION_CONFLICT: refresh before deleting this local draft.' });
+                return true;
+            }
+            sendJson(res, 200, deleteStoredAppBuildDraft(projectRoot, current));
+        }
+        catch (err) {
+            sendJson(res, 400, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return true;
+    }
+    const askResultMatch = path.match(/^\/api\/app-builds\/([^/]+)\/ask-results$/);
+    if (askResultMatch && req.method === 'POST') {
+        try {
+            const id = decodeURIComponent(askResultMatch[1]);
+            const body = await readJson(req);
+            const result = addAskResultToAppBuildDraft(projectRoot, id, body);
+            sendJson(res, result.deduped ? 200 : 201, result);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            sendJson(res, message.includes('APP_BUILD_') ? 409 : 400, { ok: false, error: message });
+        }
+        return true;
+    }
+    const draftAiProposalMatch = path.match(/^\/api\/app-builds\/([^/]+)\/ai-proposals$/);
+    if (draftAiProposalMatch && req.method === 'POST') {
+        try {
+            const id = decodeURIComponent(draftAiProposalMatch[1]);
+            const current = loadStoredAppBuildDraft(projectRoot, id);
+            if (!current) {
+                sendJson(res, 404, { ok: false, error: 'App Build Draft not found.' });
+                return true;
+            }
+            const body = await readJson(req);
+            if (body.expectedRevision !== current.revision || body.proposalHash !== current.proposalHash) {
+                sendJson(res, 409, { ok: false, error: 'APP_BUILD_REVISION_CONFLICT: refresh before asking AI to change this draft.' });
+                return true;
+            }
+            const proposal = await proposeAppBuildDraftOperations(projectRoot, current, {
+                prompt: cleanString(body.prompt) || current.frame.goal,
+                selectedBlockIds: body.selectedBlockIds,
+            }, { generateGovernedAnswer: ctx.generateGovernedAnswer });
+            sendJson(res, 201, { ok: true, proposal });
+        }
+        catch (err) {
+            sendJson(res, 400, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return true;
+    }
+    buildMatch = path.match(/^\/api\/app-builds\/([^/]+)\/preflight$/);
+    if (buildMatch && req.method === 'POST') {
+        const current = loadStoredAppBuildDraft(projectRoot, decodeURIComponent(buildMatch[1]));
+        if (!current) {
+            sendJson(res, 404, { ok: false, error: 'App Build Draft not found.' });
+            return true;
+        }
+        const body = await readJson(req);
+        if ((body.expectedRevision !== undefined && body.expectedRevision !== current.revision)
+            || (body.proposalHash && body.proposalHash !== current.proposalHash)) {
+            sendJson(res, 409, { ok: false, error: 'APP_BUILD_REVISION_CONFLICT: refresh before preflight.' });
+            return true;
+        }
+        const errors = preflightAppBuildRequestErrors(projectRoot, current, ctx.verifyAppBuildPreview);
+        if (errors.length) {
+            sendJson(res, 400, {
+                ok: false,
+                code: 'APP_BUILD_NOT_READY',
+                message: 'This App is not ready to publish yet.',
+                draft: current,
+                errors,
+                details: { draft: current, errors },
+            });
+            return true;
+        }
+        const next = markStoredAppBuildDraftPreflighted(projectRoot, current);
+        sendJson(res, 200, { ok: true, draft: next, errors: [] });
+        return true;
+    }
+    buildMatch = path.match(/^\/api\/app-builds\/([^/]+)\/(publish-to-project|commit)$/);
+    if (buildMatch && req.method === 'POST') {
+        try {
+            const current = loadStoredAppBuildDraft(projectRoot, decodeURIComponent(buildMatch[1]));
+            if (!current) {
+                sendJson(res, 404, { ok: false, error: 'App Build Draft not found.' });
+                return true;
+            }
+            const body = await readJson(req);
+            if (body.expectedRevision !== current.revision || body.proposalHash !== current.proposalHash) {
+                sendJson(res, 409, { ok: false, error: 'APP_BUILD_REVISION_CONFLICT: refresh the Build Frame before committing.' });
+                return true;
+            }
+            const errors = preflightAppBuildRequestErrors(projectRoot, current, ctx.verifyAppBuildPreview);
+            if (errors.length) {
+                sendJson(res, 400, {
+                    ok: false,
+                    code: 'APP_BUILD_NOT_READY',
+                    message: 'This App is not ready to publish yet.',
+                    draft: current,
+                    errors,
+                    details: { draft: current, errors },
+                });
+                return true;
+            }
+            // The final confirmation consumes the exact receipt the user reviewed.
+            // Compatibility callers that arrive without one are preflighted once in
+            // this same request so they cannot enter a client-side recheck loop.
+            const prepared = hasCurrentAppBuildPreflightReceipt(current)
+                ? current
+                : markStoredAppBuildDraftPreflighted(projectRoot, current);
+            const result = publishStoredAppBuildDraft(projectRoot, prepared);
+            await refreshGeneratedMetadata(projectRoot);
+            sendJson(res, 201, { ...result, compatibilityRoute: buildMatch[2] === 'commit' });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            sendJson(res, message.includes('already exists') ? 409 : 400, { ok: false, error: message });
+        }
+        return true;
+    }
     if (req.method === 'GET' && path === '/api/apps') {
         const apps = collectAppsList(projectRoot);
         sendJson(res, 200, { apps });
@@ -156,7 +338,9 @@ export async function handleAppsApi(ctx) {
     if (req.method === 'POST' && path === '/api/apps') {
         try {
             const body = await readJson(req);
-            const result = createAppPackage(projectRoot, body);
+            // Compatibility adapter: the legacy manual endpoint now traverses the
+            // same versioned draft, preflight, and private commit service as Studio.
+            const result = createAppPackageViaBuildDraft(projectRoot, body);
             if (!result.ok) {
                 sendJson(res, 400, { error: result.error });
                 return true;
@@ -204,6 +388,24 @@ export async function handleAppsApi(ctx) {
         }
         return true;
     }
+    m = path.match(/^\/api\/apps\/([^/]+)\/publish-to-project$/);
+    if (m && req.method === 'POST') {
+        const appId = decodeURIComponent(m[1]);
+        try {
+            const body = await readJson(req);
+            const result = promoteAppForStakeholders(projectRoot, appId, body);
+            if (!result.ok) {
+                sendJson(res, 409, result);
+                return true;
+            }
+            await refreshGeneratedMetadata(projectRoot);
+            sendJson(res, 200, result);
+        }
+        catch (err) {
+            sendJson(res, 500, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return true;
+    }
     m = path.match(/^\/api\/apps\/([^/]+)\/dashboards\/([^/]+)\/approve-semantic$/);
     if (m && req.method === 'POST') {
         const appId = decodeURIComponent(m[1]);
@@ -714,7 +916,8 @@ export async function handleAppsApi(ctx) {
     if (m && req.method === 'DELETE') {
         const id = decodeURIComponent(m[1]);
         try {
-            const result = deleteAppPackage(projectRoot, id);
+            const body = await readJson(req);
+            const result = deleteAppPackage(projectRoot, id, body);
             if (!result.ok) {
                 sendJson(res, result.status, { ok: false, error: result.error });
                 return true;
@@ -727,6 +930,39 @@ export async function handleAppsApi(ctx) {
         }
         return true;
     }
+    m = path.match(/^\/api\/app-recoveries\/([^/]+)\/restore$/);
+    if (m && req.method === 'POST') {
+        try {
+            const result = restoreAppRecovery(projectRoot, decodeURIComponent(m[1]));
+            if (!result.ok) {
+                sendJson(res, result.status, result);
+                return true;
+            }
+            ctx.scheduleProjectRefresh?.('app-restored');
+            sendJson(res, 200, result);
+        }
+        catch (err) {
+            sendJson(res, 500, { ok: false, error: err.message });
+        }
+        return true;
+    }
+    if (m && req.method === 'PATCH') {
+        const id = decodeURIComponent(m[1]);
+        try {
+            const body = await readJson(req);
+            const result = renameApp(projectRoot, id, body);
+            if (!result.ok) {
+                sendJson(res, result.code === 'APP_NOT_FOUND' ? 404 : result.code === 'APP_CHANGED' ? 409 : 400, result);
+                return true;
+            }
+            ctx.scheduleProjectRefresh?.('app-renamed');
+            sendJson(res, 200, result);
+        }
+        catch (err) {
+            sendJson(res, 500, { ok: false, error: err.message });
+        }
+        return true;
+    }
     if (m && req.method === 'GET') {
         const id = m[1];
         const result = loadAppById(projectRoot, id);
@@ -830,6 +1066,7 @@ function collectAppsList(projectRoot) {
         out.push({
             id: document.id,
             name: document.name,
+            fingerprint: fingerprintAppDirectory(appDir),
             filePath: relative(projectRoot, appDir),
             domain: document.domain,
             ownerDomain: document.ownerDomain,
@@ -1242,13 +1479,51 @@ function buildAppProposal(plan) {
         seenGap.add(question.toLowerCase());
         gaps.push({ id: `gap_${gaps.length + 1}`, question, reason: 'No certified block covers this question.' });
     }
+    const metrics = Array.from(new Set(plan.requirements.flatMap((requirement) => requirement.measures)));
+    const dimensions = Array.from(new Set(plan.requirements.flatMap((requirement) => requirement.dimensions)));
+    const filters = Array.from(new Set(plan.requirements.flatMap((requirement) => requirement.filters)));
+    const clarifications = [];
+    if (metrics.length === 0) {
+        clarifications.push({
+            id: 'metric',
+            question: 'Which governed business metric should lead this App?',
+            choices: ['Choose a certified block', 'Choose a semantic metric', 'Describe the calculation as review-required analysis'],
+            required: true,
+        });
+    }
+    if (tiles.length === 0 || gaps.length > 0) {
+        clarifications.push({
+            id: 'coverage',
+            question: 'How should DQL handle requirements without governed coverage?',
+            choices: ['Refine metrics or dimensions', 'Use governed semantic coverage', 'Include review-required analysis', 'Keep visible gaps'],
+            required: tiles.length === 0,
+        });
+    }
+    if (!plan.prompt.match(/\b(day|week|month|quarter|year|today|yesterday|current|previous|over time)\b/i)) {
+        clarifications.push({
+            id: 'time',
+            question: 'What time window and comparison should the App use?',
+            choices: ['Current period vs previous period', 'Trailing 30 days', 'Year to date', 'No time comparison'],
+            required: false,
+        });
+    }
     return {
         intent: {
             target: plan.publicationIntent,
             initialVisibility: 'private',
         },
+        buildFrame: {
+            goal: plan.businessGoal,
+            audience: plan.audience,
+            metrics,
+            dimensions,
+            grain: plan.requirements.find((requirement) => requirement.grain)?.grain,
+            filters,
+            desiredOutput: plan.planning.displayStrategy,
+        },
         tiles,
         gaps,
+        clarifications,
         followUps: gaps.map((gap) => gap.question).slice(0, 4),
         coverage: {
             certifiedTiles: tiles.filter((tile) => tile.certification === 'certified').length,
@@ -1343,6 +1618,7 @@ async function fillProposalGaps(proposal, hooks, maxGeneratedTiles) {
                 certification: 'ai_generated',
                 sourceClass: 'exploratory_analysis',
                 reviewStatus: 'required',
+                requirementIds: gap.id.startsWith('gap_') ? [gap.id.slice('gap_'.length)] : undefined,
                 preflight: {
                     status: preview ? 'passed' : unresolvedExecutionError ? 'blocked' : 'review_required',
                     sourceFingerprint: `sha256:${createHash('sha256').update(sql).digest('hex')}`,
@@ -1383,6 +1659,7 @@ async function fillProposalGaps(proposal, hooks, maxGeneratedTiles) {
                 certification: 'ai_generated',
                 sourceClass: 'exploratory_analysis',
                 reviewStatus: 'required',
+                requirementIds: gap.id.startsWith('gap_') ? [gap.id.slice('gap_'.length)] : undefined,
                 preflight: {
                     status: 'blocked',
                     message: 'Exploratory analysis generation failed.',
@@ -1530,6 +1807,309 @@ export async function proposeAppAiBuild(projectRoot, input, hooks) {
         kg.close();
     }
 }
+function materializeAppBuildProposalReviewAnalyses(projectRoot, draft, plan, proposalId, candidates, inputDashboards) {
+    const eligible = candidates.filter((candidate) => (candidate.source === 'ai_generated'
+        && Boolean(candidate.sql)
+        && !candidate.error
+        && candidate.preflight.status === 'passed'));
+    if (eligible.length === 0 || inputDashboards.length === 0) {
+        return { dashboards: inputDashboards, sourceOperations: [], reviewTasks: [], coverageByRequirement: new Map() };
+    }
+    const proposalKey = slugify(proposalId) || `proposal-${Date.now()}`;
+    const relativeDraftDir = `proposals/${proposalKey}/drafts`;
+    const absoluteDraftDir = join(projectRoot, '.dql', 'local', 'app-builds', draft.id, relativeDraftDir);
+    mkdirSync(absoluteDraftDir, { recursive: true });
+    const sourceOperations = [];
+    const reviewTasks = [];
+    const coverageByRequirement = new Map();
+    const generatedItems = [];
+    const normalizeQuestion = (value) => value.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+    for (const [index, candidate] of eligible.entries()) {
+        const sql = candidate.sql;
+        if (sql.includes('"""'))
+            throw new Error(`Exploratory SQL for "${candidate.title}" contains an unsupported triple-quote delimiter.`);
+        const candidateKey = slugify(candidate.id) || `analysis-${index + 1}`;
+        const blockName = `app_${slugify(draft.appId)}_${candidateKey}`;
+        const sourceRef = `${relativeDraftDir}/${candidateKey}.dql`;
+        const source = [
+            `block "${escapeDqlString(blockName)}" {`,
+            `  domain = "${escapeDqlString(plan.domain)}"`,
+            '  type = "custom"',
+            '  status = "review"',
+            `  owner = "${escapeDqlString(plan.owner)}"`,
+            `  description = "${escapeDqlString((candidate.answer ?? candidate.question ?? candidate.title).slice(0, 240))}"`,
+            candidate.question ? `  llmContext = "${escapeDqlString(`App-scoped exploratory analysis. Question: ${candidate.question}`)}"` : '',
+            '  caveats = ["AI-generated App analysis. Validate joins, filters, grain, and business interpretation before promotion."]',
+            '  tags = ["app-scoped", "ai-generated", "needs-review"]',
+            '',
+            '  query = """',
+            sql,
+            '  """',
+            '',
+            '  visualization {',
+            `    chart = "${escapeDqlString(normalizeGeneratedViz(candidate.viz))}"`,
+            '  }',
+            '}',
+            '',
+        ].filter(Boolean).join('\n');
+        const fingerprint = `sha256:${createHash('sha256').update(source).digest('hex')}`;
+        writeFileSync(join(absoluteDraftDir, `${candidateKey}.dql`), source, 'utf-8');
+        const sourceId = `review-dql:${candidate.id}`;
+        const componentId = `review_${candidateKey}`;
+        sourceOperations.push({
+            type: 'upsert_source',
+            source: {
+                id: sourceId,
+                kind: 'review_dql',
+                sourceRef,
+                qualifiedIdentity: candidate.title,
+                snapshotId: candidate.preflight.snapshotId ?? plan.snapshotId,
+                sourceFingerprint: fingerprint,
+                receiptId: candidate.preflight.receiptId,
+                trustState: 'review_required',
+                reviewStatus: 'required',
+            },
+        });
+        reviewTasks.push({
+            type: 'set_review_task',
+            task: {
+                id: `review-generated-${candidateKey}`,
+                message: `Validate the joins, grain, filters, and business interpretation for ${candidate.title}.`,
+                status: 'open',
+                sourceId,
+                pageId: inputDashboards[0].id,
+                tileId: componentId,
+            },
+        });
+        const requirementIds = candidate.requirementIds?.length
+            ? candidate.requirementIds
+            : plan.requirements.filter((requirement) => normalizeQuestion(requirement.question) === normalizeQuestion(candidate.question ?? '')).map((requirement) => requirement.id);
+        for (const requirementId of requirementIds) {
+            const current = coverageByRequirement.get(requirementId) ?? { sourceIds: [], componentIds: [] };
+            current.sourceIds.push(sourceId);
+            current.componentIds.push(componentId);
+            coverageByRequirement.set(requirementId, current);
+        }
+        generatedItems.push({
+            i: componentId,
+            x: (index % 2) * 6,
+            y: Math.floor(index / 2) * 4,
+            w: 6,
+            h: 4,
+            draftAnalysis: {
+                ref: sourceRef,
+                artifactFingerprint: fingerprint,
+                ...(candidate.preflight.snapshotId ?? plan.snapshotId ? { snapshotId: candidate.preflight.snapshotId ?? plan.snapshotId } : {}),
+                ...(candidate.preflight.receiptId ? { executionReceiptId: candidate.preflight.receiptId } : {}),
+            },
+            viz: { type: normalizeGeneratedViz(candidate.viz) },
+            title: candidate.title,
+            sourceClass: 'exploratory_analysis',
+            sourceEvidence: [
+                ...(candidate.sourceEvidence ?? []),
+                {
+                    source: sourceRef,
+                    reason: candidate.question
+                        ? `AI generated this private analysis for: ${candidate.question}`
+                        : 'AI generated this private analysis for a requirement without governed coverage.',
+                    kind: 'review_dql',
+                    trustState: 'review_required',
+                },
+            ],
+            review: { status: 'required', sourceFingerprint: fingerprint, ...(candidate.preflight.receiptId ? { preflightReceiptId: candidate.preflight.receiptId } : {}) },
+            trustState: 'review_required',
+            reviewStatus: 'review_required',
+        });
+    }
+    const first = inputDashboards[0];
+    const baseY = first.layout.items.reduce((max, item) => Math.max(max, item.y + item.h), 0);
+    const items = [...first.layout.items, ...generatedItems.map((item) => ({ ...item, y: item.y + baseY }))];
+    const sections = first.sections
+        ? first.sections.some((section) => section.kind === 'appendix')
+            ? first.sections
+            : [...first.sections, { id: 'review-appendix', title: 'Review-required analysis', kind: 'appendix', order: first.sections.length }]
+        : undefined;
+    const appendixId = sections?.find((section) => section.kind === 'appendix')?.id;
+    const finalItems = appendixId
+        ? items.map((item) => generatedItems.some((generated) => generated.i === item.i) ? { ...item, sectionId: appendixId } : item)
+        : items;
+    const page = {
+        ...first,
+        ...(sections ? { sections } : {}),
+        layout: {
+            ...first.layout,
+            items: finalItems,
+            responsive: responsiveLayoutsForDashboardItems(finalItems),
+        },
+    };
+    return {
+        dashboards: [page, ...inputDashboards.slice(1)],
+        sourceOperations,
+        reviewTasks,
+        coverageByRequirement,
+    };
+}
+/**
+ * AI is a coauthor of the same local AppBuildDraft used by manual authoring.
+ * This adapter reuses the governed planner, compiles its result outside the
+ * project, and returns typed operations. It does not mutate the draft or write
+ * any canonical App source.
+ */
+export async function proposeAppBuildDraftOperations(projectRoot, draft, input, hooks) {
+    const session = await proposeAppAiBuild(projectRoot, {
+        sessionId: `app_build_${draft.id}_${draft.revision}`,
+        prompt: input.prompt,
+        domain: draft.pages[0]?.metadata.domain,
+        audience: draft.frame.audience,
+        mode: draft.sourcePolicy === 'include_review_required' ? 'personal' : 'stakeholder',
+        exploreGaps: draft.sourcePolicy === 'include_review_required',
+        selectedBlockIds: input.selectedBlockIds,
+        ...(draft.baseApp ? { existingAppId: draft.baseApp.appId } : {}),
+    }, hooks);
+    if (session.status !== 'proposed' || !session.plan || !session.proposal) {
+        throw new Error(session.error ?? 'The App planner did not produce a proposal.');
+    }
+    const plan = session.plan;
+    const { KGStore, defaultKgPath, materializeAppPlanDocuments } = await import('@duckcodeailabs/dql-agent');
+    const kg = new KGStore(defaultKgPath(projectRoot));
+    let dashboards;
+    try {
+        dashboards = materializeAppPlanDocuments(plan, kg).dashboards;
+    }
+    finally {
+        kg.close();
+    }
+    const proposalTileById = new Map(session.proposal.tiles.map((tile) => [tile.id, tile]));
+    const plannedTiles = plan.pages.flatMap((page) => page.tiles);
+    const sourceOperations = plannedTiles.flatMap((tile) => {
+        const proposalTile = proposalTileById.get(tile.id);
+        if (tile.kind === 'certified_block' && tile.blockId) {
+            return [{
+                    type: 'upsert_source',
+                    source: {
+                        id: `block:${tile.blockId}`,
+                        kind: 'certified_block',
+                        sourceRef: tile.blockId,
+                        sourceFingerprint: proposalTile?.preflight.sourceFingerprint,
+                        receiptId: proposalTile?.preflight.receiptId,
+                        trustState: 'certified',
+                        reviewStatus: 'not_required',
+                    },
+                }];
+        }
+        if (tile.kind === 'semantic_query' && tile.semantic) {
+            return [{
+                    type: 'upsert_source',
+                    source: {
+                        id: `semantic:${tile.semantic.id}`,
+                        kind: 'governed_semantic',
+                        sourceRef: tile.semantic.id,
+                        qualifiedIdentity: tile.semantic.qualifiedMetricIds?.join(',') || tile.semantic.id,
+                        snapshotId: tile.semantic.snapshotId,
+                        sourceFingerprint: tile.semantic.definitionFingerprint,
+                        receiptId: proposalTile?.preflight.receiptId,
+                        trustState: 'review_required',
+                        reviewStatus: 'required',
+                    },
+                }];
+        }
+        return [];
+    });
+    const reviewAnalyses = materializeAppBuildProposalReviewAnalyses(projectRoot, draft, plan, session.id, session.proposal.tiles, dashboards);
+    dashboards = reviewAnalyses.dashboards;
+    sourceOperations.push(...reviewAnalyses.sourceOperations);
+    const sourceIdForCoverage = (source, sourceId) => {
+        if (!sourceId)
+            return [];
+        if (source === 'certified_block')
+            return [sourceId.startsWith('block:') ? sourceId : `block:${sourceId}`];
+        if (source === 'semantic_query')
+            return [sourceId.startsWith('semantic:') ? sourceId : `semantic:${sourceId}`];
+        return [];
+    };
+    const clarifications = session.proposal.clarifications.map((clarification) => ({
+        id: clarification.id,
+        question: clarification.question,
+        choices: clarification.choices.map((label, index) => ({ id: slugify(label) || `choice-${index + 1}`, label })),
+        required: clarification.required,
+    }));
+    const replaceInitialBlank = !draft.baseApp
+        && draft.pages.length === 1
+        && draft.pages[0].layout.items.length === 0
+        && !dashboards.some((page) => page.id === draft.pages[0].id);
+    const coverage = plan.requirementCoverage.map((item) => {
+        const reviewCoverage = reviewAnalyses.coverageByRequirement.get(item.requirementId);
+        if (reviewCoverage) {
+            return {
+                requirementId: item.requirementId,
+                status: 'covered',
+                sourceIds: reviewCoverage.sourceIds,
+                componentIds: reviewCoverage.componentIds,
+                reasons: ['Covered by explicitly selectable review-required App analysis.'],
+            };
+        }
+        return {
+            requirementId: item.requirementId,
+            status: item.status === 'covered' ? 'covered' : 'gap',
+            sourceIds: sourceIdForCoverage(item.source, item.sourceId),
+            componentIds: item.tileId ? [item.tileId] : [],
+            reasons: item.reasons,
+        };
+    });
+    const operations = [
+        { type: 'set_name', name: plan.name },
+        {
+            type: 'set_frame',
+            frame: {
+                goal: session.proposal.buildFrame.goal,
+                decision: plan.businessGoal,
+                audience: session.proposal.buildFrame.audience,
+                metrics: session.proposal.buildFrame.metrics,
+                dimensions: session.proposal.buildFrame.dimensions,
+                grain: session.proposal.buildFrame.grain,
+                timeRange: session.proposal.buildFrame.timeRange,
+                comparison: session.proposal.buildFrame.comparison,
+                filters: session.proposal.buildFrame.filters,
+                desiredOutput: session.proposal.buildFrame.desiredOutput,
+                clarificationQuestions: clarifications,
+            },
+        },
+        {
+            type: 'set_requirements',
+            requirements: plan.requirements.map((requirement) => ({
+                id: requirement.id,
+                question: requirement.question,
+                role: requirement.role,
+                required: true,
+                measures: requirement.measures,
+                dimensions: requirement.dimensions,
+                filters: requirement.filters,
+                grain: requirement.grain,
+            })),
+            coverage,
+        },
+        ...(replaceInitialBlank ? [{ type: 'remove_page', pageId: draft.pages[0].id }] : []),
+        ...dashboards.map((page) => ({ type: 'upsert_page', page })),
+        ...sourceOperations,
+        ...reviewAnalyses.reviewTasks,
+    ];
+    return {
+        id: session.id,
+        draftId: draft.id,
+        baseRevision: draft.revision,
+        baseProposalHash: draft.proposalHash,
+        operations,
+        defaultSelectedSourceIds: sourceOperations.flatMap((operation) => (operation.type === 'upsert_source' && operation.source.kind !== 'review_dql' ? [operation.source.id] : [])),
+        clarifications,
+        summary: {
+            requirements: plan.requirements.length,
+            covered: plan.requirementCoverage.filter((item) => item.status === 'covered').length,
+            gaps: plan.requirementCoverage.filter((item) => item.status === 'gap').length,
+            certifiedSources: session.proposal.coverage.certifiedTiles,
+            semanticSources: session.proposal.coverage.semanticTiles,
+        },
+    };
+}
 /**
  * Materialize explicitly selected exploratory candidates as Git-owned, app-scoped
  * review DQL. They are never promoted into the shared block library and the
@@ -1677,10 +2257,20 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
     if (selected.size === 0) {
         return { ok: false, error: 'Select at least one tile to create the app.', status: 400 };
     }
+    const plannedFilterIds = new Set([
+        ...(plan.globalFilters ?? []).map((filter) => filter.id),
+        ...plan.pages.flatMap((page) => (page.filters ?? []).map((filter) => filter.id)),
+    ]);
+    const selectedFilterIds = new Set((input.filterIds ?? Array.from(plannedFilterIds)).filter((filterId) => plannedFilterIds.has(filterId)));
     // Filter the plan's certified tiles down to the confirmed selection; structural
     // tiles (narrative, draft placeholders) stay — they document the story + gaps.
     const committedPlan = {
         ...plan,
+        globalFilters: (plan.globalFilters ?? []).filter((filter) => selectedFilterIds.has(filter.id)),
+        // `+ Add page` must not rewrite the App it is adding to (`UI-017`), but the
+        // fields were dropped with no error, so a name typed in that brief silently
+        // vanished. Adding a page keeps the App's own name; use `PATCH /api/apps/:id`
+        // to rename, and see `appliedNameWarnings` below for the reported diagnostic.
         ...(!isExistingPageBuild && cleanString(input.appName) ? { name: cleanString(input.appName).slice(0, 120) } : {}),
         ...(!isExistingPageBuild && cleanString(input.audience) ? { audience: cleanString(input.audience).slice(0, 120) } : {}),
         pages: plan.pages.map((page, pageIndex) => ({
@@ -1688,15 +2278,20 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
             ...(isExistingPageBuild && pageIndex === 0 && cleanString(input.pageTitle)
                 ? { title: cleanString(input.pageTitle).slice(0, 120) }
                 : {}),
+            filters: (page.filters ?? []).filter((filter) => selectedFilterIds.has(filter.id)),
             tiles: page.tiles
                 .filter((tile) => !['certified_block', 'semantic_query'].includes(tile.kind) || selected.has(tile.id))
                 .map((tile) => {
                 const override = tileOverrides[tile.id];
+                const filteredTile = {
+                    ...tile,
+                    filterBindings: (tile.filterBindings ?? []).filter((binding) => selectedFilterIds.has(binding.filter)),
+                };
                 if (!override)
-                    return tile;
+                    return filteredTile;
                 const viz = override.viz;
                 return {
-                    ...tile,
+                    ...filteredTile,
                     ...(override.title ? { title: override.title } : {}),
                     ...(viz ? { viz } : {}),
                     ...(viz && tile.display ? {
@@ -1721,7 +2316,15 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
     const { KGStore, defaultKgPath, ensureMetadataCatalogFresh, generateAppFromPlan, reindexProject, validateAppPlan, } = await import('@duckcodeailabs/dql-agent');
     const index = await reindexProject(projectRoot, { kgPath: defaultKgPath(projectRoot) });
     if (!session.snapshotId || index.kgFingerprint !== session.snapshotId) {
-        return { ok: false, error: 'Project sources changed after this proposal was created. Refresh and review the App proposal again.', status: 409 };
+        // This compares a whole-project index, so an unrelated block or model edit
+        // invalidates a pending proposal. Kept deliberately strict — the proposal's
+        // preflight receipts are bound to that snapshot — but the message now says
+        // what to do instead of only reporting a conflict.
+        return {
+            ok: false,
+            error: 'Project sources changed after this proposal was created, so its preflight evidence no longer applies. Re-run the build request to get a fresh proposal.',
+            status: 409,
+        };
     }
     const kg = new KGStore(defaultKgPath(projectRoot));
     try {
@@ -1747,7 +2350,10 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
         const stagedAppDir = isExistingPageBuild
             ? join(stagingRoot, 'candidate', 'apps', committedPlan.appId)
             : generatedAppDir;
-        const targetAppDir = join(projectRoot, 'apps', committedPlan.appId);
+        // Apps also resolve under `domains/**/apps/<id>`. Hardcoding the canonical
+        // root meant a domain-hosted App always failed the existence check below
+        // and could never have a page added.
+        const targetAppDir = existingApp?.appDir ?? join(projectRoot, 'apps', committedPlan.appId);
         const backupAppDir = join(projectRoot, '.dql', 'local', 'app-build-staging', `${session.id}-backup`);
         rmSync(stagingRoot, { recursive: true, force: true });
         try {
@@ -1841,6 +2447,15 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
             rmSync(stagingRoot, { recursive: true, force: true });
         }
         const attachWarnings = [];
+        // Adding a page deliberately cannot rename or re-audience the App it joins.
+        // Say so instead of discarding the input silently — this array existed and
+        // was never written to, so the drop had no surface at all.
+        if (isExistingPageBuild && cleanString(input.appName)) {
+            attachWarnings.push('The App name was not changed: adding a page cannot rename the App. Rename it from the App header.');
+        }
+        if (isExistingPageBuild && cleanString(input.audience)) {
+            attachWarnings.push('The audience was not changed: adding a page keeps the App\'s existing audience.');
+        }
         await ensureMetadataCatalogFresh(projectRoot, { force: true });
         const app = collectAppsList(projectRoot).find((entry) => entry.id === committedPlan.appId) ?? null;
         const next = {
@@ -1858,6 +2473,7 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
                     ? { pageTitle: committedPlan.pages[0]?.title }
                     : { appName: committedPlan.name }),
                 audience: committedPlan.audience,
+                filterIds: Array.from(selectedFilterIds),
                 tileOverrides,
             },
             warnings: [...session.warnings, ...attachWarnings],
@@ -1920,7 +2536,7 @@ async function routeAppAskQuestion(ctx, appId, input) {
     const tile = dashboard?.layout.items.find((item) => item.i === input.tileId ||
         (input.blockId && item.block && 'blockId' in item.block && item.block.blockId === input.blockId));
     const blockId = cleanString(input.blockId) || (tile?.block && 'blockId' in tile.block ? tile.block.blockId : undefined);
-    const appContext = buildAppContextEnvelope(loaded.app, loaded.appDir, {
+    const appContext = buildAppContextEnvelope(ctx.projectRoot, loaded.app, loaded.appDir, {
         dashboardId,
         tileId: cleanString(input.tileId) || undefined,
         blockId,
@@ -2170,17 +2786,80 @@ function questionIsAboutFocusedTile(question) {
     return true;
 }
 /** Map a governed AgentAnswer into the App Copilot's response shape. */
+/** Overlap needed before a draft is offered as covering the question. */
+const APP_DRAFT_MATCH_MIN_OVERLAP = 2;
+const APP_DRAFT_STOPWORDS = new Set([
+    'the', 'a', 'an', 'and', 'or', 'for', 'with', 'what', 'which', 'who', 'how', 'why', 'is', 'are',
+    'do', 'does', 'can', 'you', 'me', 'my', 'our', 'this', 'that', 'show', 'give', 'get', 'by', 'of',
+    'in', 'on', 'to', 'from', 'all', 'complete', 'view',
+]);
+function appDraftTokens(value) {
+    return new Set(value.toLowerCase().split(/[^a-z0-9]+/)
+        .filter((word) => word.length > 2 && !APP_DRAFT_STOPWORDS.has(word)));
+}
+/**
+ * The app's own draft that best covers a question the governed loop could not answer.
+ *
+ * Drafts are review-required exploratory analyses saved in the app. They are not
+ * indexed into the manifest, so retrieval cannot find them — but when the loop
+ * has just refused for want of a certified path, the app frequently already
+ * contains a draft that does exactly the thing. Offering it is strictly better
+ * than explaining the gap and stopping, and it never launders trust: the answer
+ * stays review-required and says the source is an unreviewed draft.
+ */
+export function matchAppDraftForQuestion(drafts, question) {
+    const asked = appDraftTokens(question);
+    if (asked.size === 0)
+        return undefined;
+    let best;
+    for (const draft of drafts ?? []) {
+        const candidate = appDraftTokens([draft.name, draft.question ?? '', draft.description ?? ''].join(' '));
+        let score = 0;
+        for (const token of asked)
+            if (candidate.has(token))
+                score += 1;
+        if (score >= APP_DRAFT_MATCH_MIN_OVERLAP && (!best || score > best.score))
+            best = { draft, score };
+    }
+    return best?.draft;
+}
 function mapGovernedToAppAsk(governed, input) {
     const isCertified = governed.certification === 'certified' || governed.kind === 'certified';
     const noAnswer = governed.kind === 'no_answer';
-    const answer = cleanString(governed.answer) || cleanString(governed.text) || 'No governed answer was available for this question.';
+    const governedText = cleanString(governed.answer) || cleanString(governed.text) || 'No governed answer was available for this question.';
+    // The loop just declined for want of certified evidence. Before returning only
+    // the gap, check whether this app already saved a draft that covers it.
+    const draft = noAnswer ? matchAppDraftForQuestion(input.appContext?.drafts ?? [], input.question) : undefined;
+    // App drafts are often generated FROM a refusal like this one, so their
+    // description can be the same paragraph the loop just returned. Only add it
+    // when it actually says something new.
+    const normalize = (value) => value.toLowerCase().replace(/\s+/g, ' ').trim();
+    const draftAdds = draft?.description && !normalize(governedText).includes(normalize(draft.description).slice(0, 80))
+        ? draft.description
+        : '';
+    const answer = draft
+        ? [
+            governedText,
+            '',
+            `This app already has a saved draft for it: "${draft.name}" (${draft.status}).`,
+            draftAdds,
+            'It is an unreviewed draft, not a certified answer — open it under Drafts, check the join, grain, and filters, then certify it to make it governed.',
+        ].filter(Boolean).join('\n')
+        : governedText;
     const route = noAnswer ? 'metadata_answer' : isCertified ? 'certified_answer' : 'generated_answer';
-    const trustState = noAnswer ? 'draft_ready' : isCertified ? 'certified' : 'review_required';
+    // Offering a draft is actionable but unreviewed, so it is review_required
+    // rather than the bare draft_ready used when there is nothing to offer.
+    const trustState = draft ? 'review_required' : noAnswer ? 'draft_ready' : isCertified ? 'certified' : 'review_required';
     const govCitations = Array.isArray(governed.citations)
         ? governed.citations.map((c) => ({ kind: String(c.kind ?? 'source'), name: String(c.name ?? '') })).filter((c) => c.name)
         : [];
     const seen = new Set();
-    const citations = [...input.citations, ...govCitations].filter((c) => {
+    const citations = [
+        ...input.citations,
+        ...govCitations,
+        // Cite the draft so the user can open the exact file being offered.
+        ...(draft ? [{ kind: 'draft', name: draft.name, path: draft.path }] : []),
+    ].filter((c) => {
         const key = `${c.kind}:${c.name}`;
         if (seen.has(key))
             return false;
@@ -2194,9 +2873,11 @@ function mapGovernedToAppAsk(governed, input) {
         trustState,
         reviewStatus: trustState,
         citations,
-        followUps: noAnswer
-            ? ['Name the metric and grain', 'Pick a certified tile', 'Start driver analysis']
-            : ['Investigate drivers', 'Break this down further', 'Create a draft DQL block'],
+        followUps: draft
+            ? [`Open the "${draft.name}" draft`, 'Review its join and grain', 'Certify it to make it governed']
+            : noAnswer
+                ? ['Name the metric and grain', 'Pick a certified tile', 'Start driver analysis']
+                : ['Investigate drivers', 'Break this down further', 'Create a draft DQL block'],
         decision: buildAppAskDecision(route, { question: input.question, blockId: input.blockId, appName: input.appName }),
     };
 }
@@ -2386,6 +3067,75 @@ export function recommendDashboardTile(projectRoot, appId, dashboardId, input) {
         warnings: recommendation.warnings,
     };
 }
+/**
+ * Rename an App, and optionally a page inside it.
+ *
+ * `dql.app.json` previously had exactly two writers — create and publish — so
+ * an App could never be renamed after it was built. Only the display `name`
+ * changes here: the App **id** is also its folder name and is referenced by
+ * notebooks, product context, and deep links, so renaming must not move it.
+ *
+ * The write is staged and swapped like the publish path, and guarded by the
+ * caller-supplied fingerprint so a concurrent edit cannot be clobbered.
+ */
+export function renameApp(projectRoot, appId, input) {
+    const loaded = loadAppById(projectRoot, appId);
+    if (!loaded)
+        return { ok: false, error: `App "${appId}" not found`, code: 'APP_NOT_FOUND' };
+    if (input.expectedFingerprint && fingerprintAppDirectory(loaded.appDir) !== input.expectedFingerprint) {
+        return { ok: false, error: 'This App changed since it was loaded. Refresh and rename again.', code: 'APP_CHANGED' };
+    }
+    const name = cleanString(input.name);
+    const pageTitle = cleanString(input.pageTitle);
+    if (!name && !pageTitle)
+        return { ok: false, error: 'Provide a name or a pageTitle.', code: 'INVALID_REQUEST' };
+    const appPath = join(loaded.appDir, 'dql.app.json');
+    const parsedApp = parseAppDocument(JSON.stringify({ ...loaded.app, ...(name ? { name } : {}) }), appPath);
+    if (!parsedApp.document)
+        return { ok: false, error: parsedApp.errors.map((err) => err.message).join('; ') };
+    const renamedDashboards = [];
+    if (pageTitle) {
+        const homepage = loaded.app.homepage;
+        const dashboardId = cleanString(input.dashboardId)
+            || (homepage?.type === 'dashboard' ? homepage.id : undefined);
+        const source = findDashboardsForApp(loaded.appDir)
+            .map((path) => ({ path, document: loadDashboardDocument(path).document }))
+            .find((item) => item.document && (!dashboardId || item.document.id === dashboardId));
+        if (!source?.document)
+            return { ok: false, error: `Dashboard "${dashboardId ?? ''}" not found in app "${appId}"`, code: 'DASHBOARD_NOT_FOUND' };
+        const next = { ...source.document, metadata: { ...source.document.metadata, title: pageTitle } };
+        const parsed = parseDashboardDocument(JSON.stringify(next), source.path);
+        if (!parsed.document)
+            return { ok: false, error: parsed.errors.map((err) => err.message).join('; ') };
+        renamedDashboards.push({ sourcePath: source.path, document: parsed.document });
+    }
+    const stagingBase = join(projectRoot, '.dql', 'local', 'app-rename-staging');
+    const stagedAppDir = join(stagingBase, `${appId}-next`);
+    const backupAppDir = join(stagingBase, `${appId}-backup`);
+    rmSync(stagedAppDir, { recursive: true, force: true });
+    rmSync(backupAppDir, { recursive: true, force: true });
+    mkdirSync(stagingBase, { recursive: true });
+    cpSync(loaded.appDir, stagedAppDir, { recursive: true });
+    writeFileSync(join(stagedAppDir, 'dql.app.json'), JSON.stringify(parsedApp.document, null, 2) + '\n', 'utf-8');
+    for (const dashboard of renamedDashboards) {
+        writeFileSync(join(stagedAppDir, relative(loaded.appDir, dashboard.sourcePath)), JSON.stringify(dashboard.document, null, 2) + '\n', 'utf-8');
+    }
+    try {
+        renameSync(loaded.appDir, backupAppDir);
+        renameSync(stagedAppDir, loaded.appDir);
+        rmSync(backupAppDir, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (existsSync(backupAppDir) && !existsSync(loaded.appDir))
+            renameSync(backupAppDir, loaded.appDir);
+        throw error;
+    }
+    return {
+        ok: true,
+        app: parsedApp.document,
+        paths: [relative(projectRoot, appPath), ...renamedDashboards.map((item) => relative(projectRoot, item.sourcePath))],
+    };
+}
 export function promoteAppForStakeholders(projectRoot, appId, input = {}) {
     const loaded = loadAppById(projectRoot, appId);
     if (!loaded)
@@ -2393,7 +3143,7 @@ export function promoteAppForStakeholders(projectRoot, appId, input = {}) {
     const dashboardSources = findDashboardsForApp(loaded.appDir)
         .map((path) => ({ path, document: loadDashboardDocument(path).document }))
         .filter((item) => Boolean(item.document));
-    const readiness = appPublicationReadiness(dashboardSources.map((item) => item.document));
+    const readiness = appPublicationReadiness(projectRoot, dashboardSources.map((item) => item.document));
     if (!readiness.ready) {
         return {
             ok: false,
@@ -2456,101 +3206,853 @@ export function promoteAppForStakeholders(projectRoot, appId, input = {}) {
         writeFileSync(stagedPath, JSON.stringify(dashboard.document, null, 2) + '\n', 'utf-8');
     }
     try {
-        renameSync(loaded.appDir, backupAppDir);
-        renameSync(stagedAppDir, loaded.appDir);
-        rmSync(backupAppDir, { recursive: true, force: true });
+        renameSync(loaded.appDir, backupAppDir);
+        renameSync(stagedAppDir, loaded.appDir);
+        rmSync(backupAppDir, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (existsSync(backupAppDir) && !existsSync(loaded.appDir))
+            renameSync(backupAppDir, loaded.appDir);
+        throw error;
+    }
+    const paths = [relative(projectRoot, appPath), ...dashboards.map((dashboard) => relative(projectRoot, dashboard.sourcePath))];
+    return { ok: true, app: parsedApp.document, paths, removedLocalTiles, readiness };
+}
+export function approveAppSemanticTiles(projectRoot, appId, dashboardId, input) {
+    const loaded = loadDashboardForApp(projectRoot, appId, dashboardId);
+    if (!loaded)
+        return { ok: false, error: `Dashboard "${dashboardId}" not found in App "${appId}".` };
+    const currentFingerprint = `sha256:${createHash('sha256').update(JSON.stringify(loaded.dashboard)).digest('hex')}`;
+    if (!input.expectedDashboardFingerprint || input.expectedDashboardFingerprint !== currentFingerprint) {
+        return { ok: false, error: 'The dashboard changed after the reviewed run. Run it again before approval.' };
+    }
+    const selected = new Set(input.tileIds);
+    const semanticIds = new Set(loaded.dashboard.layout.items.filter((item) => item.semantic).map((item) => item.i));
+    const invalid = input.tileIds.filter((tileId) => !semanticIds.has(tileId));
+    if (invalid.length > 0)
+        return { ok: false, error: `Only semantic tiles can be approved here: ${invalid.join(', ')}` };
+    const reviewedAt = new Date().toISOString();
+    const dashboard = {
+        ...loaded.dashboard,
+        layout: {
+            ...loaded.dashboard.layout,
+            items: loaded.dashboard.layout.items.map((item) => {
+                if (!selected.has(item.i) || !item.semantic)
+                    return item;
+                return {
+                    ...item,
+                    semantic: { ...item.semantic, snapshotId: input.snapshotId },
+                    review: {
+                        status: 'approved',
+                        sourceFingerprint: item.semantic.definitionFingerprint,
+                        preflightReceiptId: input.runId,
+                        reviewedAt,
+                        reviewedBy: input.reviewer,
+                    },
+                    trustState: 'review_required',
+                    reviewStatus: 'review_required',
+                };
+            }),
+        },
+    };
+    const parsed = parseDashboardDocument(JSON.stringify(dashboard), loaded.path);
+    if (!parsed.document)
+        return { ok: false, error: parsed.errors.map((error) => error.message).join('; ') };
+    writeFileSync(loaded.path, JSON.stringify(parsed.document, null, 2) + '\n', 'utf-8');
+    return { ok: true, dashboard: parsed.document, path: relative(projectRoot, loaded.path) };
+}
+function appPublicationReadiness(projectRoot, dashboards, options = {}) {
+    const blockers = [];
+    let governedTiles = 0;
+    const blocks = collectBlockCandidates(projectRoot);
+    for (const dashboard of dashboards) {
+        for (const item of dashboard.layout.items) {
+            if (item.block) {
+                governedTiles += 1;
+                const blockRef = item.block;
+                const block = blocks.find((candidate) => ('blockId' in blockRef
+                    ? candidate.id === blockRef.blockId || candidate.name === blockRef.blockId
+                    : candidate.path === blockRef.ref));
+                if (!block || block.status !== 'certified') {
+                    blockers.push({
+                        dashboardId: dashboard.id,
+                        tileId: item.i,
+                        code: 'block_not_certified',
+                        message: `${dashboard.id}/${item.i} no longer resolves to a certified block.`,
+                    });
+                }
+                else if (item.review?.sourceFingerprint?.startsWith('sha256:') && item.review.sourceFingerprint !== block.fingerprint) {
+                    blockers.push({
+                        dashboardId: dashboard.id,
+                        tileId: item.i,
+                        code: 'block_source_changed',
+                        message: `${dashboard.id}/${item.i} changed after it was selected; review the current certified block before publication.`,
+                    });
+                }
+            }
+            if (item.draftAnalysis) {
+                blockers.push({
+                    dashboardId: dashboard.id,
+                    tileId: item.i,
+                    code: 'exploratory_source',
+                    message: `${dashboard.id}/${item.i} references app-scoped exploratory DQL; promote it to governed semantic logic or a certified block first.`,
+                });
+            }
+            if (item.semantic) {
+                governedTiles += 1;
+                if (item.review?.status !== 'approved') {
+                    blockers.push({
+                        dashboardId: dashboard.id,
+                        tileId: item.i,
+                        code: 'semantic_review',
+                        message: `${dashboard.id}/${item.i} semantic result has not been explicitly approved.`,
+                    });
+                }
+                if (!item.semantic.snapshotId || !item.review?.preflightReceiptId) {
+                    blockers.push({
+                        dashboardId: dashboard.id,
+                        tileId: item.i,
+                        code: 'semantic_preflight',
+                        message: `${dashboard.id}/${item.i} needs a snapshot-bound semantic preflight receipt.`,
+                    });
+                }
+            }
+            if (dashboard.version === 2 && (item.block || item.semantic || item.draftAnalysis)) {
+                for (const filter of dashboard.filters ?? []) {
+                    if (filter.scope?.tileIds && !filter.scope.tileIds.includes(item.i))
+                        continue;
+                    const binding = item.filterBindings?.find((candidate) => candidate.filter === filter.id);
+                    // An explicit unsupported binding is a governed exclusion, not a
+                    // missing binding. Studio shows the reason on the affected tile and
+                    // the filter deliberately leaves that tile unchanged.
+                    if (binding?.capability === 'unsupported' && binding.unsupportedReason?.trim())
+                        continue;
+                    const settled = options.settledPageIds?.has(dashboard.id) ?? false;
+                    if (!binding || (!binding.binding && binding.mode !== 'parameter') || (binding.capability === 'preflight_required' && !settled)) {
+                        blockers.push({
+                            dashboardId: dashboard.id,
+                            tileId: item.i,
+                            code: 'filter_not_preflighted',
+                            message: `${dashboard.id}/${item.i} does not have a preflighted binding for filter ${filter.label ?? filter.id}.`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return { ready: blockers.length === 0, governedTiles, blockers };
+}
+function appAiBuildSessionDir(projectRoot) {
+    return join(projectRoot, '.dql', 'local', 'app-ai-builds');
+}
+function appBuildDraftDir(projectRoot) {
+    // Read-only migration location for AppBuildDraft v1 JSON files. New drafts
+    // are persisted transactionally in .dql/local/apps.sqlite.
+    return join(projectRoot, '.dql', 'local', 'app-builds');
+}
+export function createStoredAppBuildDraft(projectRoot, input) {
+    const baseAppId = cleanString(input.baseAppId);
+    const base = baseAppId ? loadAppById(projectRoot, baseAppId) : null;
+    if (baseAppId && !base)
+        throw new Error(`App "${baseAppId}" not found.`);
+    const name = cleanString(input.name) || base?.app.name || cleanString(input.goal) || 'Untitled App';
+    const appId = base?.app.id || cleanString(input.appId) || suggestAppId(name);
+    const id = `build_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const pageId = 'overview';
+    const emptyItems = [];
+    const blankPage = {
+        version: 2,
+        id: pageId,
+        metadata: {
+            title: 'Overview',
+            description: cleanString(input.goal) || `Local draft canvas for ${name}`,
+            domain: cleanString(input.domain) || base?.app.domain || 'general',
+            audience: cleanString(input.audience) || base?.app.audience || 'stakeholders',
+            visibility: 'private',
+            lifecycle: 'draft',
+        },
+        layout: {
+            kind: 'grid', cols: 12, rowHeight: 80, items: emptyItems,
+            responsive: {
+                wide: { kind: 'grid', cols: 12, rowHeight: 80, items: emptyItems },
+                medium: { kind: 'grid', cols: 6, rowHeight: 80, items: emptyItems },
+                narrow: { kind: 'grid', cols: 1, rowHeight: 80, items: emptyItems },
+            },
+        },
+    };
+    const basePages = base
+        ? findDashboardsForApp(base.appDir)
+            .map((path) => loadDashboardDocument(path).document)
+            .filter((page) => Boolean(page))
+        : [];
+    const template = input.template ?? 'blank';
+    const pages = basePages.length ? basePages : [applyAppStudioTemplate(blankPage, template, name)];
+    const draft = createAppBuildDraft({
+        id,
+        appId,
+        name,
+        ...(base ? { baseApp: { appId: base.app.id, fingerprint: fingerprintAppDirectory(base.appDir) } } : {}),
+        authoringMode: input.authoringMode === 'manual' ? 'manual' : 'ai',
+        template,
+        sourcePolicy: input.sourcePolicy,
+        frame: {
+            goal: cleanString(input.goal) || `Create ${name}`,
+            audience: cleanString(input.audience) || base?.app.audience || 'stakeholders',
+            metrics: [], dimensions: [], filters: [], desiredOutput: 'One responsive analytical page',
+            clarificationQuestions: input.authoringMode === 'manual' || base || input.entrypoint === 'ask' ? [] : [{
+                    id: 'metric',
+                    question: 'Which governed business metric should lead this App?',
+                    choices: [
+                        { id: 'certified', label: 'Choose a certified block' },
+                        { id: 'semantic', label: 'Choose a semantic metric' },
+                        { id: 'gap', label: 'Keep a visible gap' },
+                    ],
+                    required: true,
+                }],
+        },
+        pages,
+    });
+    writeStoredAppBuildDraft(projectRoot, draft);
+    return draft;
+}
+/**
+ * Adds an Ask result to the same local AppBuildDraft used by manual and AI
+ * authoring. Certified answers retain their block identity. Exploratory DQL is
+ * materialized as an app-scoped local artifact and remains review-required;
+ * SQL is never embedded in the dashboard JSON or written to Project source.
+ */
+export function addAskResultToAppBuildDraft(projectRoot, draftId, input) {
+    const draft = loadStoredAppBuildDraft(projectRoot, draftId);
+    if (!draft)
+        throw new Error('App Build Draft not found.');
+    if (input.expectedRevision !== draft.revision || input.expectedProposalHash !== draft.proposalHash) {
+        throw new Error('APP_BUILD_REVISION_CONFLICT: refresh the local draft before adding this Ask result.');
+    }
+    const page = draft.pages.find((candidate) => candidate.id === cleanString(input.pageId)) ?? draft.pages[0];
+    if (!page)
+        throw new Error('The local App draft needs a page before adding an Ask result.');
+    const question = cleanString(input.question).slice(0, 500);
+    const answer = cleanString(input.answer).slice(0, 40_000);
+    const title = (cleanString(input.title) || titleForGapQuestion(question || 'Ask result')).slice(0, 120);
+    const requestedBlockId = cleanString(input.certifiedBlockId);
+    const dqlSource = cleanString(input.dqlSource);
+    const sql = cleanString(input.sql);
+    if (dqlSource.length > 400_000 || sql.length > 200_000)
+        throw new Error('Ask result source exceeds the local App artifact limit.');
+    const sourceIdentity = requestedBlockId || dqlSource || sql || `${question}\n${answer}`;
+    if (!sourceIdentity)
+        throw new Error('The Ask result did not include reusable evidence.');
+    const identity = createHash('sha256').update(sourceIdentity).digest('hex').slice(0, 16);
+    const tileId = `ask-${identity}`;
+    if (draft.pages.some((candidate) => candidate.layout.items.some((tile) => tile.i === tileId))) {
+        return { ok: true, draft, pageId: page.id, tileId, deduped: true };
+    }
+    const nextY = page.layout.items.reduce((max, tile) => Math.max(max, tile.y + tile.h), 0);
+    const viz = normalizeGeneratedViz(input.visualization);
+    const operations = [];
+    let artifactPath;
+    let artifactWasCreated = false;
+    let tile;
+    if (requestedBlockId) {
+        const block = collectBlockCandidates(projectRoot).find((candidate) => candidate.status === 'certified'
+            && (candidate.id === requestedBlockId || candidate.name === requestedBlockId || candidate.path === requestedBlockId));
+        if (!block)
+            throw new Error(`Certified block "${requestedBlockId}" is no longer available.`);
+        const sourceId = `block:${block.id}`;
+        operations.push({
+            type: 'upsert_source',
+            source: {
+                id: sourceId,
+                kind: 'certified_block',
+                sourceRef: block.id,
+                sourceFingerprint: block.fingerprint,
+                trustState: 'certified',
+                reviewStatus: 'not_required',
+            },
+        });
+        tile = {
+            i: tileId, x: 0, y: nextY, w: 6, h: 4,
+            block: { blockId: block.id },
+            viz: { type: viz === 'table' ? normalizeVizType(block.chartType) : viz },
+            title,
+            sourceClass: 'certified_block',
+            filterBindings: block.filterIds.map((filter) => ({ filter, binding: filter, mode: 'predicate', capability: 'preflight_required' })),
+            sourceEvidence: [{ source: block.id, reason: question ? `Ask answer for: ${question}` : 'Added from a certified Ask answer.', kind: 'certified_block', trustState: 'certified' }],
+            review: { status: 'not_required', sourceFingerprint: block.fingerprint },
+            trustState: 'certified',
+            reviewStatus: 'certified',
+        };
+    }
+    else if (dqlSource || sql) {
+        const sourceId = `review-dql:ask-${identity}`;
+        const sourceRef = `analysis/ask-${identity}.dql`;
+        const source = dqlSource || [
+            `block "ask_${identity}" {`,
+            `  domain = "${escapeDqlString(page.metadata.domain ?? 'general')}"`,
+            '  type = "custom"',
+            '  status = "review"',
+            '  owner = "local-ask"',
+            `  description = "${escapeDqlString(answer || question || title)}"`,
+            question ? `  llmContext = "${escapeDqlString(`Ask result: ${question}`)}"` : '',
+            '  caveats = ["Ask-generated local analysis. Validate joins, grain, filters, and interpretation before promotion."]',
+            '  tags = ["app-scoped", "ask-generated", "needs-review"]',
+            '',
+            '  query = """',
+            sql,
+            '  """',
+            '',
+            '  visualization {',
+            `    chart = "${escapeDqlString(normalizeGeneratedViz(input.visualization))}"`,
+            '  }',
+            '}',
+            '',
+        ].filter(Boolean).join('\n');
+        const fingerprint = `sha256:${createHash('sha256').update(source).digest('hex')}`;
+        artifactPath = join(projectRoot, '.dql', 'local', 'app-builds', draft.id, sourceRef);
+        operations.push(...(draft.sourcePolicy === 'include_review_required'
+            ? []
+            : [{ type: 'set_source_policy', sourcePolicy: 'include_review_required' }]), {
+            type: 'upsert_source',
+            source: {
+                id: sourceId,
+                kind: 'review_dql',
+                sourceRef,
+                qualifiedIdentity: title,
+                sourceFingerprint: fingerprint,
+                trustState: 'review_required',
+                reviewStatus: 'required',
+            },
+        }, {
+            type: 'set_review_task',
+            task: {
+                id: `review-ask-${identity}`,
+                message: `Validate the joins, grain, filters, and business interpretation for ${title}.`,
+                status: 'open',
+                sourceId,
+                pageId: page.id,
+                tileId,
+            },
+        });
+        tile = {
+            i: tileId, x: 0, y: nextY, w: 6, h: 4,
+            draftAnalysis: { ref: sourceRef, artifactFingerprint: fingerprint },
+            viz: { type: viz },
+            title,
+            sourceClass: 'exploratory_analysis',
+            sourceEvidence: [{ source: sourceRef, reason: question ? `Ask generated this private analysis for: ${question}` : 'Ask generated this private analysis.', kind: 'review_dql', trustState: 'review_required' }],
+            review: { status: 'required', sourceFingerprint: fingerprint },
+            trustState: 'review_required',
+            reviewStatus: 'review_required',
+        };
+        if (!existsSync(artifactPath)) {
+            mkdirSync(dirname(artifactPath), { recursive: true });
+            writeFileSync(artifactPath, source, 'utf-8');
+            artifactWasCreated = true;
+        }
+    }
+    else {
+        const sourceId = `text:ask-${identity}`;
+        operations.push(...(draft.sourcePolicy === 'include_review_required'
+            ? []
+            : [{ type: 'set_source_policy', sourcePolicy: 'include_review_required' }]), { type: 'upsert_source', source: { id: sourceId, kind: 'text', sourceRef: `ask:${identity}`, trustState: 'review_required', reviewStatus: 'required' } }, { type: 'set_review_task', task: { id: `review-ask-${identity}`, message: `Review the Ask narrative ${title} before publication.`, status: 'open', sourceId, pageId: page.id, tileId } });
+        tile = {
+            i: tileId, x: 0, y: nextY, w: 12, h: 2,
+            text: { markdown: answer || question },
+            viz: { type: 'text' },
+            title,
+            sourceClass: 'narrative',
+            sourceEvidence: [{ source: `ask:${identity}`, reason: 'Saved from Ask as an editable review-required narrative.', kind: 'text', trustState: 'review_required' }],
+            review: { status: 'required' },
+            trustState: 'review_required',
+            reviewStatus: 'review_required',
+        };
+    }
+    operations.push({ type: 'add_tile', pageId: page.id, tile });
+    try {
+        const next = applyAppBuildDraftOperations(draft, draft.revision, operations);
+        writeStoredAppBuildDraft(projectRoot, next, { expectedRevision: draft.revision, operations });
+        return { ok: true, draft: next, pageId: page.id, tileId, deduped: false };
+    }
+    catch (error) {
+        if (artifactWasCreated && artifactPath)
+            rmSync(artifactPath, { force: true });
+        throw error;
+    }
+}
+function applyAppStudioTemplate(page, template, appName) {
+    if (template === 'blank')
+        return page;
+    const intro = template === 'executive_brief'
+        ? `# ${appName}\n\nState the decision this brief supports, then add governed evidence below.`
+        : template === 'operational_dashboard'
+            ? `# ${appName}\n\nMonitor current performance, changes, and the details that require action.`
+            : `# ${appName}\n\nDocument the question, findings, caveats, and evidence for this investigation.`;
+    const items = [{
+            i: 'template-introduction', x: 0, y: 0, w: 12, h: 2,
+            title: template === 'investigation' ? 'Investigation question' : 'Executive context',
+            sectionId: 'exec_summary',
+            text: { markdown: intro },
+            viz: { type: 'text' },
+            sourceClass: 'narrative',
+            trustState: 'draft_ready',
+            reviewStatus: 'draft_ready',
+        }];
+    const sections = template === 'investigation'
+        ? [
+            { id: 'exec_summary', title: 'Question', kind: 'exec_summary', order: 0 },
+            { id: 'insight', title: 'Findings and comparisons', kind: 'insight', order: 1 },
+            { id: 'appendix', title: 'Caveats and evidence', kind: 'appendix', order: 2 },
+        ]
+        : [
+            { id: 'exec_summary', title: 'Executive summary', kind: 'exec_summary', order: 0 },
+            { id: 'kpi_band', title: 'Key metrics', kind: 'kpi_band', order: 1 },
+            { id: 'insight', title: template === 'executive_brief' ? 'Decision evidence' : 'Trends and drivers', kind: 'insight', order: 2 },
+            { id: 'appendix', title: 'Detail and evidence', kind: 'appendix', order: 3 },
+        ];
+    return {
+        ...page,
+        sections,
+        layout: {
+            ...page.layout,
+            items,
+            responsive: responsiveLayoutsForDashboardItems(items),
+        },
+    };
+}
+function loadStoredAppBuildDraft(projectRoot, id) {
+    const clean = cleanString(id);
+    if (!clean || !/^[a-z0-9_:-]+$/i.test(clean))
+        return null;
+    const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+    try {
+        const stored = storage.getAppBuildDraft(clean);
+        if (stored)
+            return stored;
+        const legacyPath = join(appBuildDraftDir(projectRoot), `${clean}.json`);
+        if (!existsSync(legacyPath))
+            return null;
+        const migrated = migrateLegacyAppBuildDraft(JSON.parse(readFileSync(legacyPath, 'utf-8')));
+        if (!migrated)
+            return null;
+        storage.saveAppBuildDraft(migrated);
+        return migrated;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        storage.close();
+    }
+}
+export function writeStoredAppBuildDraft(projectRoot, draft, input = {}) {
+    const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+    try {
+        storage.saveAppBuildDraft(draft, input);
+    }
+    finally {
+        storage.close();
+    }
+}
+function migrateLegacyAppBuildDraft(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const legacy = value;
+    if (legacy.version === 2)
+        return legacy;
+    if (legacy.version !== 1 || typeof legacy.id !== 'string' || typeof legacy.appId !== 'string')
+        return null;
+    const frame = (legacy.frame && typeof legacy.frame === 'object' ? legacy.frame : {});
+    const clarificationQuestions = Array.isArray(frame.clarificationQuestions)
+        ? frame.clarificationQuestions.flatMap((raw) => {
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                return [];
+            const question = raw;
+            if (typeof question.id !== 'string' || typeof question.question !== 'string')
+                return [];
+            const choices = Array.isArray(question.choices)
+                ? question.choices.map((choice, index) => typeof choice === 'string'
+                    ? { id: slugify(choice) || `choice-${index + 1}`, label: choice }
+                    : choice).filter((choice) => Boolean(choice && typeof choice === 'object' && 'id' in choice && 'label' in choice))
+                : [];
+            return [{ id: question.id, question: question.question, choices, required: question.required !== false }];
+        })
+        : [];
+    const migrated = createAppBuildDraft({
+        id: legacy.id,
+        appId: legacy.appId,
+        name: typeof legacy.name === 'string' ? legacy.name : (typeof frame.goal === 'string' ? frame.goal : legacy.appId),
+        authoringMode: legacy.authoringMode === 'manual' ? 'manual' : 'ai',
+        sourcePolicy: legacy.sourcePolicy === 'include_review_required' ? 'include_review_required' : 'governed_only',
+        frame: {
+            goal: typeof frame.goal === 'string' ? frame.goal : `Create ${legacy.appId}`,
+            decision: typeof frame.decision === 'string' ? frame.decision : undefined,
+            audience: typeof frame.audience === 'string' ? frame.audience : undefined,
+            metrics: Array.isArray(frame.metrics) ? frame.metrics.filter((item) => typeof item === 'string') : [],
+            dimensions: Array.isArray(frame.dimensions) ? frame.dimensions.filter((item) => typeof item === 'string') : [],
+            filters: Array.isArray(frame.filters) ? frame.filters.filter((item) => typeof item === 'string') : [],
+            desiredOutput: typeof frame.desiredOutput === 'string' ? frame.desiredOutput : undefined,
+            clarificationQuestions,
+        },
+        sources: Array.isArray(legacy.sources) ? legacy.sources : [],
+        pages: Array.isArray(legacy.pages) ? legacy.pages : [],
+        reviewTasks: Array.isArray(legacy.reviewTasks) ? legacy.reviewTasks : [],
+        now: typeof legacy.createdAt === 'string' ? legacy.createdAt : undefined,
+    });
+    return {
+        ...migrated,
+        revision: typeof legacy.revision === 'number' ? legacy.revision : migrated.revision,
+        updatedAt: typeof legacy.updatedAt === 'string' ? legacy.updatedAt : migrated.updatedAt,
+    };
+}
+export function deleteStoredAppBuildDraft(projectRoot, draft) {
+    const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+    let deleted;
+    try {
+        deleted = storage.deleteAppBuildDraft(draft.id);
+    }
+    finally {
+        storage.close();
+    }
+    if (!deleted)
+        throw new Error(`App Build Draft not found: ${draft.id}`);
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const recoveryId = `draft-${stamp}-${draft.id}`;
+    const recoveryDir = join(projectRoot, '.dql', 'local', 'trash', 'app-drafts', recoveryId);
+    const localArtifactsDir = join(projectRoot, '.dql', 'local', 'app-builds', draft.id);
+    const recoveryArtifactsDir = join(recoveryDir, 'artifacts');
+    let artifactsMoved = false;
+    try {
+        mkdirSync(recoveryDir, { recursive: true });
+        if (existsSync(localArtifactsDir)) {
+            renameSync(localArtifactsDir, recoveryArtifactsDir);
+            artifactsMoved = true;
+        }
+        writeFileSync(join(recoveryDir, 'recovery.json'), JSON.stringify({
+            version: 1,
+            kind: 'app_build_draft',
+            recoveryId,
+            deletedAt: new Date().toISOString(),
+            draft: deleted.draft,
+            operations: deleted.operations,
+        }, null, 2) + '\n', 'utf-8');
+    }
+    catch (error) {
+        if (artifactsMoved && existsSync(recoveryArtifactsDir)) {
+            mkdirSync(dirname(localArtifactsDir), { recursive: true });
+            renameSync(recoveryArtifactsDir, localArtifactsDir);
+        }
+        const restore = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+        try {
+            restore.restoreAppBuildDraft(deleted.draft, deleted.operations);
+        }
+        finally {
+            restore.close();
+        }
+        rmSync(recoveryDir, { recursive: true, force: true });
+        throw error;
+    }
+    return { ok: true, id: draft.id, recoveryId, recoverableUntilRestart: false };
+}
+function restoreStoredAppBuildDraft(projectRoot, recoveryId) {
+    const recoveryDir = join(projectRoot, '.dql', 'local', 'trash', 'app-drafts', recoveryId);
+    const recoveryPath = join(recoveryDir, 'recovery.json');
+    if (!existsSync(recoveryPath))
+        return { ok: false, status: 404, error: 'App recovery bundle not found.' };
+    let payload;
+    try {
+        payload = JSON.parse(readFileSync(recoveryPath, 'utf-8'));
+    }
+    catch {
+        return { ok: false, status: 400, error: 'App draft recovery bundle is invalid.' };
+    }
+    if (payload.kind !== 'app_build_draft' || !payload.draft)
+        return { ok: false, status: 400, error: 'App draft recovery bundle is invalid.' };
+    const recoveredArtifactsDir = join(recoveryDir, 'artifacts');
+    const localArtifactsDir = join(projectRoot, '.dql', 'local', 'app-builds', payload.draft.id);
+    const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+    let artifactsRestored = false;
+    try {
+        if (storage.getAppBuildDraft(payload.draft.id))
+            return { ok: false, status: 409, error: `App Build Draft already exists: ${payload.draft.id}` };
+        if (existsSync(localArtifactsDir))
+            return { ok: false, status: 409, error: `App Build Draft artifacts already exist: ${payload.draft.id}` };
+        if (existsSync(recoveredArtifactsDir)) {
+            mkdirSync(dirname(localArtifactsDir), { recursive: true });
+            renameSync(recoveredArtifactsDir, localArtifactsDir);
+            artifactsRestored = true;
+        }
+        storage.restoreAppBuildDraft(payload.draft, payload.operations ?? []);
     }
     catch (error) {
-        if (existsSync(backupAppDir) && !existsSync(loaded.appDir))
-            renameSync(backupAppDir, loaded.appDir);
+        if (artifactsRestored && existsSync(localArtifactsDir))
+            renameSync(localArtifactsDir, recoveredArtifactsDir);
         throw error;
     }
-    const paths = [relative(projectRoot, appPath), ...dashboards.map((dashboard) => relative(projectRoot, dashboard.sourcePath))];
-    return { ok: true, app: parsedApp.document, paths, removedLocalTiles, readiness };
+    finally {
+        storage.close();
+    }
+    rmSync(recoveryDir, { recursive: true, force: true });
+    return { ok: true, id: payload.draft.id, restoredPath: '.dql/local/apps.sqlite', draft: payload.draft };
 }
-export function approveAppSemanticTiles(projectRoot, appId, dashboardId, input) {
-    const loaded = loadDashboardForApp(projectRoot, appId, dashboardId);
-    if (!loaded)
-        return { ok: false, error: `Dashboard "${dashboardId}" not found in App "${appId}".` };
-    const currentFingerprint = `sha256:${createHash('sha256').update(JSON.stringify(loaded.dashboard)).digest('hex')}`;
-    if (!input.expectedDashboardFingerprint || input.expectedDashboardFingerprint !== currentFingerprint) {
-        return { ok: false, error: 'The dashboard changed after the reviewed run. Run it again before approval.' };
+export function preflightStoredAppBuildDraft(projectRoot, draft) {
+    const errors = [];
+    const blocks = collectBlockCandidates(projectRoot);
+    if (draft.state === 'clarification_required')
+        errors.push('Resolve required Build Frame clarifications before publication.');
+    if (draft.pages.length === 0)
+        errors.push('App Build Draft needs at least one page.');
+    for (const requirement of draft.requirements.filter((item) => appBuildRequirementBlocksPublication(draft, item))) {
+        const coverage = draft.coverage.find((item) => item.requirementId === requirement.id);
+        if (!coverage || coverage.status !== 'covered')
+            errors.push(`Required App question is unresolved: ${requirement.question}`);
+    }
+    for (const task of draft.reviewTasks.filter((item) => appBuildReviewTaskBlocksPublication(draft, item))) {
+        errors.push(`Review task is still open: ${task.message}`);
+    }
+    if (draft.baseApp) {
+        const base = loadAppById(projectRoot, draft.baseApp.appId);
+        if (!base || fingerprintAppDirectory(base.appDir) !== draft.baseApp.fingerprint) {
+            errors.push('The published App changed after this local draft was created. Refresh the draft before publishing.');
+        }
+    }
+    for (const page of draft.pages) {
+        const parsed = parseDashboardDocument(JSON.stringify(page), `<app-build:${draft.id}/${page.id}>`);
+        if (!parsed.document)
+            errors.push(...parsed.errors.map((error) => error.message));
+    }
+    const analysisPages = draft.pages.filter((page) => page.layout.items.some((tile) => !tile.text && !tile.aiPin));
+    const receipts = draft.previewReceipts ?? (draft.previewReceipt ? [draft.previewReceipt] : []);
+    for (const page of analysisPages) {
+        const receipt = receipts.find((candidate) => candidate.pageId === page.id);
+        if (!receipt || receipt.revision !== draft.revision)
+            errors.push(`Run a current settled preview for page ${page.metadata.title || page.id} before Project publication.`);
+    }
+    for (const source of draft.sources) {
+        if (source.kind === 'certified_block') {
+            const block = blocks.find((candidate) => candidate.id === source.sourceRef || candidate.name === source.sourceRef || candidate.path === source.sourceRef);
+            if (!block || block.status !== 'certified')
+                errors.push(`Source ${source.id} does not resolve to a current certified block.`);
+            if (block && source.sourceFingerprint && source.sourceFingerprint !== block.fingerprint)
+                errors.push(`Source ${source.id} changed after selection.`);
+        }
+        if (source.kind === 'governed_semantic' || source.kind === 'semantic_query') {
+            if (source.reviewStatus !== 'approved' || !source.snapshotId || !source.receiptId) {
+                errors.push(`Source ${source.id} requires snapshot-bound semantic approval before Project publication.`);
+            }
+        }
+        if (source.kind === 'review_block' || source.kind === 'review_dql' || source.kind === 'exploratory_sql') {
+            errors.push(`Source ${source.id} is review-required and cannot be published to the Project.`);
+        }
+        if ((source.kind === 'review_block' || source.kind === 'review_dql' || source.kind === 'exploratory_sql') && draft.sourcePolicy !== 'include_review_required') {
+            errors.push(`Source ${source.id} requires include_review_required policy.`);
+        }
     }
-    const selected = new Set(input.tileIds);
-    const semanticIds = new Set(loaded.dashboard.layout.items.filter((item) => item.semantic).map((item) => item.i));
-    const invalid = input.tileIds.filter((tileId) => !semanticIds.has(tileId));
-    if (invalid.length > 0)
-        return { ok: false, error: `Only semantic tiles can be approved here: ${invalid.join(', ')}` };
-    const reviewedAt = new Date().toISOString();
-    const dashboard = {
-        ...loaded.dashboard,
-        layout: {
-            ...loaded.dashboard.layout,
-            items: loaded.dashboard.layout.items.map((item) => {
-                if (!selected.has(item.i) || !item.semantic)
-                    return item;
-                return {
-                    ...item,
-                    semantic: { ...item.semantic, snapshotId: input.snapshotId },
-                    review: {
-                        status: 'approved',
-                        sourceFingerprint: item.semantic.definitionFingerprint,
-                        preflightReceiptId: input.runId,
-                        reviewedAt,
-                        reviewedBy: input.reviewer,
-                    },
-                    trustState: 'review_required',
-                    reviewStatus: 'review_required',
-                };
-            }),
+    const settledPageIds = new Set(receipts.filter((receipt) => receipt.revision === draft.revision).map((receipt) => receipt.pageId));
+    const readiness = appPublicationReadiness(projectRoot, draft.pages, { settledPageIds });
+    errors.push(...readiness.blockers.map((blocker) => blocker.message));
+    return Array.from(new Set(errors));
+}
+function preflightAppBuildRequestErrors(projectRoot, draft, verifyPreview) {
+    const errors = preflightStoredAppBuildDraft(projectRoot, draft);
+    const analysisPages = draft.pages
+        .map((page) => ({
+        pageId: page.id,
+        tileIds: page.layout.items.filter((tile) => !tile.text && !tile.aiPin).map((tile) => tile.i),
+    }))
+        .filter((page) => page.tileIds.length > 0);
+    const receipts = draft.previewReceipts ?? (draft.previewReceipt ? [draft.previewReceipt] : []);
+    if (analysisPages.length > 0 && !verifyPreview) {
+        errors.push('The runtime cannot verify the settled App preview receipts.');
+    }
+    for (const page of analysisPages) {
+        const receipt = receipts.find((candidate) => candidate.pageId === page.pageId);
+        if (!receipt || !verifyPreview)
+            continue;
+        const verified = verifyPreview({
+            runId: receipt.id,
+            draftId: draft.id,
+            dashboardId: page.pageId,
+            tileIds: page.tileIds,
+        });
+        if (!verified.ok
+            || verified.snapshotId !== receipt.snapshotId
+            || verified.resultFingerprint !== receipt.resultFingerprint) {
+            errors.push(verified.ok
+                ? `The saved preview receipt for ${page.pageId} no longer matches the settled run.`
+                : verified.error);
+        }
+    }
+    return Array.from(new Set(errors));
+}
+function appBuildRequirementBlocksPublication(draft, requirement) {
+    if (!requirement.required)
+        return false;
+    if (draft.authoringMode === 'manual' && draft.frame.metrics.length === 0 && requirement.measures.length === 0)
+        return false;
+    return true;
+}
+function appBuildReviewTaskBlocksPublication(draft, task) {
+    if (task.status !== 'open')
+        return false;
+    if (task.sourceId && draft.sources.some((source) => source.id === task.sourceId))
+        return true;
+    if (task.tileId && draft.pages.some((page) => page.layout.items.some((tile) => tile.i === task.tileId)))
+        return true;
+    if (task.pageId && draft.pages.some((page) => page.id === task.pageId))
+        return true;
+    // v2 AI plans previously persisted general guidance as open tasks without an
+    // attached source, page, or tile. Keep those reminders readable, but do not
+    // turn them into an unexplained hard publication gate.
+    return false;
+}
+function hasCurrentAppBuildPreflightReceipt(draft) {
+    return Boolean(draft.preflightReceipt
+        && draft.preflightReceipt.revision === draft.revision
+        && draft.preflightReceipt.proposalHash === draft.proposalHash
+        && draft.preflightReceipt.sourceFingerprint === appBuildSourceFingerprint(draft));
+}
+export function markStoredAppBuildDraftPreflighted(projectRoot, draft) {
+    const errors = preflightStoredAppBuildDraft(projectRoot, draft);
+    if (errors.length)
+        throw new Error(`App Build preflight failed: ${errors.join(' ')}`);
+    const now = new Date().toISOString();
+    const next = {
+        ...draft,
+        state: 'preflight_ready',
+        preflightReceipt: {
+            id: `app_preflight_${createHash('sha256').update(`${draft.id}:${draft.revision}:${draft.proposalHash}`).digest('hex').slice(0, 16)}`,
+            revision: draft.revision,
+            proposalHash: draft.proposalHash,
+            sourceFingerprint: appBuildSourceFingerprint(draft),
+            createdAt: now,
         },
+        updatedAt: now,
     };
-    const parsed = parseDashboardDocument(JSON.stringify(dashboard), loaded.path);
-    if (!parsed.document)
-        return { ok: false, error: parsed.errors.map((error) => error.message).join('; ') };
-    writeFileSync(loaded.path, JSON.stringify(parsed.document, null, 2) + '\n', 'utf-8');
-    return { ok: true, dashboard: parsed.document, path: relative(projectRoot, loaded.path) };
+    writeStoredAppBuildDraft(projectRoot, next, { expectedRevision: draft.revision });
+    return next;
 }
-function appPublicationReadiness(dashboards) {
-    const blockers = [];
-    let governedTiles = 0;
-    for (const dashboard of dashboards) {
-        for (const item of dashboard.layout.items) {
-            if (item.block)
-                governedTiles += 1;
-            if (item.draftAnalysis) {
-                blockers.push({
-                    dashboardId: dashboard.id,
-                    tileId: item.i,
-                    code: 'exploratory_source',
-                    message: `${dashboard.id}/${item.i} references app-scoped exploratory DQL; promote it to governed semantic logic or a certified block first.`,
-                });
+function appBuildSourceFingerprint(draft) {
+    const sources = [...draft.sources]
+        .sort((left, right) => left.id.localeCompare(right.id))
+        .map((source) => ({
+        id: source.id,
+        kind: source.kind,
+        sourceRef: source.sourceRef,
+        snapshotId: source.snapshotId,
+        sourceFingerprint: source.sourceFingerprint,
+        receiptId: source.receiptId,
+        reviewStatus: source.reviewStatus,
+    }));
+    return `sha256:${createHash('sha256').update(JSON.stringify(sources)).digest('hex')}`;
+}
+export function publishStoredAppBuildDraft(projectRoot, draft) {
+    const errors = preflightStoredAppBuildDraft(projectRoot, draft);
+    if (errors.length)
+        throw new Error(`App Build preflight failed: ${errors.join(' ')}`);
+    if (!hasCurrentAppBuildPreflightReceipt(draft)) {
+        throw new Error('App Build Draft needs a current preflight receipt before publication.');
+    }
+    const destination = resolveAppPackageDir(projectRoot, draft.appId);
+    if (!draft.baseApp && existsSync(destination))
+        throw new Error(`App already exists: ${draft.appId}`);
+    if (draft.baseApp && (!existsSync(destination) || draft.baseApp.appId !== draft.appId)) {
+        throw new Error('Published App base no longer exists at the expected path.');
+    }
+    const stage = join(projectRoot, '.dql', 'local', 'app-build-staging', `${draft.id}-${Date.now()}`);
+    const dashboardDir = join(stage, 'dashboards');
+    const owner = `${process.env.USER ?? 'owner'}@local`;
+    const domain = draft.pages[0]?.metadata.domain || 'general';
+    const name = draft.name.trim() || draft.appId;
+    const containsSemantic = draft.sources.some((source) => source.kind === 'governed_semantic' || source.kind === 'semantic_query');
+    const hasCertifiedAnalysis = draft.sources.some((source) => source.kind === 'certified_block');
+    const lifecycle = hasCertifiedAnalysis && !containsSemantic ? 'certified' : 'review';
+    const app = {
+        version: 1,
+        id: draft.appId,
+        name,
+        description: draft.frame.decision || `Governed analytical App for ${name}`,
+        visibility: 'shared',
+        publicationIntent: 'shared_project',
+        ownerDomain: domain,
+        usesDomains: [domain],
+        requiredExports: [],
+        domain,
+        audience: draft.frame.audience,
+        lifecycle,
+        owners: [owner],
+        members: [{ userId: owner, displayName: owner, roles: ['owner', 'analyst'] }],
+        roles: [
+            { id: 'owner', displayName: 'Owner' },
+            { id: 'analyst', displayName: 'Analyst' },
+            { id: 'viewer', displayName: 'Viewer' },
+        ],
+        policies: [
+            { id: 'viewers-read', domain, minClassification: 'internal', allowedRoles: ['viewer', 'analyst', 'owner'], accessLevel: 'read', enabled: true },
+            { id: 'analyst-execute', domain, minClassification: 'internal', allowedRoles: ['analyst', 'owner'], accessLevel: 'execute', enabled: true },
+            { id: 'owner-admin', domain, minClassification: 'restricted', allowedRoles: ['owner'], accessLevel: 'admin', enabled: true },
+        ],
+        rlsBindings: [],
+        schedules: [],
+        homepage: { type: 'dashboard', id: draft.pages[0].id },
+    };
+    const committedPages = draft.pages.map((page) => ({
+        ...page,
+        version: 2,
+        metadata: { ...page.metadata, visibility: 'shared', lifecycle },
+    }));
+    mkdirSync(dashboardDir, { recursive: true });
+    mkdirSync(join(stage, 'notebooks'), { recursive: true });
+    mkdirSync(join(stage, 'drafts'), { recursive: true });
+    try {
+        writeFileSync(join(stage, 'dql.app.json'), JSON.stringify(app, null, 2) + '\n', 'utf-8');
+        for (const page of committedPages) {
+            writeFileSync(join(dashboardDir, `${page.id}.dqld`), JSON.stringify(page, null, 2) + '\n', 'utf-8');
+        }
+        writeFileSync(join(stage, 'README.md'), appReadme(app, draft.frame.audience ?? '', [], committedPages[0].id), 'utf-8');
+        mkdirSync(dirname(destination), { recursive: true });
+        if (draft.baseApp) {
+            const backup = join(projectRoot, '.dql', 'local', 'app-build-staging', `${draft.id}-backup-${Date.now()}`);
+            renameSync(destination, backup);
+            try {
+                renameSync(stage, destination);
+                rmSync(backup, { recursive: true, force: true });
             }
-            if (item.semantic) {
-                governedTiles += 1;
-                if (item.review?.status !== 'approved') {
-                    blockers.push({
-                        dashboardId: dashboard.id,
-                        tileId: item.i,
-                        code: 'semantic_review',
-                        message: `${dashboard.id}/${item.i} semantic result has not been explicitly approved.`,
-                    });
-                }
-                if (!item.semantic.snapshotId || !item.review?.preflightReceiptId) {
-                    blockers.push({
-                        dashboardId: dashboard.id,
-                        tileId: item.i,
-                        code: 'semantic_preflight',
-                        message: `${dashboard.id}/${item.i} needs a snapshot-bound semantic preflight receipt.`,
-                    });
-                }
+            catch (error) {
+                if (!existsSync(destination) && existsSync(backup))
+                    renameSync(backup, destination);
+                throw error;
             }
         }
+        else {
+            renameSync(stage, destination);
+        }
     }
-    return { ready: blockers.length === 0, governedTiles, blockers };
+    catch (error) {
+        rmSync(stage, { recursive: true, force: true });
+        throw error;
+    }
+    const next = {
+        ...draft,
+        revision: draft.revision + 1,
+        state: 'project_published',
+        publishedFingerprint: fingerprintAppDirectory(destination),
+        updatedAt: new Date().toISOString(),
+        proposalHash: draft.proposalHash,
+    };
+    writeStoredAppBuildDraft(projectRoot, next, { expectedRevision: draft.revision });
+    const created = collectAppsList(projectRoot).find((entry) => entry.id === draft.appId);
+    if (!created)
+        throw new Error(`App was committed but could not be reloaded: ${draft.appId}`);
+    return {
+        ok: true,
+        app: created,
+        draft: next,
+        paths: ['dql.app.json', 'README.md', ...committedPages.map((page) => `dashboards/${page.id}.dqld`)].map((path) => `apps/${draft.appId}/${path}`),
+    };
 }
-function appAiBuildSessionDir(projectRoot) {
-    return join(projectRoot, '.dql', 'local', 'app-ai-builds');
+/** @deprecated Compatibility adapter for callers that still use the old name. */
+export function commitStoredAppBuildDraft(projectRoot, draft) {
+    return publishStoredAppBuildDraft(projectRoot, draft);
 }
 function writeAppAiBuildSession(projectRoot, session) {
     const dir = appAiBuildSessionDir(projectRoot);
@@ -2646,7 +4148,7 @@ function appAskTileContext(tile) {
         sourceEvidence: tile.sourceEvidence,
     };
 }
-function buildAppContextEnvelope(app, appDir, focus) {
+function buildAppContextEnvelope(projectRoot, app, appDir, focus) {
     const dashboards = findDashboardsForApp(appDir)
         .map((path) => loadDashboardDocument(path).document)
         .filter((document) => Boolean(document))
@@ -2671,6 +4173,7 @@ function buildAppContextEnvelope(app, appDir, focus) {
             caveats: app.caveats ?? [],
         },
         dashboards,
+        drafts: loadAppDraftContext(projectRoot, appDir),
         focus,
     };
 }
@@ -2683,6 +4186,9 @@ function filterBindingsForBlockSource(projectRoot, block) {
     const parameterSection = sectionBody(source, 'parameterPolicy');
     const bindings = Array.from(filterSection.matchAll(/^\s*([A-Za-z_][\w-]*)\s*=\s*"([^"]+)"/gm))
         .map((match) => ({ filter: match[1], binding: match[2], mode: 'predicate' }));
+    const allowedFilterBindings = matchArray(source, /allowedFilters\s*=\s*\[([^\]]*)\]/)
+        .filter((filter) => !bindings.some((binding) => binding.filter === filter))
+        .map((filter) => ({ filter, binding: filter, mode: 'predicate' }));
     const parameterNames = Array.from(parameterSection.matchAll(/^\s*([A-Za-z_][\w-]*)\s*=\s*"dynamic"/gm))
         .map((match) => match[1]);
     const parameterBindings = parameterNames.map((param) => ({
@@ -2691,7 +4197,7 @@ function filterBindingsForBlockSource(projectRoot, block) {
         mode: 'parameter',
         paramNames: [param],
     }));
-    return uniqueFilterBindings([...bindings, ...parameterBindings]);
+    return uniqueFilterBindings([...bindings, ...allowedFilterBindings, ...parameterBindings]);
 }
 function sectionBody(source, sectionName) {
     const match = new RegExp(`${sectionName}\\s*\\{([\\s\\S]*?)\\n\\s*\\}`, 'm').exec(source);
@@ -2857,7 +4363,7 @@ function promoteSharedDashboardItem(item) {
         reviewStatus,
     };
 }
-export function deleteAppPackage(projectRoot, id) {
+export function deleteAppPackage(projectRoot, id, input = {}) {
     const cleanId = cleanString(id);
     if (!cleanId || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(cleanId)) {
         return { ok: false, status: 400, error: 'A valid App id is required.' };
@@ -2865,27 +4371,130 @@ export function deleteAppPackage(projectRoot, id) {
     const loaded = loadAppById(projectRoot, cleanId);
     if (!loaded)
         return { ok: false, status: 404, error: `App "${cleanId}" not found.` };
+    const currentFingerprint = fingerprintAppDirectory(loaded.appDir);
+    if (!input.expectedFingerprint) {
+        return { ok: false, status: 409, error: 'App deletion requires the fingerprint shown during confirmation.' };
+    }
+    if (input.expectedFingerprint !== currentFingerprint) {
+        return { ok: false, status: 409, error: 'This App changed since deletion was requested. Refresh and review it again.' };
+    }
     const relativeAppDir = relative(projectRoot, loaded.appDir).replaceAll('\\', '/');
     const isProjectApp = /^apps\/[^/]+$/.test(relativeAppDir);
     const isDomainApp = /^domains\/(?:[^/]+\/)*apps\/[^/]+$/.test(relativeAppDir);
     if ((!isProjectApp && !isDomainApp) || relativeAppDir.startsWith('../')) {
         return { ok: false, status: 400, error: 'DQL refused to delete an App outside this project.' };
     }
-    const trashRoot = join(projectRoot, '.dql', 'trash', 'apps');
+    const trashRoot = join(projectRoot, '.dql', 'local', 'trash', 'apps');
     mkdirSync(trashRoot, { recursive: true });
     const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-    let trashDir = join(trashRoot, `${stamp}-${cleanId}`);
+    let recoveryId = `${stamp}-${cleanId}`;
+    let trashDir = join(trashRoot, recoveryId);
     let suffix = 2;
-    while (existsSync(trashDir))
-        trashDir = join(trashRoot, `${stamp}-${cleanId}-${suffix++}`);
-    renameSync(loaded.appDir, trashDir);
+    while (existsSync(trashDir)) {
+        recoveryId = `${stamp}-${cleanId}-${suffix++}`;
+        trashDir = join(trashRoot, recoveryId);
+    }
+    mkdirSync(trashDir, { recursive: true });
+    const packageDir = join(trashDir, 'package');
+    renameSync(loaded.appDir, packageDir);
+    let localArchive;
+    try {
+        const dbPath = defaultLocalAppsDbPath(projectRoot);
+        if (existsSync(dbPath)) {
+            const storage = new LocalAppStorage(dbPath);
+            try {
+                localArchive = storage.archiveAndDeleteAppState(cleanId);
+            }
+            finally {
+                storage.close();
+            }
+            writeFileSync(join(trashDir, 'local-state.json'), JSON.stringify(localArchive, null, 2) + '\n', 'utf-8');
+        }
+        writeFileSync(join(trashDir, 'recovery.json'), JSON.stringify({
+            version: 1,
+            recoveryId,
+            appId: cleanId,
+            originalPath: relativeAppDir,
+            appFingerprint: currentFingerprint,
+            deletedAt: new Date().toISOString(),
+        }, null, 2) + '\n', 'utf-8');
+    }
+    catch (error) {
+        if (localArchive) {
+            const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+            try {
+                storage.restoreAppState(localArchive);
+            }
+            finally {
+                storage.close();
+            }
+        }
+        if (!existsSync(loaded.appDir) && existsSync(packageDir))
+            renameSync(packageDir, loaded.appDir);
+        rmSync(trashDir, { recursive: true, force: true });
+        throw error;
+    }
+    const localRowsArchived = localArchive
+        ? Object.values(localArchive.rows).reduce((count, rows) => count + rows.length, 0)
+        : 0;
     return {
         ok: true,
         id: cleanId,
         deletedPath: relativeAppDir,
         trashPath: relative(projectRoot, trashDir).replaceAll('\\', '/'),
+        recoveryId,
+        localRowsArchived,
+        sourceControlImpact: 'delete',
     };
 }
+export function restoreAppPackage(projectRoot, recoveryId) {
+    const cleanRecoveryId = cleanString(recoveryId);
+    if (!cleanRecoveryId || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(cleanRecoveryId)) {
+        return { ok: false, status: 400, error: 'A valid recovery id is required.' };
+    }
+    const recoveryDir = join(projectRoot, '.dql', 'local', 'trash', 'apps', cleanRecoveryId);
+    const manifestPath = join(recoveryDir, 'recovery.json');
+    const packageDir = join(recoveryDir, 'package');
+    if (!existsSync(manifestPath) || !existsSync(packageDir))
+        return { ok: false, status: 404, error: 'App recovery bundle not found.' };
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    if (!manifest.appId || !manifest.originalPath || manifest.originalPath.startsWith('../')) {
+        return { ok: false, status: 400, error: 'App recovery bundle is invalid.' };
+    }
+    const destination = join(projectRoot, manifest.originalPath);
+    if (existsSync(destination))
+        return { ok: false, status: 409, error: `Cannot restore because ${manifest.originalPath} already exists.` };
+    mkdirSync(dirname(destination), { recursive: true });
+    renameSync(packageDir, destination);
+    try {
+        const localStatePath = join(recoveryDir, 'local-state.json');
+        if (existsSync(localStatePath)) {
+            const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+            try {
+                storage.restoreAppState(JSON.parse(readFileSync(localStatePath, 'utf-8')));
+            }
+            finally {
+                storage.close();
+            }
+        }
+    }
+    catch (error) {
+        renameSync(destination, packageDir);
+        throw error;
+    }
+    rmSync(recoveryDir, { recursive: true, force: true });
+    return { ok: true, id: manifest.appId, restoredPath: manifest.originalPath };
+}
+export function restoreAppRecovery(projectRoot, recoveryId) {
+    const cleanRecoveryId = cleanString(recoveryId);
+    if (!cleanRecoveryId || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(cleanRecoveryId)) {
+        return { ok: false, status: 400, error: 'A valid recovery id is required.' };
+    }
+    const draftRecovery = join(projectRoot, '.dql', 'local', 'trash', 'app-drafts', cleanRecoveryId, 'recovery.json');
+    return existsSync(draftRecovery)
+        ? restoreStoredAppBuildDraft(projectRoot, cleanRecoveryId)
+        : restoreAppPackage(projectRoot, cleanRecoveryId);
+}
 export function createAppPackage(projectRoot, input) {
     const name = cleanString(input.name);
     const domain = cleanString(input.ownerDomain) || cleanString(input.domain);
@@ -2903,16 +4512,23 @@ export function createAppPackage(projectRoot, input) {
     const audience = cleanString(input.audience);
     const subdomain = cleanString(input.subdomain);
     const groups = normalizeTags(input.groups ?? []);
-    const visibility = input.visibility === 'private' || input.visibility === 'template' ? input.visibility : 'shared';
-    const lifecycle = input.lifecycle === 'certified' || input.lifecycle === 'review' || input.lifecycle === 'deprecated'
-        ? input.lifecycle
-        : 'draft';
+    // API-013: authoring always starts as a private draft. Project visibility is
+    // available only through the publication endpoint and its live trust checks.
+    const visibility = 'private';
+    const lifecycle = 'draft';
     const tags = normalizeTags([...(input.tags ?? []), audience ? `audience:${slugify(audience)}` : '']);
     const selectedIds = Array.from(new Set((input.selectedBlockIds ?? []).map(cleanString).filter(Boolean)));
     const blocks = collectBlockCandidates(projectRoot);
     const selectedBlocks = selectedIds
         .map((blockId) => blocks.find((block) => block.id === blockId || block.name === blockId))
         .filter((block) => Boolean(block));
+    const missingBlocks = selectedIds.filter((blockId) => !selectedBlocks.some((block) => block.id === blockId || block.name === blockId));
+    if (missingBlocks.length)
+        return { ok: false, error: `Unknown block selection: ${missingBlocks.join(', ')}` };
+    const uncertifiedBlocks = selectedBlocks.filter((block) => block.status !== 'certified');
+    if (uncertifiedBlocks.length) {
+        return { ok: false, error: `Manual App creation accepts certified blocks only: ${uncertifiedBlocks.map((block) => block.name).join(', ')}` };
+    }
     const app = {
         version: 1,
         id,
@@ -2970,7 +4586,7 @@ export function createAppPackage(projectRoot, input) {
         homepage: { type: 'dashboard', id: dashboardId },
     };
     const dashboard = {
-        version: 1,
+        version: 2,
         id: dashboardId,
         metadata: {
             title: dashboardTitle,
@@ -2983,11 +4599,13 @@ export function createAppPackage(projectRoot, input) {
             lifecycle,
             tags,
         },
+        filters: dashboardFiltersForBlocks(selectedBlocks),
         layout: {
             kind: 'grid',
             cols: 12,
             rowHeight: 80,
-            items: buildDashboardItems(selectedBlocks),
+            items: buildDashboardItems(projectRoot, selectedBlocks),
+            responsive: responsiveLayoutsForDashboardItems(buildDashboardItems(projectRoot, selectedBlocks)),
         },
     };
     const paths = [
@@ -3013,7 +4631,81 @@ export function createAppPackage(projectRoot, input) {
         dashboardId,
     };
 }
-function buildDashboardItems(blocks) {
+function createAppPackageViaBuildDraft(projectRoot, input) {
+    const name = cleanString(input.name);
+    const domain = cleanString(input.ownerDomain) || cleanString(input.domain);
+    if (!name)
+        return { ok: false, error: 'name is required' };
+    if (!domain)
+        return { ok: false, error: 'domain is required' };
+    const appId = suggestAppId(name);
+    if (existsSync(resolveAppPackageDir(projectRoot, appId)))
+        return { ok: false, error: `App already exists: ${appId}` };
+    const selectedIds = unique((input.selectedBlockIds ?? []).map(cleanString).filter(Boolean));
+    const blocks = collectBlockCandidates(projectRoot);
+    const selectedBlocks = selectedIds
+        .map((id) => blocks.find((block) => block.id === id || block.name === id))
+        .filter((block) => Boolean(block));
+    const missing = selectedIds.filter((id) => !selectedBlocks.some((block) => block.id === id || block.name === id));
+    if (missing.length)
+        return { ok: false, error: `Unknown block selection: ${missing.join(', ')}` };
+    const uncertified = selectedBlocks.filter((block) => block.status !== 'certified');
+    if (uncertified.length)
+        return { ok: false, error: `Manual App creation accepts certified blocks only: ${uncertified.map((block) => block.name).join(', ')}` };
+    const draft = createStoredAppBuildDraft(projectRoot, {
+        appId,
+        name,
+        goal: name,
+        audience: cleanString(input.audience),
+        domain,
+        authoringMode: 'manual',
+        sourcePolicy: 'governed_only',
+    });
+    const items = buildDashboardItems(projectRoot, selectedBlocks);
+    const page = {
+        ...draft.pages[0],
+        id: slugify(cleanString(input.dashboardTitle) || 'Overview') || 'overview',
+        metadata: {
+            ...draft.pages[0].metadata,
+            title: cleanString(input.dashboardTitle) || 'Overview',
+            description: cleanString(input.purpose) || `Starter dashboard for ${name}`,
+            domain,
+            audience: cleanString(input.audience) || undefined,
+        },
+        filters: dashboardFiltersForBlocks(selectedBlocks),
+        layout: {
+            ...draft.pages[0].layout,
+            items,
+            responsive: responsiveLayoutsForDashboardItems(items),
+        },
+    };
+    const operations = [
+        ...(page.id === draft.pages[0].id ? [] : [{ type: 'remove_page', pageId: draft.pages[0].id }]),
+        { type: 'upsert_page', page },
+        ...selectedBlocks.map((block) => ({
+            type: 'upsert_source',
+            source: {
+                id: `block:${block.id}`,
+                kind: 'certified_block',
+                sourceRef: block.id,
+                sourceFingerprint: block.fingerprint,
+                trustState: 'certified',
+                reviewStatus: 'not_required',
+            },
+        })),
+    ];
+    const revised = applyAppBuildDraftOperations(draft, draft.revision, operations);
+    writeStoredAppBuildDraft(projectRoot, revised, { expectedRevision: draft.revision, operations });
+    try {
+        const preflighted = markStoredAppBuildDraftPreflighted(projectRoot, revised);
+        const committed = publishStoredAppBuildDraft(projectRoot, preflighted);
+        return { ok: true, app: committed.app, paths: committed.paths, dashboardId: page.id };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+function buildDashboardItems(projectRoot, blocks) {
     let x = 0;
     let y = 0;
     let rowH = 0;
@@ -3027,13 +4719,51 @@ function buildDashboardItems(blocks) {
             y += rowH || size.h;
             rowH = 0;
         }
-        const item = dashboardItemForBlock(block, chartType, x, y, size, index);
+        const item = dashboardItemForBlock(block, chartType, x, y, size, index, filterBindingsForBlockSource(projectRoot, block));
         x += size.w;
         rowH = Math.max(rowH, size.h);
         return item;
     });
 }
-function dashboardItemForBlock(block, chartType, x, y, size, index) {
+function dashboardFiltersForBlocks(blocks) {
+    return unique(blocks.flatMap((block) => block.filterIds)).map((id) => ({
+        id,
+        label: id.replace(/[_-]+/g, ' ').replace(/\b\w/g, (character) => character.toUpperCase()),
+        type: /(?:^|_)(?:top_n|limit|count|amount|number|minimum|maximum)(?:_|$)/i.test(id)
+            ? 'number'
+            : /(?:date|time|period|month|quarter|year)/i.test(id)
+                ? 'date'
+                : /(?:^|_)(?:name|id|search|email)(?:_|$)/i.test(id)
+                    ? 'search'
+                    : 'select',
+        bindsTo: id,
+    }));
+}
+function responsiveLayoutsForDashboardItems(items) {
+    const project = (cols) => {
+        let x = 0;
+        let y = 0;
+        let rowHeight = 0;
+        return [...items].sort((left, right) => left.y - right.y || left.x - right.x).map((item) => {
+            const width = cols === 1 ? 1 : Math.min(cols, Math.max(2, Math.ceil(item.w / 2)));
+            if (x + width > cols) {
+                x = 0;
+                y += rowHeight || item.h;
+                rowHeight = 0;
+            }
+            const next = { ...item, x, y, w: width };
+            x += width;
+            rowHeight = Math.max(rowHeight, item.h);
+            return next;
+        });
+    };
+    return {
+        wide: { kind: 'grid', cols: 12, rowHeight: 80, items },
+        medium: { kind: 'grid', cols: 6, rowHeight: 80, items: project(6) },
+        narrow: { kind: 'grid', cols: 1, rowHeight: 80, items: project(1) },
+    };
+}
+function dashboardItemForBlock(block, chartType, x, y, size, index, filterBindings = []) {
     return {
         i: slugify(block.name) || `tile-${index + 1}`,
         x,
@@ -3043,7 +4773,12 @@ function dashboardItemForBlock(block, chartType, x, y, size, index) {
         block: { blockId: block.name },
         viz: { type: chartType },
         display: displayForBlockHint(block, chartType),
+        sourceClass: 'certified_block',
+        review: { status: 'not_required', sourceFingerprint: block.fingerprint },
+        trustState: 'certified',
+        reviewStatus: 'certified',
         title: block.name,
+        ...(filterBindings.length ? { filterBindings } : {}),
     };
 }
 function vizRank(chartType) {
@@ -3209,8 +4944,13 @@ function visualizationFitsResult(viz, columns, rows) {
     const hasTime = columns.some((column) => /\b(date|time|week|month|quarter|year|season|period)\b/i.test(column.name));
     if (viz === 'table' || viz === 'pivot' || viz === 'text' || viz === 'heading')
         return true;
+    // An empty row sample means "cannot judge", not "does not fit". Returning
+    // false here silently rewrote every requested visualization to `table`
+    // whenever no rows were supplied — which is the normal case when a tile is
+    // configured before its first run, so authored and AI-chosen charts were
+    // routinely discarded. Keep the request; the renderer copes with the shape.
     if (rows.length === 0)
-        return false;
+        return true;
     if (viz === 'single_value' || viz === 'kpi' || viz === 'gauge')
         return rows.length === 1 && measures.length >= 1;
     if (viz === 'line' || viz === 'area')
@@ -3415,7 +5155,12 @@ function collectBlockCandidates(projectRoot) {
                     seen.add(filePath);
                     const source = readFileSync(filePath, 'utf-8');
                     const stat = statSyncSafe(filePath);
-                    const name = matchString(source, /block\s+"([^"]+)"/) ?? entry.name.replace(/\.dql$/, '');
+                    const name = matchString(source, /block\s+"([^"]+)"/);
+                    // The App source picker is an executable-block catalog. Domain terms,
+                    // skills, and other .dql context remain available to planning, but they
+                    // must not appear as addable dashboard data sources.
+                    if (!name)
+                        continue;
                     const tags = matchArray(source, /tags\s*=\s*\[([^\]]*)\]/);
                     blocks.push({
                         id: name,
@@ -3425,10 +5170,13 @@ function collectBlockCandidates(projectRoot) {
                         owner: matchString(source, /owner\s*=\s*"([^"]+)"/),
                         tags,
                         path: relative(projectRoot, filePath).replaceAll('\\', '/'),
+                        fingerprint: `sha256:${createHash('sha256').update(source).digest('hex')}`,
                         lastModified: stat?.mtime.toISOString() ?? new Date(0).toISOString(),
                         description: matchString(source, /description\s*=\s*"((?:[^"\\]|\\.)*)"/) ?? '',
                         llmContext: matchString(source, /llmContext\s*=\s*"((?:[^"\\]|\\.)*)"/),
                         chartType: matchString(source, /chart\s*=\s*"([^"]+)"/) ?? matchString(source, /chart\.(\w+)\s*\(/) ?? undefined,
+                        filterIds: declaredAppFilterIds(source),
+                        dimensionIds: declaredAppDimensionIds(source),
                         score: 0,
                         reasons: [],
                     });
@@ -3441,7 +5189,31 @@ function collectBlockCandidates(projectRoot) {
     };
     scanDir(join(projectRoot, 'blocks'));
     scanDir(join(projectRoot, 'domains'));
-    return blocks;
+    const byId = new Map();
+    for (const block of blocks) {
+        const current = byId.get(block.id);
+        if (!current) {
+            byId.set(block.id, block);
+            continue;
+        }
+        const blockRank = (block.status === 'certified' ? 4 : 0) + (block.path.startsWith('domains/') ? 2 : 0);
+        const currentRank = (current.status === 'certified' ? 4 : 0) + (current.path.startsWith('domains/') ? 2 : 0);
+        if (blockRank > currentRank || (blockRank === currentRank && block.lastModified > current.lastModified))
+            byId.set(block.id, block);
+    }
+    return Array.from(byId.values());
+}
+function declaredAppFilterIds(source) {
+    const filterSection = sectionBody(source, 'filterBindings');
+    const parameterSection = sectionBody(source, 'parameterPolicy');
+    return unique([
+        ...matchArray(source, /allowedFilters\s*=\s*\[([^\]]*)\]/),
+        ...Array.from(filterSection.matchAll(/^\s*([A-Za-z_][\w-]*)\s*=\s*"[^"]+"/gm)).map((match) => match[1]),
+        ...Array.from(parameterSection.matchAll(/^\s*([A-Za-z_][\w-]*)\s*=\s*"(?:dynamic|optional|business)"/gm)).map((match) => match[1]),
+    ]);
+}
+function declaredAppDimensionIds(source) {
+    return unique(matchArray(source, /dimensions\s*=\s*\[([^\]]*)\]/));
 }
 function readdirSyncSafe(dir) {
     try {
@@ -4111,10 +5883,13 @@ function resolveSelectedBlock(projectRoot, selected, sourceBlockId) {
                 owner: matchString(source, /owner\s*=\s*"([^"]+)"/),
                 tags: matchArray(source, /tags\s*=\s*\[([^\]]*)\]/),
                 path: normalizedPath,
+                fingerprint: `sha256:${createHash('sha256').update(source).digest('hex')}`,
                 lastModified: statSyncSafe(join(projectRoot, normalizedPath))?.mtime.toISOString() ?? new Date(0).toISOString(),
                 description: matchString(source, /description\s*=\s*"((?:[^"\\]|\\.)*)"/) ?? '',
                 llmContext: matchString(source, /llmContext\s*=\s*"((?:[^"\\]|\\.)*)"/),
                 chartType: matchString(source, /chart\s*=\s*"([^"]+)"/) ?? undefined,
+                filterIds: declaredAppFilterIds(source),
+                dimensionIds: declaredAppDimensionIds(source),
                 score: 0,
                 reasons: [],
             };
@@ -5051,14 +6826,29 @@ function uniqueAppPageId(base, existingIds) {
  * deliberately stricter than the metadata snapshot: page, notebook, draft, and
  * App-document edits all invalidate approval before the atomic directory swap.
  */
+/**
+ * Fingerprint the parts of an App package a write can actually conflict with:
+ * the manifest and the dashboard documents.
+ *
+ * Hashing every byte under the App directory made the guard far too sensitive —
+ * a notebook run output, a README edit, or an attached notebook would
+ * invalidate a page proposal that could not possibly conflict with them, and
+ * the commit failed with an unexplained 409.
+ */
 function fingerprintAppDirectory(appDir) {
     const files = [];
     const visit = (directory) => {
         for (const entry of readdirSync(directory, { withFileTypes: true })) {
             const absolutePath = join(directory, entry.name);
-            if (entry.isDirectory())
+            if (entry.isDirectory()) {
+                // Only `dashboards/` participates; notebooks, drafts and generated prose do not.
+                if (directory === appDir && entry.name !== 'dashboards')
+                    continue;
                 visit(absolutePath);
+            }
             else if (entry.isFile() || entry.isSymbolicLink()) {
+                if (directory === appDir && entry.name !== 'dql.app.json')
+                    continue;
                 files.push({ path: absolutePath, symbolicLink: entry.isSymbolicLink() });
             }
         }
@@ -5679,6 +7469,32 @@ function readNotebookRunSnapshot(absNotebookPath) {
 function normalizeNotebookRole(value) {
     return value === 'source' || value === 'analysis' ? value : 'supporting';
 }
+/** Longest draft SQL carried into a prompt; drafts are context, not the answer. */
+const APP_DRAFT_SQL_PROMPT_LIMIT = 1200;
+/**
+ * The app's drafts, with enough of each to be usable as context.
+ *
+ * `listAppDrafts` reads the same files for the Drafts panel but keeps only a
+ * name and review status, which is why the drafts were visible in the UI and
+ * invisible to the copilot even once the envelope carried them.
+ */
+function loadAppDraftContext(projectRoot, appDir) {
+    return scanFiles(join(appDir, 'drafts'), '.dql').map((file) => {
+        const source = readFileSync(file, 'utf-8');
+        const path = relative(projectRoot, file).replaceAll('\\', '/');
+        const query = matchString(source, /query\s*=\s*"""([\s\S]*?)"""/)?.trim();
+        return {
+            name: matchString(source, /block\s+"([^"]+)"/) ?? titleFromPath(path),
+            path,
+            status: matchString(source, /status\s*=\s*"([^"]+)"/) ?? 'review',
+            description: matchString(source, /description\s*=\s*"([^"]*)"/) ?? undefined,
+            question: matchString(source, /question\s*=\s*"([^"]*)"/) ?? undefined,
+            sql: query
+                ? query.length > APP_DRAFT_SQL_PROMPT_LIMIT ? `${query.slice(0, APP_DRAFT_SQL_PROMPT_LIMIT)}\n-- …truncated` : query
+                : undefined,
+        };
+    }).sort((a, b) => a.name.localeCompare(b.name));
+}
 function listAppDrafts(projectRoot, appDir) {
     return scanFiles(join(appDir, 'drafts'), '.dql').map((file) => {
         const source = readFileSync(file, 'utf-8');
@@ -5788,6 +7604,7 @@ function loadDashboardForApp(projectRoot, appId, dashboardId) {
     }
     return null;
 }
+export { writeDashboard as writeDashboardForTest };
 function writeDashboard(projectRoot, appId, dashboardId, payload) {
     // Validate against the dashboard schema before touching disk.
     const { document, errors } = parseDashboardDocument(JSON.stringify(payload), '<incoming>');
@@ -5803,6 +7620,22 @@ function writeDashboard(projectRoot, appId, dashboardId, payload) {
         return { ok: false, error: `App "${appId}" not found` };
     const appDir = loaded.appDir;
     const dashboardPath = join(appDir, 'dashboards', `${dashboardId}.dqld`);
+    // Dashboard ids are unique only within an App — `overview` is a common name —
+    // so a caller holding one App's document and another App's id would silently
+    // overwrite the wrong file. Only accept a title change to an existing page,
+    // never a wholesale replacement of a different App's page of the same name.
+    if (existsSync(dashboardPath)) {
+        const existing = loadDashboardDocument(dashboardPath).document;
+        const incomingBlocks = new Set(document.layout.items.map((item) => item.i));
+        const existingBlocks = new Set((existing?.layout.items ?? []).map((item) => item.i));
+        const overlap = [...incomingBlocks].filter((tileId) => existingBlocks.has(tileId)).length;
+        if (existingBlocks.size > 0 && incomingBlocks.size > 0 && overlap === 0) {
+            return {
+                ok: false,
+                error: `Refusing to overwrite "${appId}/${dashboardId}": the incoming page shares no tiles with the one on disk, so it is very likely a different App's page of the same name.`,
+            };
+        }
+    }
     mkdirSync(dirname(dashboardPath), { recursive: true });
     writeFileSync(dashboardPath, JSON.stringify(document, null, 2) + '\n', 'utf-8');
     return { ok: true, path: dashboardPath };