@frontera-sdk/cli 1.52.39 → 1.52.40

package/src/local/local-dev-references.ts

@@ -6,7 +6,7 @@ import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
 import type { LocalAction } from './local-actions'
 import { absentWhy, adaptOperating, plainLinks, projectProvides } from './local-adapt'
 import { applyAgentGrants, type AgentGrant } from './local-agent-grants'
-import { oneLine, refWords } from './local-applied'
+import { loadBuild, oneLine, pushedWorkflowVersion, refWords } from './local-applied'
 import { readableName } from './local-sync-names'
 import { ensureObjectDefinitions } from './local-objects'
 import { applyQualityChecks, QUALITY_CHECKS_FILE, readQualityChecks, sourcePaths, sourceRows } from './local-quality-checks'
@@ -14,14 +14,21 @@ import { readLock } from './local-sync-plan'
 import { applyErrorText } from './local-apply-error'
 import { localAdaptation } from './local-blueprint-outline'
 import { actionFit, classify, objectTypeFit, objectTypeNeeds } from './local-portability'
+import { actionSemanticConflicts, semanticFactsOf } from '../blueprint/action-semantic-fit'
+import { inheritedConflictLine } from '../blueprint/action-rules'
+import { inheritedFromPull, unchangedSincePull } from './local-check-inherited'
 import type { SyncProfiles, SyncTarget } from './local-dev-sync'
 import type { LocalProject } from './local-project'
 import { syncClient } from './local-sync-client'
+import { DEFAULT_KNOWLEDGE_THRESHOLD, KEYLESS_KNOWLEDGE_THRESHOLD, PLATFORM_DEFAULT_EMBEDDING, sameEmbedding, WIDENED_KNOWLEDGE_THRESHOLD, type OrgSettings } from './local-org-settings'
+import { isLocalEmbeddings } from './local-seed'
+import { readLink } from './local-sync-link'
+import { readSnapshot } from './local-sync-snapshot'
 import { readProviderSetup } from './local-providers'
 import { fillPluginSecrets, localSecretNames, needsValueLine, NON_SECRET_HEADERS, pluginSecretInputs, pluginSecretName } from './local-secrets'
 import { describeUnresolved, governedActionIds, isUuid, kindsIn, parseRef, referencesIn, toIds, type Directory } from './local-sync-refs'
 import { buildDirectory, rows } from './local-sync-remote'
-import type { LocalCredentials } from './local-state'
+import { isAlive, type LocalCredentials } from './local-state'
 import { addStandInServers, dropPlatformOnly, dropStandInTriggers, platformOnlyNames, standInNames } from './local-stand-ins'
 
 /**
@@ -441,12 +448,43 @@ function parseJson<T>(output: string): T | null {
   }
 }
 
+/**
+ * Why a dataset file is not applied here, when an object type over a Media
+ * Set reads it (`media_<set>`, or a type with a media property left off):
+ * that type reads a Media Set's catalog, which an empty stand-in Media Set
+ * holds here (or nothing, for a type left off), and a CSV of sample rows
+ * cannot publish into it ("Only managed Datasets accept file publications").
+ * Null for any other dataset.
+ */
+export function mediaCatalogDatasetReason(root: string, dataset: string): string | null {
+  const dir = join(root, 'blueprint', 'object-types')
+  if (!existsSync(dir)) return null
+  for (const name of readdirSync(dir).filter((n) => /\.ya?ml$/.test(n) && !n.startsWith('.'))) {
+    let doc: Record<string, any> | null
+    try {
+      doc = parseYaml(readFileSync(join(dir, name), 'utf8')) as Record<string, any> | null
+    } catch {
+      continue
+    }
+    if (!doc || doc.backing?.dataset !== dataset) continue
+    const fit = localAdaptation(doc, () => false)
+    if (fit.mediaStub) return `${doc.apiName ?? name} reads it as Media Set ${fit.mediaStub}'s catalog, which an empty Media Set stands in for here (its files stay on the platform); a CSV can't publish into a Media Set's catalog, so datasets/${dataset}.* is left as it is and not applied`
+    if (fit.leftOff) return `${doc.apiName ?? name} reads the platform's media files and is left off this runtime, so datasets/${dataset}.* is not applied`
+  }
+  return null
+}
+
 /** How the runtime holds one object type of the Blueprint it was given. */
 export interface ObjectBuild {
   status: 'built' | 'adapted' | 'stubbed' | 'left-off'
   adaptations?: string[]
+  /** Left off because the local runtime refused this type's file: the runtime's words. The rest of the Blueprint builds. */
+  refused?: string
 }
 
