@revoengine/cli 1.0.10 → 1.0.11

package/dist/src/resource-syncs/database-view-sync.js

@@ -0,0 +1,1317 @@
+import path from 'node:path';
+import { hashStable, readComponentLock, writeComponentLock } from "../component-lock.js";
+import { readConfiguredResourceMetadataStableKey, sanitizeUserMetadata } from "../resource-metadata.js";
+import { readJsonFile, sanitizeSegment } from "../utils.js";
+import { findManifestFiles, isRecord, localTargetPath, requireProjectLayout, stableKeySuffix, toPortableRelativePath, unwrapData, writePulledManifest, } from "./util.js";
+export const DATABASE_VIEWS_DIRECTORY = 'DatabaseViews';
+export const DATABASE_VIEW_MANIFEST_FILE = 'database-view.json';
+function canonicalValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => canonicalValue(item));
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.keys(value)
+        .sort((left, right) => left.localeCompare(right))
+        .map((key) => [key, canonicalValue(value[key])]));
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function viewIdOf(record) {
+    return String(record.databaseViewId || record.id || '');
+}
+function databaseIdOf(record) {
+    return String(record.databaseId || record.id || '');
+}
+function stableKeyOf(record, stableKeyName) {
+    return readConfiguredResourceMetadataStableKey(record, stableKeyName);
+}
+function metadataFromRecord(record, stableKeyName, stableKey) {
+    return canonicalValue({
+        ...sanitizeUserMetadata(record.resourceMetadata),
+        ...sanitizeUserMetadata(record.metaData),
+        ...sanitizeUserMetadata(record.metadata),
+        [stableKeyName]: stableKey,
+    });
+}
+function databaseViewManifestPath(workspaceRoot, manifest) {
+    const category = typeof manifest.category === 'string' && manifest.category.trim()
+        ? sanitizeSegment(manifest.category)
+        : 'Uncategorized';
+    return path.join(workspaceRoot, DATABASE_VIEWS_DIRECTORY, category, `${sanitizeSegment(manifest.name)}-${stableKeySuffix(manifest.stableKey)}`, DATABASE_VIEW_MANIFEST_FILE);
+}
+function readWorkspaceDatabaseViews(cwd) {
+    const { workspaceRoot } = requireProjectLayout(cwd, 'Database View');
+    return findManifestFiles(path.join(workspaceRoot, DATABASE_VIEWS_DIRECTORY), DATABASE_VIEW_MANIFEST_FILE)
+        .map((manifestPath) => ({
+        manifestPath,
+        manifest: readJsonFile(manifestPath),
+    }));
+}
+function validColumn(value) {
+    return isRecord(value)
+        && isNonEmptyString(value.stableKey)
+        && isNonEmptyString(value.name)
+        && isNonEmptyString(value.type)
+        && typeof value.isArray === 'boolean'
+        && Object.keys(value).every((key) => ['stableKey', 'name', 'type', 'isArray'].includes(key));
+}
+function validSource(value) {
+    return isRecord(value)
+        && isNonEmptyString(value.databaseStableKey)
+        && isNonEmptyString(value.name)
+        && Array.isArray(value.columns)
+        && value.columns.every(validColumn)
+        && Object.keys(value).every((key) => ['databaseStableKey', 'name', 'columns'].includes(key));
+}
+function validRawSqlSource(value) {
+    return isRecord(value)
+        && isNonEmptyString(value.databaseStableKey)
+        && isNonEmptyString(value.name)
+        && Object.keys(value).every((key) => ['databaseStableKey', 'name'].includes(key));
+}
+function validOutput(value) {
+    return isRecord(value)
+        && isNonEmptyString(value.name)
+        && isNonEmptyString(value.type)
+        && typeof value.isArray === 'boolean'
+        && Object.keys(value).every((key) => ['name', 'type', 'isArray'].includes(key));
+}
+function validManifest(value, stableKeyName) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (!Object.keys(value).every((key) => [
+        'kind', 'stableKey', 'name', 'category', 'description', 'metadata', 'type', 'definitionMode', 'request', 'rawQuery', 'sources', 'output', 'uniqueKey', 'indexes',
+    ].includes(key))) {
+        return false;
+    }
+    if (value.kind !== 'database-view'
+        || !isNonEmptyString(value.stableKey)
+        || !isNonEmptyString(value.name)
+        || (value.type !== 'VIEW' && value.type !== 'MATERIALIZED_VIEW')
+        || (value.definitionMode !== 'STRUCTURED' && value.definitionMode !== 'RAW_SQL')
+        || !isRecord(value.metadata)
+        || !Array.isArray(value.sources)
+        || !Array.isArray(value.output)
+        || !value.output.every(validOutput)) {
+        return false;
+    }
+    if ((value.definitionMode === 'STRUCTURED' && (!isRecord(value.request) || !value.sources.every(validSource) || value.rawQuery !== undefined))
+        || (value.definitionMode === 'RAW_SQL' && (!isNonEmptyString(value.rawQuery) || !value.sources.every(validRawSqlSource) || value.request !== undefined))) {
+        return false;
+    }
+    if (value.category !== undefined && value.category !== null && typeof value.category !== 'string') {
+        return false;
+    }
+    if (value.description !== undefined && typeof value.description !== 'string') {
+        return false;
+    }
+    if (value.type === 'VIEW' && (value.uniqueKey !== undefined || value.indexes !== undefined)) {
+        return false;
+    }
+    if (value.type === 'MATERIALIZED_VIEW') {
+        if (!Array.isArray(value.uniqueKey)
+            || value.uniqueKey.length === 0
+            || !value.uniqueKey.every(isNonEmptyString)) {
+            return false;
+        }
+        if (value.indexes !== undefined && (!Array.isArray(value.indexes)
+            || !value.indexes.every((index) => (isRecord(index)
+                && Array.isArray(index.columns)
+                && index.columns.length > 0
+                && index.columns.every(isNonEmptyString)
+                && (index.unique === undefined || typeof index.unique === 'boolean')
+                && Object.keys(index).every((key) => key === 'columns' || key === 'unique'))))) {
+            return false;
+        }
+    }
+    return stableKeyOf(value, stableKeyName) === value.stableKey;
+}
+export function hashPortableDatabaseView(manifest) {
+    return hashStable(canonicalValue({
+        ...manifest,
+        sources: [...manifest.sources].sort((left, right) => (left.databaseStableKey.localeCompare(right.databaseStableKey)
+            || left.name.localeCompare(right.name))),
+    }));
+}
+export function hashDatabaseViewManifest(manifest) {
+    return hashPortableDatabaseView(manifest);
+}
+function exclusionReason(record) {
+    if (record.deletedAt || record.deletedBy) {
+        return 'deleted Database View is excluded';
+    }
+    if (record.definitionMode !== 'STRUCTURED' && record.definitionMode !== 'RAW_SQL') {
+        return `definitionMode ${String(record.definitionMode || 'unknown')} is unsupported`;
+    }
+    if (record.type !== 'VIEW' && record.type !== 'MATERIALIZED_VIEW') {
+        return `type ${String(record.type || 'unknown')} is unsupported; only STRUCTURED VIEW or MATERIALIZED_VIEW is migrated`;
+    }
+    return undefined;
+}
+function sourceInventory(databases, stableKeyName) {
+    const byId = new Map();
+    const stableKeys = new Map();
+    const duplicateStableKeys = new Set();
+    for (const database of databases) {
+        const id = databaseIdOf(database);
+        if (!id) {
+            continue;
+        }
+        byId.set(id, database);
+        const stableKey = stableKeyOf(database, stableKeyName);
+        if (!stableKey) {
+            continue;
+        }
+        const previousId = stableKeys.get(stableKey);
+        if (previousId && previousId !== id) {
+            duplicateStableKeys.add(stableKey);
+            continue;
+        }
+        stableKeys.set(stableKey, id);
+    }
+    return { byId, duplicateStableKeys };
+}
+function sourceColumns(input) {
+    const databaseName = String(input.database.name || databaseIdOf(input.database));
+    if (!Array.isArray(input.dependencyFields)) {
+        return `Database View source "${databaseName}" does not expose structured field dependencies`;
+    }
+    const definitions = Array.isArray(input.database.definition) ? input.database.definition.filter(isRecord) : [];
+    const byName = new Map(definitions.map((definition) => [String(definition.name || ''), definition]));
+    const columns = [];
+    const seenStableKeys = new Set();
+    for (const fieldName of input.dependencyFields) {
+        if (!isNonEmptyString(fieldName)) {
+            return `Database View source "${databaseName}" has an invalid referenced column`;
+        }
+        const definition = byName.get(fieldName);
+        if (!definition) {
+            return `Database View source "${databaseName}" is missing referenced column "${fieldName}"`;
+        }
+        const stableKey = stableKeyOf(definition, input.stableKeyName);
+        if (!stableKey) {
+            return `Database View source column "${databaseName}.${fieldName}" is missing ${input.stableKeyName}`;
+        }
+        if (seenStableKeys.has(stableKey)) {
+            return `Database View source "${databaseName}" has duplicate column stableKey "${stableKey}"`;
+        }
+        seenStableKeys.add(stableKey);
+        if (!isNonEmptyString(definition.type)) {
+            return `Database View source column "${databaseName}.${fieldName}" has no type`;
+        }
+        columns.push({ stableKey, name: fieldName, type: definition.type, isArray: definition.isArray === true });
+    }
+    return columns;
+}
+function outputSignature(record) {
+    const name = String(record.name || viewIdOf(record) || 'unknown');
+    if (!Array.isArray(record.definition) || record.definition.length === 0) {
+        return `Database View "${name}" has no output definition`;
+    }
+    const output = [];
+    const names = new Set();
+    for (const field of record.definition) {
+        if (!isRecord(field) || !isNonEmptyString(field.name) || !isNonEmptyString(field.type)) {
+            return `Database View "${name}" has an invalid output definition`;
+        }
+        if (names.has(field.name)) {
+            return `Database View "${name}" has duplicate output column "${field.name}"`;
+        }
+        names.add(field.name);
+        output.push({ name: field.name, type: field.type, isArray: field.isArray === true });
+    }
+    return output;
+}
+function materializedConfiguration(record, output) {
+    if (!Array.isArray(record.uniqueKey) || record.uniqueKey.length === 0 || !record.uniqueKey.every(isNonEmptyString)) {
+        return `Database View "${String(record.name || viewIdOf(record) || 'unknown')}" has no valid materialized uniqueKey`;
+    }
+    const outputNames = new Set(output.map((field) => field.name));
+    if (record.uniqueKey.some((column) => !outputNames.has(column))) {
+        return `Database View "${String(record.name || viewIdOf(record) || 'unknown')}" uniqueKey references an unknown output column`;
+    }
+    const indexes = [];
+    if (record.indexes !== undefined && !Array.isArray(record.indexes)) {
+        return `Database View "${String(record.name || viewIdOf(record) || 'unknown')}" has an invalid materialized index`;
+    }
+    for (const index of record.indexes || []) {
+        if (!isRecord(index) || !Array.isArray(index.columns) || index.columns.length === 0) {
+            return `Database View "${String(record.name || viewIdOf(record) || 'unknown')}" has an invalid materialized index`;
+        }
+        const columns = [];
+        for (const column of index.columns) {
+            const name = isNonEmptyString(column)
+                ? column
+                : isRecord(column) && isNonEmptyString(column.name)
+                    ? column.name
+                    : undefined;
+            if (!name) {
+                return `Database View "${String(record.name || viewIdOf(record) || 'unknown')}" has an invalid materialized index`;
+            }
+            columns.push(name);
+        }
+        if (columns.some((column) => !outputNames.has(column))) {
+            return `Database View "${String(record.name || viewIdOf(record) || 'unknown')}" index references an unknown output column`;
+        }
+        if (index.unique !== undefined && typeof index.unique !== 'boolean') {
+            return `Database View "${String(record.name || viewIdOf(record) || 'unknown')}" has an invalid materialized index unique flag`;
+        }
+        indexes.push({ columns, ...(index.unique === true ? { unique: true } : {}) });
+    }
+    return {
+        uniqueKey: [...record.uniqueKey],
+        indexes: indexes.sort((left, right) => hashStable(canonicalValue(left)).localeCompare(hashStable(canonicalValue(right)))),
+    };
+}
+function rawSqlSources(input) {
+    if (!Array.isArray(input.record.sourceDatabaseIds)) {
+        return `Database View "${String(input.record.name || viewIdOf(input.record) || 'unknown')}" does not expose raw SQL source Database Schemas`;
+    }
+    const sources = [];
+    for (const sourceId of [...new Set(input.record.sourceDatabaseIds)]) {
+        const database = input.inventory.byId.get(sourceId);
+        if (!database) {
+            return `Database View "${String(input.record.name || viewIdOf(input.record) || 'unknown')}" source Database Schema "${sourceId}" is unavailable`;
+        }
+        const databaseStableKey = stableKeyOf(database, input.stableKeyName);
+        if (!databaseStableKey) {
+            return `Database View source Database Schema "${String(database.name || sourceId)}" is missing ${input.stableKeyName}`;
+        }
+        if (input.inventory.duplicateStableKeys.has(databaseStableKey)) {
+            return `Database View source Database Schema "${String(database.name || sourceId)}" has duplicate stableKey "${databaseStableKey}"`;
+        }
+        if (!isNonEmptyString(database.name)) {
+            return `Database View source Database Schema "${sourceId}" has no logical name`;
+        }
+        sources.push({ databaseStableKey, name: database.name });
+    }
+    return sources.sort((left, right) => (left.databaseStableKey.localeCompare(right.databaseStableKey)
+        || left.name.localeCompare(right.name)));
+}
+function manifestFromRecord(input) {
+    const { record, stableKey, stableKeyName, inventory } = input;
+    if (!isNonEmptyString(record.name)) {
+        return `Database View "${String(record.name || viewIdOf(record) || stableKey)}" has no valid name`;
+    }
+    const output = outputSignature(record);
+    if (typeof output === 'string') {
+        return output;
+    }
+    const materialized = record.type === 'MATERIALIZED_VIEW' ? materializedConfiguration(record, output) : undefined;
+    if (typeof materialized === 'string') {
+        return materialized;
+    }
+    const base = {
+        kind: 'database-view',
+        stableKey,
+        name: record.name,
+        ...(record.category === undefined ? {} : { category: record.category }),
+        ...(typeof record.desc === 'string' ? { description: record.desc } : typeof record.description === 'string' ? { description: record.description } : {}),
+        metadata: metadataFromRecord(record, stableKeyName, stableKey),
+        type: record.type,
+        output,
+        ...(materialized ? materialized : {}),
+    };
+    if (record.definitionMode === 'RAW_SQL') {
+        if (!isNonEmptyString(record.rawQuery)) {
+            return `Database View "${record.name}" has no valid raw SQL query`;
+        }
+        const sources = rawSqlSources({ record, stableKeyName, inventory });
+        if (typeof sources === 'string') {
+            return sources;
+        }
+        return {
+            ...base,
+            definitionMode: 'RAW_SQL',
+            rawQuery: record.rawQuery,
+            sources,
+        };
+    }
+    if (!isRecord(record.request)) {
+        return `Database View "${String(record.name || viewIdOf(record) || stableKey)}" has no valid structured request`;
+    }
+    if (!Array.isArray(record.sourceDatabaseIds) || record.sourceDatabaseIds.length === 0) {
+        return `Database View "${record.name}" has no source Database Schemas`;
+    }
+    const dependencies = isRecord(record.sourceFieldDependencies) ? record.sourceFieldDependencies : {};
+    const sources = [];
+    for (const sourceId of [...new Set(record.sourceDatabaseIds)]) {
+        const database = inventory.byId.get(sourceId);
+        if (!database) {
+            return `Database View "${record.name}" source Database Schema "${sourceId}" is unavailable`;
+        }
+        const databaseStableKey = stableKeyOf(database, stableKeyName);
+        if (!databaseStableKey) {
+            return `Database View source Database Schema "${String(database.name || sourceId)}" is missing ${stableKeyName}`;
+        }
+        if (inventory.duplicateStableKeys.has(databaseStableKey)) {
+            return `Database View source Database Schema "${String(database.name || sourceId)}" has duplicate stableKey "${databaseStableKey}"`;
+        }
+        if (!isNonEmptyString(database.name)) {
+            return `Database View source Database Schema "${sourceId}" has no logical name`;
+        }
+        const columns = sourceColumns({ database, dependencyFields: dependencies[sourceId], stableKeyName });
+        if (typeof columns === 'string') {
+            return columns;
+        }
+        sources.push({ databaseStableKey, name: database.name, columns });
+    }
+    return {
+        ...base,
+        definitionMode: 'STRUCTURED',
+        request: canonicalValue(record.request),
+        sources,
+    };
+}
+function warningKey(record, stableKey) {
+    return stableKey || String(record.name || viewIdOf(record) || 'unknown Database View');
+}
+function emptyPlanCounts() {
+    return {
+        clean: 0,
+        create: 0,
+        'safe-update': 0,
+        'remote-changed': 0,
+        conflict: 0,
+        'missing-lock': 0,
+        orphan: 0,
+        collision: 0,
+        skipped: 0,
+    };
+}
+function diffManifestFields(desired, current) {
+    const fields = [
+        ['name', desired.name, current.name],
+        ['category', desired.category ?? null, current.category ?? null],
+        ['description', desired.description ?? '', current.description ?? ''],
+        ['metadata', desired.metadata, current.metadata],
+        ['definitionMode', desired.definitionMode, current.definitionMode],
+        ['request', desired.definitionMode === 'STRUCTURED' ? desired.request : null, current.definitionMode === 'STRUCTURED' ? current.request : null],
+        ['rawQuery', desired.definitionMode === 'RAW_SQL' ? desired.rawQuery : null, current.definitionMode === 'RAW_SQL' ? current.rawQuery : null],
+        ['sources', desired.sources, current.sources],
+        ['output', desired.output, current.output],
+    ];
+    return fields
+        .filter(([, expected, actual]) => hashStable(canonicalValue(expected)) !== hashStable(canonicalValue(actual)))
+        .map(([field]) => field);
+}
+function materializedPlanDetails(input) {
+    if (input.manifest.type !== 'MATERIALIZED_VIEW') {
+        return {};
+    }
+    const scheduleDependencies = input.databaseViewId
+        ? input.schedules
+            .filter((schedule) => {
+            if (schedule.active !== true || schedule.targetType !== 'PLATFORM_OPERATION') {
+                return false;
+            }
+            const config = schedule.targetConfig;
+            return isRecord(config)
+                && config.kind === 'refresh_materialized_view'
+                && schedule.targetId === input.databaseViewId;
+        })
+            .map((schedule) => String(schedule.name || schedule.scheduleId || schedule.id || 'unnamed refresh schedule'))
+            .sort((left, right) => left.localeCompare(right))
+        : [];
+    return {
+        risks: ['materialization/rebuild can consume the shared databases and databaseSize quota; deploy in a reviewed maintenance window'],
+        ...(scheduleDependencies.length > 0 ? { scheduleDependencies } : {}),
+    };
+}
+function validateTargetSources(manifest, databases, stableKeyName) {
+    const byStableKey = new Map();
+    for (const database of databases) {
+        const stableKey = stableKeyOf(database, stableKeyName);
+        if (!stableKey) {
+            continue;
+        }
+        byStableKey.set(stableKey, [...(byStableKey.get(stableKey) || []), database]);
+    }
+    for (const source of manifest.sources) {
+        const candidates = byStableKey.get(source.databaseStableKey) || [];
+        if (candidates.length !== 1) {
+            return `source Database Schema Stable Key "${source.databaseStableKey}" resolves to ${candidates.length} TARGET records`;
+        }
+        const database = candidates[0];
+        if (database.name !== source.name) {
+            return `source Database Schema "${source.databaseStableKey}" has TARGET name "${String(database.name || '')}" instead of "${source.name}"`;
+        }
+        if (!('columns' in source)) {
+            continue;
+        }
+        const columnsByStableKey = new Map();
+        for (const definition of Array.isArray(database.definition) ? database.definition.filter(isRecord) : []) {
+            const stableKey = stableKeyOf(definition, stableKeyName);
+            if (!stableKey) {
+                continue;
+            }
+            columnsByStableKey.set(stableKey, [...(columnsByStableKey.get(stableKey) || []), definition]);
+        }
+        for (const sourceColumn of source.columns) {
+            const columns = columnsByStableKey.get(sourceColumn.stableKey) || [];
+            if (columns.length !== 1) {
+                return `source column Stable Key "${sourceColumn.stableKey}" resolves to ${columns.length} TARGET definitions`;
+            }
+            const column = columns[0];
+            if (column.name !== sourceColumn.name
+                || column.type !== sourceColumn.type
+                || (column.isArray === true) !== sourceColumn.isArray) {
+                return `source column "${sourceColumn.stableKey}" is incompatible on TARGET`;
+            }
+        }
+    }
+    return undefined;
+}
+function databaseViewPreviewPayload(manifest) {
+    const output = { take: 0, count: false };
+    if (manifest.definitionMode === 'RAW_SQL') {
+        return {
+            definitionMode: 'RAW_SQL',
+            rawQuery: manifest.rawQuery,
+            take: 0,
+            output,
+        };
+    }
+    return {
+        definitionMode: 'STRUCTURED',
+        request: manifest.request,
+        take: 0,
+        output,
+    };
+}
+function previewOutput(result) {
+    const value = isRecord(result) && isRecord(result.data) ? result.data : result;
+    if (!isRecord(value)) {
+        return 'target preview returned an invalid response';
+    }
+    return outputSignature({ definition: value.definition });
+}
+function supportedTargetManifest(input) {
+    const exclusion = exclusionReason(input.record);
+    if (exclusion) {
+        return exclusion;
+    }
+    return manifestFromRecord(input);
+}
+export async function buildDatabaseViewsPlan(input) {
+    const { projectRoot } = requireProjectLayout(input.cwd, 'Database View');
+    const localEntries = readWorkspaceDatabaseViews(input.cwd);
+    const [targetViews, targetDatabaseResult, targetSchedules] = await Promise.all([
+        input.client.listAllDatabaseViewsForSync(),
+        input.client.listAllDatabaseSchemas({ projection: 'pull' }),
+        input.client.listAllSchedules(),
+    ]);
+    const targetDatabases = targetDatabaseResult.databases;
+    const targetInventory = sourceInventory(targetDatabases, input.stableKeyName);
+    const lock = readComponentLock(projectRoot);
+    const items = [];
+    const blockers = [];
+    const globalBlockers = [];
+    const warnings = [];
+    const exclusions = [];
+    const localByKey = new Map();
+    const lockEntriesByPath = new Map(Object.values(lock.databaseViews).map((entry) => [entry.path, entry]));
+    for (const entry of localEntries) {
+        if (!validManifest(entry.manifest, input.stableKeyName)) {
+            blockers.push(`Invalid Database View manifest ${path.relative(projectRoot, entry.manifestPath)}.`);
+            items.push({ status: 'conflict', name: path.basename(path.dirname(entry.manifestPath)), reason: 'invalid Database View manifest' });
+            continue;
+        }
+        const lockEntry = lockEntriesByPath.get(toPortableRelativePath(projectRoot, entry.manifestPath));
+        if (lockEntry && lockEntry.stableKey !== entry.manifest.stableKey) {
+            blockers.push(`Database View manifest ${path.relative(projectRoot, entry.manifestPath)} changed stableKey from "${lockEntry.stableKey}" to "${entry.manifest.stableKey}".`);
+            items.push({
+                status: 'conflict',
+                stableKey: entry.manifest.stableKey,
+                name: entry.manifest.name,
+                reason: `stableKey changed from "${lockEntry.stableKey}"; identity changes are not renames`,
+            });
+            continue;
+        }
+        localByKey.set(entry.manifest.stableKey, [...(localByKey.get(entry.manifest.stableKey) || []), entry]);
+    }
+    const targetByKey = new Map();
+    const excludedTargetByKey = new Map();
+    const targetUnmanagedNames = new Set();
+    for (const record of targetViews) {
+        const stableKey = stableKeyOf(record, input.stableKeyName);
+        const exclusion = exclusionReason(record);
+        const name = warningKey(record, stableKey || undefined);
+        if (exclusion) {
+            exclusions.push(`Database View "${name}": ${exclusion}.`);
+            items.push({ status: 'skipped', stableKey: stableKey || undefined, name, reason: exclusion });
+            if (stableKey) {
+                excludedTargetByKey.set(stableKey, exclusion);
+            }
+            continue;
+        }
+        if (!stableKey) {
+            targetUnmanagedNames.add(String(record.name || ''));
+            exclusions.push(`Database View "${name}": missing ${input.stableKeyName}; unmanaged.`);
+            items.push({ status: 'skipped', name, reason: `missing ${input.stableKeyName}; unmanaged` });
+            continue;
+        }
+        targetByKey.set(stableKey, [...(targetByKey.get(stableKey) || []), record]);
+    }
+    const duplicateTargetKeys = new Set();
+    for (const [stableKey, records] of targetByKey) {
+        if (records.length > 1) {
+            duplicateTargetKeys.add(stableKey);
+            const blocker = `Duplicate TARGET Database View stableKey "${stableKey}".`;
+            blockers.push(blocker);
+            globalBlockers.push(blocker);
+            items.push({ status: 'collision', stableKey, name: warningKey(records[0], stableKey), reason: 'duplicate target stableKey' });
+        }
+    }
+    for (const [stableKey, entries] of localByKey) {
+        if (entries.length > 1) {
+            const blocker = `Duplicate local Database View stableKey "${stableKey}".`;
+            blockers.push(blocker);
+            globalBlockers.push(blocker);
+            items.push({ status: 'collision', stableKey, name: entries[0].manifest.name, reason: 'duplicate local stableKey' });
+            continue;
+        }
+        const entry = entries[0];
+        const desired = entry.manifest;
+        const desiredHash = hashPortableDatabaseView(desired);
+        const excludedTargetReason = excludedTargetByKey.get(stableKey);
+        if (excludedTargetReason) {
+            const reason = `TARGET Database View is incompatible: ${excludedTargetReason}`;
+            blockers.push(`Database View "${stableKey}": ${reason}.`);
+            items.push({ status: 'collision', stableKey, name: desired.name, reason, desiredHash });
+            continue;
+        }
+        const sourceReadiness = validateTargetSources(desired, targetDatabases, input.stableKeyName);
+        if (sourceReadiness) {
+            blockers.push(`Database View "${stableKey}": ${sourceReadiness}.`);
+            items.push({ status: 'conflict', stableKey, name: desired.name, reason: sourceReadiness, desiredHash });
+            continue;
+        }
+        let preview;
+        try {
+            preview = await input.client.previewDatabaseView(databaseViewPreviewPayload(desired));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            warnings.push(`Database View "${stableKey}" TARGET preview failed: ${message}`);
+            items.push({ status: 'conflict', stableKey, name: desired.name, reason: `target preview failed: ${message}`, desiredHash });
+            continue;
+        }
+        const output = previewOutput(preview);
+        if (typeof output === 'string' || hashStable(output) !== hashStable(desired.output)) {
+            const reason = typeof output === 'string' ? output : 'target preview output signature differs from the manifest';
+            blockers.push(`Database View "${stableKey}": ${reason}.`);
+            items.push({ status: 'conflict', stableKey, name: desired.name, reason, desiredHash });
+            continue;
+        }
+        const records = targetByKey.get(stableKey) || [];
+        if (duplicateTargetKeys.has(stableKey)) {
+            continue;
+        }
+        if (records.length === 0) {
+            if (targetUnmanagedNames.has(desired.name)) {
+                const reason = 'TARGET has same-name unmanaged Database View; automatic adoption is forbidden';
+                blockers.push(`Database View "${stableKey}": ${reason}.`);
+                items.push({ status: 'collision', stableKey, name: desired.name, reason, desiredHash });
+            }
+            else {
+                items.push({ status: 'create', stableKey, name: desired.name, desiredHash, ...materializedPlanDetails({ manifest: desired, schedules: targetSchedules.schedules }) });
+            }
+            continue;
+        }
+        const record = records[0];
+        const current = supportedTargetManifest({ record, stableKey, stableKeyName: input.stableKeyName, inventory: targetInventory });
+        if (typeof current === 'string') {
+            const reason = `TARGET Database View is incompatible: ${current}`;
+            blockers.push(`Database View "${stableKey}": ${reason}.`);
+            items.push({ status: 'collision', stableKey, name: desired.name, reason, desiredHash });
+            continue;
+        }
+        if (current.name !== desired.name) {
+            const reason = 'TARGET name differs; renames require an explicit migration';
+            blockers.push(`Database View "${stableKey}": ${reason}.`);
+            items.push({ status: 'conflict', stableKey, name: desired.name, reason, desiredHash });
+            continue;
+        }
+        if (current.type !== desired.type || current.definitionMode !== desired.definitionMode) {
+            const reason = current.type !== desired.type
+                ? 'TARGET type differs; VIEW and MATERIALIZED_VIEW transitions require an explicit migration'
+                : 'TARGET definitionMode transition between STRUCTURED and RAW_SQL requires an explicit migration';
+            blockers.push(`Database View "${stableKey}": ${reason}.`);
+            items.push({ status: 'conflict', stableKey, name: desired.name, reason, desiredHash });
+            continue;
+        }
+        const currentHash = hashPortableDatabaseView(current);
+        const baselineHash = lock.databaseViews[stableKey]?.environments[input.envName]?.remoteHash;
+        if (desiredHash === currentHash) {
+            items.push({
+                status: baselineHash ? 'clean' : 'missing-lock',
+                stableKey,
+                name: desired.name,
+                desiredHash,
+                currentHash,
+                ...(baselineHash ? { baselineHash } : {}),
+                ...(baselineHash ? {} : { reason: 'TARGET matches manifest but has no environment baseline' }),
+                ...materializedPlanDetails({ manifest: desired, schedules: targetSchedules.schedules, databaseViewId: viewIdOf(record) }),
+            });
+            continue;
+        }
+        if (!baselineHash) {
+            items.push({ status: 'missing-lock', stableKey, name: desired.name, desiredHash, currentHash, reason: 'TARGET differs and has no environment baseline' });
+            continue;
+        }
+        const localChanged = hashDatabaseViewManifest(desired) !== lock.databaseViews[stableKey]?.sourceHash;
+        const targetChanged = currentHash !== baselineHash;
+        const status = localChanged && targetChanged ? 'conflict' : targetChanged ? 'remote-changed' : 'safe-update';
+        items.push({
+            status,
+            stableKey,
+            name: desired.name,
+            desiredHash,
+            currentHash,
+            baselineHash,
+            changedFields: diffManifestFields(desired, current),
+            ...materializedPlanDetails({ manifest: desired, schedules: targetSchedules.schedules, databaseViewId: viewIdOf(record) }),
+        });
+    }
+    for (const [stableKey, records] of targetByKey) {
+        if (!localByKey.has(stableKey) && !duplicateTargetKeys.has(stableKey)) {
+            items.push({ status: 'orphan', stableKey, name: warningKey(records[0], stableKey), reason: 'managed TARGET Database View has no local manifest' });
+        }
+    }
+    items.sort((left, right) => (String(left.stableKey || left.name).localeCompare(String(right.stableKey || right.name))
+        || left.status.localeCompare(right.status)));
+    const counts = emptyPlanCounts();
+    for (const item of items) {
+        counts[item.status] += 1;
+    }
+    return {
+        resourceType: 'database-view',
+        env: input.envName,
+        counts,
+        warnings: [...new Set(warnings)].sort((left, right) => left.localeCompare(right)),
+        blockers: [...new Set(blockers)].sort((left, right) => left.localeCompare(right)),
+        globalBlockers: [...new Set(globalBlockers)].sort((left, right) => left.localeCompare(right)),
+        exclusions: [...new Set(exclusions)].sort((left, right) => left.localeCompare(right)),
+        items,
+    };
+}
+function workspaceDatabaseViewsForPush(cwd, stableKeyName) {
+    const entriesByKey = new Map();
+    for (const entry of readWorkspaceDatabaseViews(cwd)) {
+        if (!validManifest(entry.manifest, stableKeyName)) {
+            continue;
+        }
+        entriesByKey.set(entry.manifest.stableKey, [...(entriesByKey.get(entry.manifest.stableKey) || []), entry]);
+    }
+    return new Map([...entriesByKey]
+        .filter(([, entries]) => entries.length === 1)
+        .map(([stableKey, entries]) => [stableKey, entries[0]]));
+}
+function createDatabaseViewPayload(manifest) {
+    const base = {
+        name: manifest.name,
+        ...(manifest.category === undefined ? {} : { category: manifest.category }),
+        ...(manifest.description === undefined ? {} : { desc: manifest.description }),
+        metadata: sanitizeUserMetadata(manifest.metadata),
+        type: manifest.type,
+        restricted: true,
+        users: [],
+        groups: [],
+        ...(manifest.type === 'MATERIALIZED_VIEW'
+            ? { uniqueKey: manifest.uniqueKey, indexes: databaseViewWriteIndexes(manifest.indexes) }
+            : {}),
+    };
+    if (manifest.definitionMode === 'RAW_SQL') {
+        return {
+            ...base,
+            definitionMode: 'RAW_SQL',
+            rawQuery: manifest.rawQuery,
+        };
+    }
+    return {
+        ...base,
+        definitionMode: 'STRUCTURED',
+        request: canonicalValue(manifest.request),
+    };
+}
+function databaseViewWriteIndexes(indexes) {
+    return indexes?.map((index) => ({
+        columns: index.columns.map((name) => ({ name })),
+        ...(index.unique === true ? { unique: true } : {}),
+    }));
+}
+function assertTargetPreviewMatchesManifest(manifest, preview) {
+    const output = previewOutput(preview);
+    if (typeof output === 'string') {
+        throw new Error(output);
+    }
+    if (hashStable(output) !== hashStable(manifest.output)) {
+        throw new Error('target preview output signature differs from the manifest');
+    }
+}
+async function recheckDatabaseViewCreate(input) {
+    const [views, databaseResult] = await Promise.all([
+        input.client.listAllDatabaseViewsForSync(),
+        input.client.listAllDatabaseSchemas({ projection: 'pull' }),
+    ]);
+    const stableKeyMatches = views.filter((record) => stableKeyOf(record, input.stableKeyName) === input.manifest.stableKey);
+    if (stableKeyMatches.length > 0) {
+        throw new Error('matching Stable Key appeared after planning');
+    }
+    if (views.some((record) => record.name === input.manifest.name)) {
+        throw new Error(`unmanaged-name-conflict: TARGET Database View "${input.manifest.name}" appeared after planning`);
+    }
+    const sourceReadiness = validateTargetSources(input.manifest, databaseResult.databases, input.stableKeyName);
+    if (sourceReadiness) {
+        throw new Error(sourceReadiness);
+    }
+    const preview = await input.client.previewDatabaseView(databaseViewPreviewPayload(input.manifest));
+    assertTargetPreviewMatchesManifest(input.manifest, preview);
+    return databaseResult.databases;
+}
+function verifyCreatedDatabaseView(input) {
+    if (stableKeyOf(input.created, input.stableKeyName) !== input.desired.stableKey) {
+        throw new Error(`written target is missing or changed ${input.stableKeyName}`);
+    }
+    if (input.created.restricted !== true || !Array.isArray(input.created.users) || !Array.isArray(input.created.groups)) {
+        throw new Error('created target does not expose the required private access policy');
+    }
+    if (input.created.users.length > 0 || input.created.groups.length > 0) {
+        throw new Error('created target copied ACL principals instead of remaining private');
+    }
+    const actual = manifestFromRecord({
+        record: input.created,
+        stableKey: input.desired.stableKey,
+        stableKeyName: input.stableKeyName,
+        inventory: sourceInventory(input.databases, input.stableKeyName),
+    });
+    if (typeof actual === 'string') {
+        throw new Error(actual);
+    }
+    const desiredHash = hashPortableDatabaseView(input.desired);
+    const remoteHash = hashPortableDatabaseView(actual);
+    if (remoteHash !== desiredHash) {
+        throw new Error(`created target did not match desired portable hash (desired: ${desiredHash}; actual: ${remoteHash})`);
+    }
+    return remoteHash;
+}
+function targetPrincipalIds(entries, property) {
+    const ids = [];
+    for (const entry of entries) {
+        const value = typeof entry === 'string'
+            ? entry
+            : isRecord(entry) && typeof entry[property] === 'string'
+                ? entry[property]
+                : undefined;
+        if (!isNonEmptyString(value)) {
+            throw new Error(`TARGET ${property === 'userId' ? 'user' : 'group'} ACL principal is invalid`);
+        }
+        ids.push(value);
+    }
+    return ids;
+}
+function updateDatabaseViewPayload(input) {
+    if (typeof input.target.restricted !== 'boolean' || !Array.isArray(input.target.users) || !Array.isArray(input.target.groups)) {
+        throw new Error('TARGET access policy is incomplete and cannot be preserved safely');
+    }
+    if (!Number.isInteger(input.target.version) || input.target.version < 0) {
+        throw new Error('TARGET version is unavailable for optimistic update');
+    }
+    const version = input.target.version;
+    const base = {
+        name: input.manifest.name,
+        category: input.manifest.category ?? null,
+        desc: input.manifest.description ?? null,
+        metadata: sanitizeUserMetadata(input.manifest.metadata),
+        type: input.manifest.type,
+        restricted: input.target.restricted,
+        users: targetPrincipalIds(input.target.users, 'userId'),
+        groups: targetPrincipalIds(input.target.groups, 'groupId'),
+        version,
+        ...(input.manifest.type === 'MATERIALIZED_VIEW'
+            ? { uniqueKey: input.manifest.uniqueKey, indexes: databaseViewWriteIndexes(input.manifest.indexes) }
+            : {}),
+    };
+    if (input.manifest.definitionMode === 'RAW_SQL') {
+        return {
+            ...base,
+            definitionMode: 'RAW_SQL',
+            rawQuery: input.manifest.rawQuery,
+        };
+    }
+    return {
+        ...base,
+        definitionMode: 'STRUCTURED',
+        request: canonicalValue(input.manifest.request),
+    };
+}
+function verifyUpdatedDatabaseView(input) {
+    if (stableKeyOf(input.written, input.stableKeyName) !== input.desired.stableKey) {
+        throw new Error(`written target is missing or changed ${input.stableKeyName}`);
+    }
+    if (!Array.isArray(input.written.users) || !Array.isArray(input.written.groups)) {
+        throw new Error('written target does not expose its access policy');
+    }
+    const actualUsers = targetPrincipalIds(input.written.users, 'userId');
+    const actualGroups = targetPrincipalIds(input.written.groups, 'groupId');
+    if (input.written.restricted !== input.expectedRestricted
+        || hashStable(actualUsers.sort()) !== hashStable([...input.expectedUsers].sort())
+        || hashStable(actualGroups.sort()) !== hashStable([...input.expectedGroups].sort())) {
+        throw new Error('written target did not preserve its access policy');
+    }
+    const actual = manifestFromRecord({
+        record: input.written,
+        stableKey: input.desired.stableKey,
+        stableKeyName: input.stableKeyName,
+        inventory: sourceInventory(input.databases, input.stableKeyName),
+    });
+    if (typeof actual === 'string') {
+        throw new Error(actual);
+    }
+    const remoteHash = hashPortableDatabaseView(actual);
+    const desiredHash = hashPortableDatabaseView(input.desired);
+    if (remoteHash !== desiredHash) {
+        throw new Error(`written target did not match desired portable hash (desired: ${desiredHash}; actual: ${remoteHash})`);
+    }
+    return remoteHash;
+}
+async function recheckDatabaseViewUpdate(input) {
+    const [views, databaseResult, schedules] = await Promise.all([
+        input.client.listAllDatabaseViewsForSync(),
+        input.client.listAllDatabaseSchemas({ projection: 'pull' }),
+        input.client.listAllSchedules(),
+    ]);
+    const matches = views.filter((record) => stableKeyOf(record, input.stableKeyName) === input.manifest.stableKey);
+    if (matches.length !== 1) {
+        throw new Error(`TARGET Stable Key resolves to ${matches.length} Database Views`);
+    }
+    const databaseViewId = viewIdOf(matches[0]);
+    if (!databaseViewId) {
+        throw new Error('TARGET Database View has no databaseViewId');
+    }
+    const target = unwrapData(await input.client.getDatabaseView(databaseViewId));
+    if (stableKeyOf(target, input.stableKeyName) !== input.manifest.stableKey) {
+        throw new Error(`TARGET Database View changed ${input.stableKeyName} after planning`);
+    }
+    if (target.type !== input.manifest.type || target.definitionMode !== input.manifest.definitionMode) {
+        throw new Error('TARGET Database View changed type or definitionMode after planning');
+    }
+    if (target.name !== input.manifest.name) {
+        throw new Error('TARGET name differs; renames require an explicit migration');
+    }
+    const sourceReadiness = validateTargetSources(input.manifest, databaseResult.databases, input.stableKeyName);
+    if (sourceReadiness) {
+        throw new Error(sourceReadiness);
+    }
+    const current = manifestFromRecord({
+        record: target,
+        stableKey: input.manifest.stableKey,
+        stableKeyName: input.stableKeyName,
+        inventory: sourceInventory(databaseResult.databases, input.stableKeyName),
+    });
+    if (typeof current === 'string') {
+        throw new Error(current);
+    }
+    if (hashPortableDatabaseView(current) !== input.expectedHash) {
+        throw new Error('TARGET portable content changed after planning');
+    }
+    const materializedDetails = materializedPlanDetails({
+        manifest: input.manifest,
+        schedules: schedules.schedules,
+        databaseViewId,
+    });
+    if (materializedDetails.scheduleDependencies && materializedDetails.scheduleDependencies.length > 0) {
+        throw new Error(`active refresh Schedule dependencies require manual coordination: ${materializedDetails.scheduleDependencies.join(', ')}`);
+    }
+    const preview = await input.client.previewDatabaseView(databaseViewPreviewPayload(input.manifest));
+    assertTargetPreviewMatchesManifest(input.manifest, preview);
+    return { target, databases: databaseResult.databases };
+}
+function updateDatabaseViewEnvironmentBaseline(input) {
+    const { projectRoot } = requireProjectLayout(input.cwd, 'Database View');
+    const lock = readComponentLock(projectRoot);
+    const existing = lock.databaseViews[input.manifest.stableKey];
+    const entry = {
+        stableKey: input.manifest.stableKey,
+        path: toPortableRelativePath(projectRoot, input.manifestPath),
+        sourceHash: hashDatabaseViewManifest(input.manifest),
+        environments: {
+            ...(existing?.environments || {}),
+            [input.envName]: { remoteHash: input.remoteHash, syncedAt: new Date().toISOString() },
+        },
+    };
+    lock.databaseViews[input.manifest.stableKey] = entry;
+    writeComponentLock(projectRoot, lock);
+}
+export async function pushDatabaseViews(input) {
+    const plan = await buildDatabaseViewsPlan(input);
+    const localByKey = workspaceDatabaseViewsForPush(input.cwd, input.stableKeyName);
+    if (input.stableKey && !localByKey.has(input.stableKey)) {
+        throw new Error(`Database View Stable Key "${input.stableKey}" was not found in the workspace.`);
+    }
+    const selected = (item) => !input.stableKey || item.stableKey === input.stableKey;
+    if (plan.globalBlockers.length > 0) {
+        return {
+            plan,
+            results: plan.items
+                .filter((item) => selected(item) && item.stableKey && localByKey.has(item.stableKey))
+                .map((item) => ({
+                stableKey: item.stableKey,
+                action: 'skipped',
+                status: 'skipped',
+                targetPath: localTargetPath(input.cwd, localByKey.get(item.stableKey).manifestPath),
+                reason: 'global Database View Stable Key ambiguity blocks every write',
+            })),
+        };
+    }
+    const canReconcile = (item) => (item.status === 'missing-lock'
+        && item.desiredHash !== undefined
+        && item.desiredHash === item.currentHash);
+    const canUpdate = (item) => (item.status === 'safe-update'
+        || (input.force === true && ['remote-changed', 'conflict', 'missing-lock'].includes(item.status) && !canReconcile(item)));
+    const results = [];
+    for (const item of plan.items) {
+        const local = item.stableKey ? localByKey.get(item.stableKey) : undefined;
+        if (selected(item) && item.stableKey && local && local.manifest.type === 'MATERIALIZED_VIEW' && input.allowMaterializedWrites !== true) {
+            results.push({
+                stableKey: item.stableKey,
+                action: 'skipped',
+                status: 'skipped',
+                targetPath: localTargetPath(input.cwd, local.manifestPath),
+                reason: 'MATERIALIZED_VIEW deployment requires --allow-materialized',
+            });
+            continue;
+        }
+        if (!selected(item)
+            || !item.stableKey
+            || !localByKey.has(item.stableKey)
+            || item.status === 'create'
+            || canReconcile(item)
+            || canUpdate(item)) {
+            continue;
+        }
+        const resolvedLocal = localByKey.get(item.stableKey);
+        results.push({
+            stableKey: item.stableKey,
+            action: 'skipped',
+            status: 'skipped',
+            targetPath: localTargetPath(input.cwd, resolvedLocal.manifestPath),
+            reason: item.reason || item.status,
+        });
+    }
+    for (const item of plan.items.filter((candidate) => (selected(candidate)
+        && candidate.status === 'create'
+        && candidate.stableKey
+        && (localByKey.get(candidate.stableKey)?.manifest.type === 'VIEW' || input.allowMaterializedWrites === true)))) {
+        const stableKey = item.stableKey;
+        const local = localByKey.get(stableKey);
+        if (!local) {
+            results.push({ stableKey, action: 'create', status: 'failed', targetPath: stableKey, error: 'desired manifest disappeared after planning' });
+            continue;
+        }
+        let writeAccepted = false;
+        try {
+            const desired = local.manifest;
+            if (hashPortableDatabaseView(desired) !== item.desiredHash) {
+                throw new Error('desired manifest changed after planning');
+            }
+            const databases = await recheckDatabaseViewCreate({
+                client: input.client,
+                manifest: desired,
+                stableKeyName: input.stableKeyName,
+            });
+            const created = unwrapData(await input.client.createDatabaseView(createDatabaseViewPayload(desired)));
+            writeAccepted = true;
+            const databaseViewId = viewIdOf(created);
+            if (!databaseViewId) {
+                throw new Error('create response did not include databaseViewId');
+            }
+            const verified = unwrapData(await input.client.getDatabaseView(databaseViewId));
+            const remoteHash = verifyCreatedDatabaseView({
+                created: verified,
+                databases,
+                desired,
+                stableKeyName: input.stableKeyName,
+            });
+            updateDatabaseViewEnvironmentBaseline({
+                cwd: input.cwd,
+                envName: input.envName,
+                manifestPath: local.manifestPath,
+                manifest: desired,
+                remoteHash,
+            });
+            results.push({
+                stableKey,
+                action: 'create',
+                status: 'deployed',
+                targetPath: localTargetPath(input.cwd, local.manifestPath),
+                accessPolicyRequired: true,
+                reason: 'created private; configure target-local ACL principals before use',
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            results.push({
+                stableKey,
+                action: 'create',
+                status: writeAccepted ? 'write-unverified' : 'failed',
+                targetPath: localTargetPath(input.cwd, local.manifestPath),
+                ...(writeAccepted
+                    ? { reason: `POST was accepted, but readback did not verify the desired portable hash; the environment lock was not updated (${message})` }
+                    : { error: message }),
+            });
+        }
+    }
+    for (const item of plan.items.filter((candidate) => (selected(candidate)
+        && candidate.stableKey
+        && canUpdate(candidate)
+        && (localByKey.get(candidate.stableKey)?.manifest.type === 'VIEW' || input.allowMaterializedWrites === true)))) {
+        const stableKey = item.stableKey;
+        const local = localByKey.get(stableKey);
+        if (!local) {
+            results.push({ stableKey, action: 'update', status: 'failed', targetPath: stableKey, error: 'desired manifest disappeared after planning' });
+            continue;
+        }
+        let writeAccepted = false;
+        try {
+            const desired = local.manifest;
+            if (hashPortableDatabaseView(desired) !== item.desiredHash || !item.currentHash) {
+                throw new Error('desired manifest or target hash changed after planning');
+            }
+            const live = await recheckDatabaseViewUpdate({
+                client: input.client,
+                manifest: desired,
+                stableKeyName: input.stableKeyName,
+                expectedHash: item.currentHash,
+            });
+            const payload = updateDatabaseViewPayload({ manifest: desired, target: live.target });
+            await input.client.updateDatabaseView(viewIdOf(live.target), payload);
+            writeAccepted = true;
+            const verified = unwrapData(await input.client.getDatabaseView(viewIdOf(live.target)));
+            const remoteHash = verifyUpdatedDatabaseView({
+                written: verified,
+                databases: live.databases,
+                desired,
+                stableKeyName: input.stableKeyName,
+                expectedRestricted: payload.restricted,
+                expectedUsers: payload.users,
+                expectedGroups: payload.groups,
+            });
+            updateDatabaseViewEnvironmentBaseline({
+                cwd: input.cwd,
+                envName: input.envName,
+                manifestPath: local.manifestPath,
+                manifest: desired,
+                remoteHash,
+            });
+            results.push({
+                stableKey,
+                action: 'update',
+                status: 'deployed',
+                targetPath: localTargetPath(input.cwd, local.manifestPath),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            results.push({
+                stableKey,
+                action: 'update',
+                status: writeAccepted ? 'write-unverified' : 'failed',
+                targetPath: localTargetPath(input.cwd, local.manifestPath),
+                ...(writeAccepted
+                    ? { reason: `PUT was accepted, but readback did not verify the desired portable hash; the environment lock was not updated (${message})` }
+                    : { error: message }),
+            });
+        }
+    }
+    for (const item of plan.items.filter((candidate) => (selected(candidate)
+        && candidate.stableKey
+        && canReconcile(candidate)
+        && (localByKey.get(candidate.stableKey)?.manifest.type === 'VIEW' || input.allowMaterializedWrites === true)))) {
+        const stableKey = item.stableKey;
+        const local = localByKey.get(stableKey);
+        if (!local) {
+            results.push({ stableKey, action: 'reconcile', status: 'failed', targetPath: stableKey, error: 'desired manifest disappeared after planning' });
+            continue;
+        }
+        try {
+            if (!item.currentHash || hashPortableDatabaseView(local.manifest) !== item.desiredHash) {
+                throw new Error('desired manifest or target hash changed after planning');
+            }
+            const live = await recheckDatabaseViewUpdate({
+                client: input.client,
+                manifest: local.manifest,
+                stableKeyName: input.stableKeyName,
+                expectedHash: item.currentHash,
+            });
+            const accessPolicy = updateDatabaseViewPayload({ manifest: local.manifest, target: live.target });
+            const remoteHash = verifyUpdatedDatabaseView({
+                written: live.target,
+                databases: live.databases,
+                desired: local.manifest,
+                stableKeyName: input.stableKeyName,
+                expectedRestricted: accessPolicy.restricted,
+                expectedUsers: accessPolicy.users,
+                expectedGroups: accessPolicy.groups,
+            });
+            updateDatabaseViewEnvironmentBaseline({
+                cwd: input.cwd,
+                envName: input.envName,
+                manifestPath: local.manifestPath,
+                manifest: local.manifest,
+                remoteHash,
+            });
+            results.push({
+                stableKey,
+                action: 'reconcile',
+                status: 'deployed',
+                targetPath: localTargetPath(input.cwd, local.manifestPath),
+            });
+        }
+        catch (error) {
+            results.push({
+                stableKey,
+                action: 'reconcile',
+                status: 'failed',
+                targetPath: localTargetPath(input.cwd, local.manifestPath),
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return { plan, results };
+}
+export async function pullDatabaseViewsToWorkspace(input) {
+    const { projectRoot, workspaceRoot } = requireProjectLayout(input.cwd, 'Database View');
+    const [sourceViews, sourceDatabases] = await Promise.all([
+        input.client.listAllDatabaseViewsForSync(),
+        input.client.listAllDatabaseSchemas({ projection: 'pull' }),
+    ]);
+    const inventory = sourceInventory(sourceDatabases.databases, input.stableKeyName);
+    const stableKeys = new Set();
+    for (const record of sourceViews) {
+        const stableKey = stableKeyOf(record, input.stableKeyName);
+        if (!stableKey) {
+            continue;
+        }
+        if (stableKeys.has(stableKey)) {
+            throw new Error(`Duplicate Database View stableKey "${stableKey}" on ${input.envName}; no files were changed.`);
+        }
+        stableKeys.add(stableKey);
+    }
+    const manifests = [];
+    const skipped = [];
+    for (const record of sourceViews) {
+        const stableKey = stableKeyOf(record, input.stableKeyName);
+        const exclusion = exclusionReason(record);
+        if (exclusion) {
+            skipped.push({ stableKey: stableKey || undefined, name: warningKey(record, stableKey || undefined), reason: exclusion });
+            continue;
+        }
+        if (!stableKey) {
+            skipped.push({ name: warningKey(record), reason: `missing ${input.stableKeyName}; Database View remains unmanaged` });
+            continue;
+        }
+        const manifest = manifestFromRecord({ record, stableKey, stableKeyName: input.stableKeyName, inventory });
+        if (typeof manifest === 'string') {
+            skipped.push({ stableKey, name: warningKey(record, stableKey), reason: manifest });
+            continue;
+        }
+        if (!validManifest(manifest, input.stableKeyName)) {
+            skipped.push({ stableKey, name: warningKey(record, stableKey), reason: 'Database View did not produce a valid portable manifest' });
+            continue;
+        }
+        manifests.push(manifest);
+    }
+    manifests.sort((left, right) => left.stableKey.localeCompare(right.stableKey));
+    skipped.sort((left, right) => (String(left.stableKey || left.name).localeCompare(String(right.stableKey || right.name))
+        || left.reason.localeCompare(right.reason)));
+    if (input.strict && skipped.length > 0) {
+        throw new Error(`Database View strict pull is incomplete: ${skipped.length} skipped or unmanaged item(s); no files were changed.`);
+    }
+    const lock = readComponentLock(projectRoot);
+    const existingByKey = new Map();
+    const existingByPath = new Map();
+    for (const entry of readWorkspaceDatabaseViews(input.cwd)) {
+        if (!validManifest(entry.manifest, input.stableKeyName)) {
+            throw new Error(`Cannot pull over invalid Database View manifest ${path.relative(projectRoot, entry.manifestPath)}.`);
+        }
+        if (existingByKey.has(entry.manifest.stableKey)) {
+            throw new Error(`Duplicate local Database View stableKey "${entry.manifest.stableKey}"; no files were changed.`);
+        }
+        existingByKey.set(entry.manifest.stableKey, entry);
+        existingByPath.set(path.resolve(entry.manifestPath), entry);
+    }
+    const writes = manifests.map((manifest) => {
+        const existing = existingByKey.get(manifest.stableKey);
+        const sourceHash = hashDatabaseViewManifest(manifest);
+        if (existing && !input.force) {
+            const localHash = hashDatabaseViewManifest(existing.manifest);
+            const baseline = lock.databaseViews[manifest.stableKey];
+            if (localHash !== sourceHash && (!baseline || localHash !== baseline.sourceHash)) {
+                throw new Error(`Cannot pull Database View "${manifest.stableKey}": local manifest changed since the lock baseline. Re-run with --force.`);
+            }
+        }
+        return {
+            manifest,
+            sourceHash,
+            remoteHash: hashPortableDatabaseView(manifest),
+            filePath: databaseViewManifestPath(workspaceRoot, manifest),
+            previousPath: existing?.manifestPath,
+        };
+    });
+    const targetPaths = new Set();
+    for (const write of writes) {
+        const targetPath = path.resolve(write.filePath);
+        if (targetPaths.has(targetPath)) {
+            throw new Error('Multiple Database Views resolve to the same workspace path; no files were changed.');
+        }
+        targetPaths.add(targetPath);
+        const existingAtPath = existingByPath.get(targetPath);
+        if (existingAtPath && existingAtPath.manifest.stableKey !== write.manifest.stableKey) {
+            throw new Error(`Database View workspace path "${path.relative(projectRoot, write.filePath)}" is occupied by different stableKey "${existingAtPath.manifest.stableKey}"; no files were changed.`);
+        }
+    }
+    const root = path.join(workspaceRoot, DATABASE_VIEWS_DIRECTORY);
+    let lockChanged = false;
+    for (const write of writes) {
+        writePulledManifest({
+            filePath: write.filePath,
+            manifest: write.manifest,
+            previousPath: write.previousPath,
+            root: root,
+            force: input.force,
+        });
+        const previous = lock.databaseViews[write.manifest.stableKey];
+        const previousBaseline = previous?.environments[input.envName];
+        const entry = {
+            stableKey: write.manifest.stableKey,
+            path: toPortableRelativePath(projectRoot, write.filePath),
+            sourceHash: write.sourceHash,
+            environments: {
+                ...(previous?.environments || {}),
+                [input.envName]: previousBaseline?.remoteHash === write.remoteHash
+                    ? previousBaseline
+                    : { remoteHash: write.remoteHash, syncedAt: new Date().toISOString() },
+            },
+        };
+        if (!previous || hashStable(previous) !== hashStable(entry)) {
+            lockChanged = true;
+        }
+        lock.databaseViews[write.manifest.stableKey] = entry;
+    }
+    if (lockChanged) {
+        writeComponentLock(projectRoot, lock);
+    }
+    return {
+        pulled: writes.map((write) => ({
+            manifest: write.manifest,
+            targetPath: localTargetPath(input.cwd, write.filePath),
+        })),
+        skipped,
+    };
+}