+/** A Blueprint artifact the local runtime refused, by `kind:apiName` (`object-type:Receipt`), with its words. */
+export type BlueprintRefusals = ReadonlyMap<string, string>
+
 export interface ResolvedBlueprint {
   /** The runtime's copy, when the project's files needed changing; unset otherwise. */
   dir?: string
@@ -457,13 +495,29 @@ export interface ResolvedBlueprint {
   actions: LocalAction[]
   /** Actions left off the copy, with why: they act on what the runtime leaves off. */
   leftOffActions: Record<string, string>
+  /** The Actions of `leftOffActions` the runtime refused (their own file), not left off by design. */
+  refusedActions?: string[]
+  /**
+   * Each Action given to the runtime as the workspace runs it although it offers
+   * a value the semantic type it writes refuses (`inheritedFromPull`), with the
+   * warning lines: it deploys, and the build and `local check` say them as inherited.
+   */
+  inheritedWarnings?: Record<string, string[]>
+  /**
+   * The link types, metrics, semantic types and shared fields left off the copy, by the
+   * reference `status` lists them as (`metric/workOrdersRaised`): with why, and whether the
+   * runtime refused the file itself (a failure to fix) or it names a type left off.
+   */
+  parts?: Record<string, { reason: string; refused: boolean }>
   /** The Media Sets the runtime needs, empty, for the media-backed types it holds: API name → display name. */
   mediaSets?: Record<string, string>
+  /** Each type over a Media Set's catalog: its set, and its file in the runtime's copy (`object-types/Receipt.yaml`). */
+  mediaTypes?: Record<string, { set: string; file: string }>
 }
 
 /**
  * The Blueprint as this runtime can hold it, in a copy under
- * `.frontera/local/resolved/blueprint`; the project's files stay as pulled.
+ * `.frontera/local/resolved/run-<pid>/blueprint`; the project's files stay as pulled.
  * The rules are `objectTypeFit` and `actionFit` (`local-portability.ts`):
  * - An object type backed by the platform's media files (a `media_reference`
  *   property) cannot be read from a local file dataset: it is left out, with
@@ -471,13 +525,16 @@ export interface ResolvedBlueprint {
  * - An object type whose rows are read by markings, with no markings column
  *   named, relies on a column the platform's media datasets publish; over a
  *   local file dataset it reads with organization row access instead.
- * - A calculated property is left off the type, and an Action that sets it.
+ * - A calculated property other than a location is left off the type, and an
+ *   Action that sets it (a location is added by `blueprint apply`).
  * Each says so. `dir` is unset when nothing needed changing.
  */
-export function resolveBlueprint(project: LocalProject): ResolvedBlueprint {
+export function resolveBlueprint(project: LocalProject, refused: BlueprintRefusals = new Map()): ResolvedBlueprint {
   const source = join(project.root, 'blueprint')
   const types = join(source, 'object-types')
   const none: ResolvedBlueprint = { warnings: [], objects: {}, actions: [], leftOffActions: {} }
+  const parts: Record<string, { reason: string; refused: boolean }> = {}
+  const offWords = (t: string) => (objects[t]?.refused ? `it names ${t}, which the local runtime refused` : `it names ${t}, which reads the platform’s media files`)
   if (!existsSync(types)) return none
   const yamlIn = (dir: string) => (existsSync(join(source, dir)) ? readdirSync(join(source, dir)).filter((n) => /\.ya?ml$/.test(n) && !n.startsWith('.')) : [])
   const read = (dir: string, name: string) => {
@@ -495,12 +552,22 @@ export function resolveBlueprint(project: LocalProject): ResolvedBlueprint {
   const warnings: string[] = []
   const objects: Record<string, ObjectBuild> = {}
   const mediaSets: Record<string, string> = {}
+  const mediaTypes: Record<string, { set: string; file: string }> = {}
   const hasLocalDataset = (dataset: string) => existsSync(join(project.root, 'datasets', `${dataset}.json`))
   for (const name of yamlIn('object-types')) {
     const doc = read('object-types', name)
     if (!doc || typeof doc.apiName !== 'string') continue
     const fit = localAdaptation(doc, hasLocalDataset)
     const adaptations = classify(objectTypeNeeds(doc, hasLocalDataset)).adaptations
+    // The runtime refused this type's file on an earlier try: the rest of the Blueprint builds without it.
+    const refusal = refused.get(`object-type:${doc.apiName}`)
+    if (refusal) {
+      dropped.add(doc.apiName)
+      removed.push(join('object-types', name))
+      objects[doc.apiName] = { status: 'left-off', adaptations: [`is left off: the local runtime refused it: ${refusal}`], refused: refusal }
+      warnings.push(`  warning: ${doc.apiName} is left off this runtime: the runtime refused it: ${refusal}`)
+      continue
+    }
     if (fit.leftOff) {
       dropped.add(doc.apiName)
       removed.push(join('object-types', name))
@@ -514,17 +581,19 @@ export function resolveBlueprint(project: LocalProject): ResolvedBlueprint {
     // A property's set is the platform's id; the runtime derives its own from the dataset.
     if (fit.mediaStub) {
       mediaSets[fit.mediaStub] ??= readableName(fit.mediaStub)
+      mediaTypes[doc.apiName] = { set: fit.mediaStub, file: join('object-types', name) }
       const properties = (doc.properties as Array<Record<string, unknown>> | undefined) ?? []
       next = { ...next, properties: properties.map(({ mediaSetId: _set, ...p }) => p) }
-      warnings.push(`  warning: ${doc.apiName}’s files stay on the platform: an empty Media Set, ${fit.mediaStub}, stands in for them here`)
+      warnings.push(`  warning: ${doc.apiName}’s files stay on the platform: a stand-in Media Set, ${fit.mediaStub}, holds placeholder files for them here`)
     }
-    // A calculated property (a location from latitude and longitude) reads no column, and
-    // `blueprint apply` cannot create one yet: the runtime holds the type without it.
+    // A location (from latitude and longitude) is added by `blueprint apply` after the type. Any
+    // other calculation has no route from a file: the runtime holds the type without it.
     if (fit.calculated.length) {
-      const properties = (doc.properties as Array<{ calculation?: unknown }> | undefined) ?? []
-      next = { ...next, properties: properties.filter((p) => !p.calculation) }
+      const off = new Set(fit.calculated)
+      const properties = (doc.properties as Array<{ apiName?: string; calculation?: unknown }> | undefined) ?? []
+      next = { ...next, properties: properties.filter((p) => !off.has(String(p.apiName))) }
       for (const f of fit.calculated) droppedFields.add(`${doc.apiName}.${f}`)
-      warnings.push(`  warning: ${doc.apiName}.${fit.calculated.join(`, ${doc.apiName}.`)} is left off this runtime: calculated fields are not applied locally yet`)
+      warnings.push(`  warning: ${doc.apiName}.${fit.calculated.join(`, ${doc.apiName}.`)} is left off this runtime: only a location is a calculated field a file can add`)
     }
     if (fit.readsEveryRow) {
       next = { ...next, rowAccess: 'organization' }
@@ -532,17 +601,48 @@ export function resolveBlueprint(project: LocalProject): ResolvedBlueprint {
     }
     if (next !== doc) patched.set(join('object-types', name), stringifyYaml(next, { lineWidth: 0 }))
   }
-  if (dropped.size) {
-    for (const name of yamlIn('link-types')) {
-      const doc = read('link-types', name)
-      if (dropped.has(doc?.from?.objectType) || dropped.has(doc?.to?.objectType)) removed.push(join('link-types', name))
-    }
-    for (const name of yamlIn('metrics')) {
-      if (dropped.has(read('metrics', name)?.objectType)) removed.push(join('metrics', name))
+  // A link type or metric the runtime refused, or that names a type left off, goes too; a refused
+  // semantic type or shared field is taken out, and what names it is refused (and left off) next.
+  const refusedHere = (kind: string, doc: Record<string, any> | null) => (typeof doc?.apiName === 'string' ? refused.get(`${kind}:${doc.apiName}`) : undefined)
+  for (const name of yamlIn('link-types')) {
+    const doc = read('link-types', name)
+    const refusal = refusedHere('link-type', doc)
+    if (refusal) warnings.push(`  warning: link type ${doc!.apiName} is left off this runtime: the runtime refused it: ${refusal}`)
+    const offType = [doc?.from?.objectType, doc?.to?.objectType].find((t) => typeof t === 'string' && dropped.has(t)) as string | undefined
+    if (refusal || offType) removed.push(join('link-types', name))
+    if (typeof doc?.apiName === 'string' && (refusal || offType)) parts[`linkType/${doc.apiName}`] = refusal ? { reason: `the local runtime refused it: ${refusal}`, refused: true } : { reason: offWords(offType!), refused: false }
+  }
+  for (const name of yamlIn('metrics')) {
+    const doc = read('metrics', name)
+    const refusal = refusedHere('metric', doc)
+    if (refusal) warnings.push(`  warning: metric ${doc!.apiName} is left off this runtime: the runtime refused it: ${refusal}`)
+    if (refusal || dropped.has(doc?.objectType)) removed.push(join('metrics', name))
+    if (typeof doc?.apiName === 'string' && (refusal || dropped.has(doc?.objectType))) parts[`metric/${doc.apiName}`] = refusal ? { reason: `the local runtime refused it: ${refusal}`, refused: true } : { reason: offWords(String(doc.objectType)), refused: false }
+  }
+  for (const [kind, folder] of [['semantic-type', 'semantic-types'], ['shared-field', 'shared-fields']] as const) {
+    for (const name of yamlIn(folder)) {
+      const doc = read(folder, name)
+      const refusal = refusedHere(kind, doc)
+      if (!refusal) continue
+      removed.push(join(folder, name))
+      warnings.push(`  warning: ${kind.replace('-', ' ')} ${doc!.apiName} is left off this runtime: the runtime refused it: ${refusal}`)
+      parts[`${kind === 'semantic-type' ? 'semanticType' : 'sharedField'}/${doc!.apiName}`] = { reason: `the local runtime refused it: ${refusal}`, refused: true }
     }
   }
   const actions: LocalAction[] = []
   const leftOffActions: Record<string, string> = {}
+  const refusedActions: string[] = []
+  // A value an Action offers that the semantic type it writes refuses, in an Action and files still as
+  // pulled: the workspace's, so the apply takes it (`action-rules.ts`), and it is said here as inherited.
+  const inheritedWarnings: Record<string, string[]> = {}
+  const unchanged = unchangedSincePull(project.root)
+  const inheritedConflict = unchanged.refs.size ? inheritedFromPull(unchanged) : null
+  const semantic = inheritedConflict
+    ? semanticFactsOf((['semantic-types', 'shared-fields', 'object-types'] as const).flatMap((folder) => yamlIn(folder).flatMap((name) => {
+        const document = read(folder, name)
+        return document ? [{ path: `${folder}/${name}`, document }] : []
+      })))
+    : null
   for (const name of yamlIn('actions')) {
     const doc = read('actions', name)
     if (!doc || typeof doc.apiName !== 'string') continue
@@ -552,18 +652,38 @@ export function resolveBlueprint(project: LocalProject): ResolvedBlueprint {
     const touches = [fit.subject, ...changes.map((c) => c?.objectType), ...inputs.map((i) => i?.valueType?.objectType)].filter((t): t is string => typeof t === 'string')
     const offType = touches.find((t) => dropped.has(t))
     const offField = changes.map((c) => `${c?.objectType ?? fit.subject}.${c?.property}`).find((f) => droppedFields.has(f))
-    if (offType || offField) {
-      leftOffActions[doc.apiName] = offType ? `it acts on ${offType}, which reads the platform’s media files` : `it sets ${offField}, a calculated field the runtime leaves off`
+    const refusal = refused.get(`action:${doc.apiName}`)
+    if (offType || offField || refusal) {
+      const offWhy = offType && objects[offType]?.refused ? 'which the local runtime refused' : 'which reads the platform’s media files'
+      leftOffActions[doc.apiName] = refusal ? `the local runtime refused it: ${refusal}` : offType ? `it acts on ${offType}, ${offWhy}` : `it sets ${offField}, a calculated field the runtime leaves off`
+      if (refusal) refusedActions.push(doc.apiName)
       removed.push(join('actions', name))
       warnings.push(`  warning: governed Action ${doc.apiName} is left off this runtime: ${leftOffActions[doc.apiName]}`)
       continue
     }
     const capability = doc.governance?.invokeCapability
     actions.push({ apiName: doc.apiName, fit, ...(typeof capability === 'string' ? { invokeCapability: capability } : {}) })
+    const conflicts = semantic && inheritedConflict ? actionSemanticConflicts(doc, semantic) : []
+    if (conflicts.length && conflicts.every((c) => inheritedConflict!(doc.apiName, c.refs))) {
+      inheritedWarnings[doc.apiName] = conflicts.map((c) => inheritedConflictLine(c.message))
+    }
+  }
+  const out: ResolvedBlueprint = {
+    warnings, objects, actions, leftOffActions,
+    ...(refusedActions.length ? { refusedActions } : {}),
+    ...(Object.keys(inheritedWarnings).length ? { inheritedWarnings } : {}),
+    ...(Object.keys(parts).length ? { parts } : {}),
+    ...(Object.keys(mediaSets).length ? { mediaSets, mediaTypes } : {}),
   }
-  const out: ResolvedBlueprint = { warnings, objects, actions, leftOffActions, ...(Object.keys(mediaSets).length ? { mediaSets } : {}) }
   if (!patched.size && !removed.length) return out
-  const copy = join('.frontera', 'local', 'resolved', 'blueprint')
+  // This process's own copy: a second `local dev` (Forge's watcher beside a `--once`) makes its own,
+  // so neither applies a folder the other is rewriting. Copies of processes gone are cleared.
+  const runs = join(project.root, '.frontera', 'local', 'resolved')
+  for (const name of existsSync(runs) ? readdirSync(runs) : []) {
+    const pid = /^run-(\d+)$/.exec(name)?.[1]
+    if (pid && Number(pid) !== process.pid && !isAlive(Number(pid))) rmSync(join(runs, name), { recursive: true, force: true })
+  }
+  const copy = join('.frontera', 'local', 'resolved', `run-${process.pid}`, 'blueprint')
   rmSync(join(project.root, copy), { recursive: true, force: true })
   cpSync(source, join(project.root, copy), { recursive: true })
   for (const [rel, text] of patched) writeFileSync(join(project.root, copy, rel), text)
@@ -571,13 +691,37 @@ export function resolveBlueprint(project: LocalProject): ResolvedBlueprint {
   return { ...out, dir: copy }
 }
 
+/**
+ * Point each type over a Media Set's catalog at the dataset that catalog is
+ * on this runtime. A set's catalog is `media_<set>` unless that name was
+ * taken when the set was made (a sample dataset of the same name the project
+ * applied first): then the runtime named it otherwise, and a type left
+ * reading `media_<set>` would read the sample's plain text columns, which
+ * the runtime refuses for a media field. Edits the runtime's copy only.
+ */
+export function pointMediaTypesAt(project: LocalProject, blueprint: ResolvedBlueprint, catalogs: Readonly<Record<string, string>>): void {
+  if (!blueprint.dir || !blueprint.mediaTypes) return
+  for (const { set, file } of Object.values(blueprint.mediaTypes)) {
+    const catalog = catalogs[set]
+    if (!catalog || catalog === `media_${set}`) continue
+    const at = join(project.root, blueprint.dir, file)
+    try {
+      const doc = parseYaml(readFileSync(at, 'utf8')) as Record<string, any> | null
+      if (!doc?.backing || typeof doc.backing !== 'object') continue
+      writeFileSync(at, stringifyYaml({ ...doc, backing: { ...doc.backing, dataset: catalog } }, { lineWidth: 0 }))
+    } catch {
+      // A file that does not parse is refused by the apply, and said there.
+    }
+  }
+}
+
 /**
  * The properties each object type lets a governed Action write
  * (`backing.editable`), for the types those Actions act on. `blueprint apply`
  * leaves backings to `bind`, so `local dev` declares them itself
  * (`blueprint editable`) before an Action's write path is built.
  */
-export function editableSets(dir: string, subjects: ReadonlySet<string>): Map<string, string[]> {
+export function editableSets(dir: string, subjects: ReadonlySet<string> | null): Map<string, string[]> {
   const out = new Map<string, string[]>()
   const at = join(dir, 'object-types')
   if (!existsSync(at)) return out
@@ -586,7 +730,7 @@ export function editableSets(dir: string, subjects: ReadonlySet<string>): Map<st
     try {
       const doc = parseYaml(readFileSync(join(at, name), 'utf8')) as { apiName?: unknown; backing?: { editable?: unknown } } | null
       const editable = doc?.backing?.editable
-      if (typeof doc?.apiName === 'string' && subjects.has(doc.apiName) && Array.isArray(editable) && editable.length) out.set(doc.apiName, editable.map(String).sort())
+      if (typeof doc?.apiName === 'string' && (!subjects || subjects.has(doc.apiName)) && Array.isArray(editable) && editable.length) out.set(doc.apiName, editable.map(String).sort())
     } catch {
       // A file that does not parse is refused by the apply itself.
     }
@@ -625,14 +769,33 @@ const KNOWLEDGE_SETTINGS = ['retrieval', 'chunker', 'chunkSize', 'chunkOverlap',
 /** The files `local dev` uploads into a knowledge base: those the runtime ingests. */
 export const KNOWLEDGE_DOCUMENT = /\.(md|markdown|txt|pdf|docx|html)$/i
 
+/**
+ * What the runtime's embedding model is compared against, when it differs:
+ * the linked workspace's, or, in a project with no workspace, the platform's
+ * default, which the default threshold is tuned for. `keyless`: the runtime
+ * embeds with the keyless local embeddings, whose distances no model's
+ * threshold fits, whatever the workspace embeds with.
+ */
+export type EmbeddingMismatch = 'workspace' | 'platform-default' | 'keyless'
+
 /**
  * A knowledge base's settings as the runtime can hold them. A model it names
  * (the reranker, the extractor's, OCR's) that the runtime's catalog does not
  * have is left off here, so documents are read and searched without that
  * step instead of failing; each says so. `models` is the catalog, or null
  * when it could not be read (the settings then go as they are).
+ *
+ * When the runtime embeds with another model than the workspace, or, with
+ * no workspace, than the platform's default (`embeddingsDiffer`), the
+ * distances between a question and its passages are not the ones the
+ * default threshold was set for, and it finds nothing that model ranks a
+ * little further away: the base searches with a wider one here (only when
+ * the file sets none, or the default), as an adaptation. On the keyless
+ * local embeddings every base searches with `KEYLESS_KNOWLEDGE_THRESHOLD`,
+ * whatever its file sets: its threshold is for a model's distances. The
+ * file is never changed, and a platform never sees either threshold.
  */
-export function knowledgeSettings(doc: Record<string, unknown>, models: ReadonlySet<string> | null, label: string): { settings: Record<string, unknown>; warnings: string[] } {
+export function knowledgeSettings(doc: Record<string, unknown>, models: ReadonlySet<string> | null, label: string, embeddingsDiffer: EmbeddingMismatch | boolean = false): { settings: Record<string, unknown>; warnings: string[] } {
   const settings: Record<string, unknown> = {}
   for (const key of KNOWLEDGE_SETTINGS) if (doc[key] !== undefined && doc[key] !== null) settings[key] = doc[key]
   // The platform keeps the threshold as a decimal, which its list sends as a string ("0.7"); the update takes numbers.
@@ -640,6 +803,15 @@ export function knowledgeSettings(doc: Record<string, unknown>, models: Readonly
     if (typeof settings[key] === 'string' && Number.isFinite(Number(settings[key]))) settings[key] = Number(settings[key])
   }
   const warnings: string[] = []
+  if (embeddingsDiffer === 'keyless') {
+    const own = settings.similarityThreshold === undefined ? '' : ` (its file’s ${String(settings.similarityThreshold)} is for a model’s embeddings, and stays the workspace’s)`
+    settings.similarityThreshold = KEYLESS_KNOWLEDGE_THRESHOLD
+    warnings.push(`  warning: Knowledge base ${label} searches with threshold ${KEYLESS_KNOWLEDGE_THRESHOLD} here, set for the keyless local embeddings${own}: retrieval is approximate, by the words a passage shares with the question; a key the provider accepts for an embedding model gives the platform’s (\`frontera local status\` says which, under Embeddings)`)
+  } else if (embeddingsDiffer && (settings.similarityThreshold === undefined || settings.similarityThreshold === DEFAULT_KNOWLEDGE_THRESHOLD)) {
+    settings.similarityThreshold = WIDENED_KNOWLEDGE_THRESHOLD
+    const from = embeddingsDiffer === 'platform-default' ? 'the platform’s default, which its threshold is tuned for' : 'the workspace’s'
+    warnings.push(`  warning: Knowledge base ${label} searches with threshold ${WIDENED_KNOWLEDGE_THRESHOLD} here: embeddings differ from ${from}`)
+  }
   const has = (model: unknown) => typeof model !== 'string' || !model.trim() || !models || models.has(model) || models.has(model.split('/').pop()!)
   const hybrid = settings.hybridConfig as Record<string, unknown> | undefined
   if (hybrid?.rerank === true && !has(hybrid.rerankerModel)) {
@@ -656,6 +828,35 @@ export function knowledgeSettings(doc: Record<string, unknown>, models: Readonly
   return { settings, warnings }
 }
 
+/**
+ * Whether the runtime embeds with another model than the workspace (as the
+ * last fetch recorded the workspace's settings), the same model through
+ * another provider counting as the same. A project linked to no workspace
+ * (`local init`) is compared against the platform's default model instead:
+ * its knowledge files carry the default threshold, which is tuned for that
+ * model. `keyless` when the runtime embeds with the keyless local
+ * embeddings, whatever the workspace's. False when either side is not known,
+ * including a linked workspace not fetched yet.
+ */
+export async function embeddingsDiffer(root: string, local: { serviceUrl: string; creds: LocalCredentials }): Promise<EmbeddingMismatch | false> {
+  if (!local.creds.workspaceKey) return false
+  const linked = readLink(root) !== null
+  const workspace = linked ? readSnapshot(root)?.settings?.embedding : PLATFORM_DEFAULT_EMBEDDING
+  try {
+    const here = (await syncClient(local.serviceUrl, local.creds.workspaceKey).get<OrgSettings | { data?: OrgSettings }>('/v1/sync/settings')) as OrgSettings & { data?: OrgSettings }
+    const settings = here?.data ?? here
+    if (!settings || !('embedding' in settings)) return false
+    if (!settings.embedding?.provider || !settings.embedding.model) return false
+    // Before the workspace is compared: the keyless embeddings answer as OpenAI's model, and are never it.
+    if (isLocalEmbeddings(settings.embedding)) return 'keyless'
+    if (!workspace?.provider || !workspace.model) return false
+    if (sameEmbedding(workspace, settings.embedding)) return false
+    return linked ? 'workspace' : 'platform-default'
+  } catch {
+    return false
+  }
+}
+
 /** The runtime's model catalog, by slug and by provider/model id; null when it could not be read. */
 async function localModels(local: { serviceUrl: string; creds: LocalCredentials }): Promise<Set<string> | null> {
   try {
@@ -676,6 +877,48 @@ async function localModels(local: { serviceUrl: string; creds: LocalCredentials
  * search and reranking, extraction and OCR), then the folder's documents the
  * base does not hold yet are uploaded.
  */
+/**
+ * What to say of a knowledge base with no documents in its folder: an Agent
+ * searching it finds nothing. A base pulled from a workspace (in
+ * `frontera.lock`) has its documents there, and the pull brings them; one of
+ * the project's own takes Markdown or text files in its folder.
+ */
+export function emptyKnowledgeNote(root: string, folder: string, name: string): string {
+  const pulled = !!readLockSafe(root)?.items[`knowledge/${folder}`]
+  return pulled
+    ? `Knowledge base ${name} has no documents here, so an Agent searching it finds nothing: its documents stay in the workspace until \`frontera local sync pull --documents ${folder}\` brings them`
+    : `Knowledge base ${name} has no documents, so an Agent searching it finds nothing: add Markdown or text files to knowledge/${folder}/`
+}
+
+function readLockSafe(root: string): { items: Record<string, unknown> } | null {
+  try {
+    const lock = JSON.parse(readFileSync(join(root, 'frontera.lock'), 'utf8')) as { items?: Record<string, unknown> }
+    return lock?.items && typeof lock.items === 'object' ? { items: lock.items } : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * What a knowledge base's settings change did to its documents, in words
+ * (`rechunk` from the settings write): how many are being chunked again,
+ * why none were, and which keep their chunks (added as text). Nothing when
+ * the change asked for no chunking.
+ */
+export function rechunkNotes(name: string, rechunk: unknown): string[] {
+  if (!rechunk || typeof rechunk !== 'object') return []
+  const r = rechunk as { changed?: unknown; queued?: unknown; kept?: unknown; notQueued?: unknown }
+  const changed = Array.isArray(r.changed) ? r.changed.filter((c): c is string => typeof c === 'string') : []
+  if (!changed.length) return []
+  const queued = typeof r.queued === 'number' ? r.queued : 0
+  const kept = Array.isArray(r.kept) ? r.kept.filter((k): k is string => typeof k === 'string') : []
+  const lines: string[] = []
+  if (queued) lines.push(`  note: Knowledge base ${name}: ${changed.join(', ')} changed, so ${queued} document${queued === 1 ? ' is' : 's are'} being chunked again (\`frontera knowledge sources ${name}\` shows each as processing, then ready)`)
+  else if (typeof r.notQueued === 'string') lines.push(`  warning: Knowledge base ${name}: ${changed.join(', ')} changed, but its documents keep their old chunks: ${r.notQueued}`)
+  if (kept.length) lines.push(`  warning: Knowledge base ${name}: ${kept.join(', ')} ${kept.length === 1 ? 'was' : 'were'} added as text and keep${kept.length === 1 ? 's' : ''} ${kept.length === 1 ? 'its' : 'their'} chunks; add ${kept.length === 1 ? 'it' : 'them'} again to chunk with the new settings`)
+  return lines
+}
+
 export async function applyKnowledge(
   project: LocalProject,
   target: Extract<SyncTarget, { kind: 'knowledge' }>,
@@ -703,7 +946,7 @@ export async function applyKnowledge(
   const notes: string[] = []
   const id = bases.find((b) => b.name === name)?.id
   if (local?.creds.workspaceKey && id) {
-    const { settings, warnings } = knowledgeSettings(doc, await localModels(local), name)
+    const { settings, warnings } = knowledgeSettings(doc, await localModels(local), name, await embeddingsDiffer(project.root, local))
     notes.push(...warnings)
     if (Object.keys(settings).length) {
       const failed = await fetch(new URL(`/v1/workspace-knowledge/${encodeURIComponent(id)}`, local.serviceUrl), {
@@ -711,7 +954,13 @@ export async function applyKnowledge(
         headers: { authorization: `Bearer ${local.creds.workspaceKey}`, 'content-type': 'application/json' },
         body: JSON.stringify(settings),
       })
-        .then(async (res) => (res.ok ? null : `${res.status} ${(await res.text()).slice(0, 200)}`))
+        .then(async (res) => {
+          if (!res.ok) return `${res.status} ${(await res.text()).slice(0, 200)}`
+          // A chunking change chunks the documents again: said, so the base is not read as unchanged.
+          const body = (await res.json().catch(() => null)) as { rechunk?: unknown } | null
+          notes.push(...rechunkNotes(name, body?.rechunk))
+          return null
+        })
         .catch((err: Error) => err.message)
       if (failed) notes.push(`  warning: Knowledge base ${name} keeps the runtime’s own retrieval settings: its settings were refused (${failed})`)
     }
@@ -732,9 +981,13 @@ export async function applyKnowledge(
   // The documents, the knowledge base's folders as subfolders (`Policies/Returns/terms.pdf`).
   const { documentPath, documentPaths, folderPaths, splitDocumentPath } = await import('./local-knowledge-documents')
   const documents = documentPaths(project.root, target.name)
-  if (!documents.length) return await done({ ok: true, output: '' })
+  // No documents: an Agent searching it finds nothing. Said with the command that brings them.
+  if (!documents.length) {
+    notes.push(`  warning: ${emptyKnowledgeNote(project.root, target.name, name)}`)
+    return await done({ ok: true, output: '' })
+  }
   const sources = await run(['knowledge', 'sources', name, '--json', ...p])
-  const listedSources = parseJson<Array<{ fileName?: string; folderId?: string | null }>>(sources.output) ?? []
+  const listedSources = parseJson<Array<{ id?: string; fileName?: string; folderId?: string | null; status?: string; updatedAt?: string }>>(sources.output) ?? []
   const key = local?.creds.workspaceKey
   const http = async (method: string, path: string, body?: FormData | Record<string, unknown>) => {
     const res = await fetch(new URL(path, local!.serviceUrl), {
@@ -752,6 +1005,9 @@ export async function applyKnowledge(
     ? folderPaths((((await http('GET', `/v1/workspace-knowledge/${encodeURIComponent(id)}/folders`).catch(() => null))?.folders ?? []) as Array<{ id: string; parentId?: string | null; name: string }>))
     : new Map<string, string>()
   const have = new Set(listedSources.map((s) => documentPath(s.folderId ? folders.get(s.folderId) : null, s.fileName ?? '')))
+  // A document the runtime holds pending or processing with no ingestion behind it (a rollback took its
+  // reading with the database it replaced) is queued to be read again: uploading it again would add a second.
+  if (key && id) notes.push(...(await requeueStuckDocuments(project, local!, name, id, listedSources)))
   const fresh = documents.filter((f) => !have.has(f))
   if (!fresh.length) return await done({ ok: true, output: '' })
   const top = fresh.filter((f) => !f.includes('/'))
@@ -800,6 +1056,33 @@ export async function applyKnowledge(
   return await done({ ok: true, output: lines.join('\n') })
 }
 
+/**
+ * The documents of one knowledge base stuck pending or processing with no
+ * ingestion behind them (`stuckSources`: unsettled since before the last
+ * restore, or for half an hour), queued to be read again. Returns the lines
+ * for the build.
+ */
+async function requeueStuckDocuments(
+  project: LocalProject,
+  local: { serviceUrl: string; creds: LocalCredentials },
+  name: string,
+  baseId: string,
+  listed: Array<{ id?: string; fileName?: string; status?: string; updatedAt?: string }>,
+): Promise<string[]> {
+  const { localIngestApi, requeueSources, shellArg, stuckLine, stuckSources } = await import('./local-knowledge-ingestion')
+  const { readBaseline } = await import('./local-db-snapshot')
+  const api = localIngestApi(local.serviceUrl, local.creds)
+  if (!api) return []
+  const sources = listed.filter((s) => s.id).map((s) => ({ base: name, baseId, id: s.id!, fileName: s.fileName ?? s.id!, status: String(s.status ?? ''), ...(s.updatedAt ? { updatedAt: s.updatedAt } : {}) }))
+  const stuck = stuckSources(sources, { restoredAt: readBaseline(project, local.creds.organizationId)?.restoredAt })
+  if (!stuck.length) return []
+  const { requeued, refused } = await requeueSources(api, stuck)
+  return [
+    ...(requeued.length ? [`  note: Knowledge base ${name}: queued ${requeued.map((s) => s.fileName).join(', ')} to be read again: ${requeued.length === 1 ? 'it was' : 'they were'} ${requeued.length === 1 ? requeued[0]!.status : 'pending or processing'} with no ingestion behind ${requeued.length === 1 ? 'it' : 'them'} (\`frontera knowledge sources ${shellArg(name)}\` shows each as pending, then ready)`] : []),
+    ...refused.map((r) => `  warning: ${stuckLine(r.source)} (re-queuing it was refused: ${r.reason})`),
+  ]
+}
+
 /**
  * A knowledge base's quality checks on the runtime (`local-quality-checks.ts`),
  * their documents by this runtime's ids. Returns the lines for the build.
@@ -1024,21 +1307,35 @@ async function setToolPolicy(local: { serviceUrl: string; creds: LocalCredential
 }
 
 /**
- * Promote a workflow's latest draft to live on the local runtime. Returns the
- * version promoted, or null when there was none or it was refused.
+ * Promote a workflow's version to live on the local runtime: `version` (the
+ * one `local dev` pushed its file as) when given, else the newest draft, but
+ * only one newer than the live version. After a promotion the newest draft
+ * can be an older push, and promoting that would put stale code live. Returns
+ * the version promoted, or null when there was none, it was live already, or
+ * it was refused.
  */
-export async function promoteWorkflow(serviceUrl: string, creds: LocalCredentials, slug: string): Promise<number | null> {
+export async function promoteWorkflow(serviceUrl: string, creds: LocalCredentials, slug: string, version?: number, opts: { onlyIfLive?: boolean } = {}): Promise<number | null> {
   if (!creds.workspaceKey) return null
   const call = (path: string, method: string) =>
     fetch(new URL(path, serviceUrl), { method, headers: { authorization: `Bearer ${creds.workspaceKey}`, 'content-type': 'application/json' }, body: method === 'POST' ? '{}' : undefined })
   const res = await call(`/v1/workflows/${encodeURIComponent(slug)}`, 'GET')
   if (!res.ok) return null
-  const n = ((await res.json()) as { data?: { latestDraftNumber?: number | null } }).data?.latestDraftNumber
+  const found = ((await res.json()) as { data?: { latestDraftNumber?: number | null; liveVersion?: number | null } }).data
+  // `onlyIfLive`: a workflow with no live version stays a draft (its triggers stay unarmed).
+  if (opts.onlyIfLive && !found?.liveVersion) return null
+  const n = promotionTarget(found?.latestDraftNumber ?? null, found?.liveVersion ?? null, version)
   if (!n) return null
   const promoted = await call(`/v1/workflows/${encodeURIComponent(slug)}/versions/${n}/promote`, 'POST')
   return promoted.ok ? n : null
 }
 
+/** Which version a promotion makes live: the pushed one, else a draft newer than the live one; null when nothing should change. */
+export function promotionTarget(latestDraft: number | null, live: number | null, pushed?: number): number | null {
+  if (pushed) return pushed === live ? null : pushed
+  if (!latestDraft) return null
+  return live && latestDraft < live ? null : latestDraft
+}
+
 /** The project's object type files by API name, parsed; unreadable ones are left out. */
 function projectObjectTypes(root: string): Map<string, Record<string, unknown>> {
   const dir = join(root, 'blueprint', 'object-types')
@@ -1086,15 +1383,25 @@ export async function applyBindings(project: LocalProject, target: Extract<SyncT
   // An Agent runs only a workflow's live version, and local dev pushes drafts: on this
   // one-person runtime, a workflow an Agent may start is promoted so the binding holds.
   const promote = async (slug: string): Promise<boolean> => {
-    const n = await promoteWorkflow(serviceUrl, creds, slug)
+    // The version the workflow's file was pushed as, not whatever draft is newest.
+    const n = await promoteWorkflow(serviceUrl, creds, slug, pushedWorkflowVersion(project, creds.organizationId, slug))
     if (n) notes.push(`  warning: promoted workflow ${slug} v${n} so ${target.slug} can start it`)
     return n !== null
   }
   const failures: string[] = []
   const settings = (row: Record<string, unknown>, keys: string[]) => Object.fromEntries(keys.filter((k) => row[k] !== undefined).map((k) => [k, row[k]]))
+  // The last build: a Function of the project's that failed to build here, and a type the runtime refused.
+  const build = loadBuild(project, creds.organizationId)
   for (const row of doc.functions ?? []) {
     const ref = typeof row.function === 'string' ? parseRef(row.function) : null
     if (!ref || ref.kind !== 'function') continue
+    // A Function of the project that does not build here: the Agent goes without it, and gets it once it builds.
+    const fn = build[`function:${ref.name}/`] ?? build[`function:${ref.name}.ts`]
+    if (fn?.status === 'failed') {
+      const why = oneLine(fn.error ?? 'it failed to build')
+      notes.push(`  warning: ${target.slug} goes without the Function ${ref.name} here until it builds: ${why.charAt(0).toLowerCase()}${why.slice(1)}`)
+      continue
+    }
     const failed = await put(`/v1/functions/${encodeURIComponent(ref.name)}/bindings/${encodeURIComponent(target.slug)}`, settings(row, ['enabled', 'requiresApproval', 'waitSeconds']))
     if (failed) failures.push(`  ${row.function}: ${failed}`)
   }
@@ -1121,9 +1428,13 @@ export async function applyBindings(project: LocalProject, target: Extract<SyncT
       creds,
       leftOff: (apiName) => {
         const type = types.get(apiName)
-        return type && objectTypeFit(type, () => true).leftOff ? 'it reads the platform’s media files' : null
+        if (type && objectTypeFit(type, () => true).leftOff) return 'it reads the platform’s media files'
+        const refused = build.blueprint?.objects?.[apiName]?.refused
+        return refused ? `the local runtime refused it: ${refused}` : null
       },
       inProject: (apiName) => types.has(apiName),
+      // Assumed as read because the pull couldn't read them: what the runtime already gives is kept.
+      keepHeld: unread,
     })
     failures.push(...granted.failures)
     notes.push(...granted.notes)