@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/state/step-executions.d.ts

@@ -4,16 +4,28 @@
  * module.
  */
 import type { ResultAsync } from "neverthrow";
+import type { QueryConfig } from "pg";
 import { type DbError } from "../lib/db-result.js";
 import type { Querier } from "./db.js";
-import type { StepExecutionRow } from "./schema.js";
-export interface SeedStepExecutionRow {
+import { type StepExecutionRow } from "./schema.js";
+/**
+ * The row-reading surface of this module: one query over the text or config form, whose rows the
+ * mapStepExecutionRow parser types. A computed test fake satisfies this shape directly, where the
+ * row-generic of `Querier` cannot be implemented by a fake that computes its rows.
+ */
+export type StepRowQuerier = {
+    query(queryTextOrConfig: string | QueryConfig, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+        rowCount: number | null;
+    }>;
+};
+export type SeedStepExecutionRow = {
     runId: string;
     stepId: string;
     analysisId: string;
     wave: number;
     agentId: string;
-}
+};
 /**
  * Seed one `pending` row per plan step at run start (`started_at` NULL — no
  * attempt has happened yet; `attempts`/`hit_max_steps` lean on their column
@@ -25,7 +37,7 @@ export interface SeedStepExecutionRow {
  * honest done/total progress including not-yet-started steps.
  */
 export declare function seedStepExecutions(pool: Querier, rows: readonly SeedStepExecutionRow[]): ResultAsync<void, DbError>;
-export interface InsertStepExecutionInput {
+export type InsertStepExecutionInput = {
     runId: string;
     stepId: string;
     analysisId: string;
@@ -33,14 +45,14 @@ export interface InsertStepExecutionInput {
     agentId: string;
     /** DBOS child workflow id (`"${parent}-${N}"`). Optional for legacy callers. */
     childWorkflowId?: string | null;
-}
+};
 export declare function insertStepExecution(pool: Querier, input: InsertStepExecutionInput): ResultAsync<void, DbError>;
 /**
  * Look up a step execution by its DBOS child workflow id. The parent
  * scheduler uses this to find the step row corresponding to a CANCELLED
  * child without holding the runId/stepId map in memory across recovery.
  */
-export interface UpdateStepExecutionInput {
+export type UpdateStepExecutionInput = {
     /** Step status — `running` is allowed for mid-flight telemetry updates (retries). */
     status: "running" | "completed" | "failed" | "skipped" | "canceled" | "blocked";
     durationMs?: number | null;
@@ -55,7 +67,7 @@ export interface UpdateStepExecutionInput {
     finishReason?: string | null;
     /** True when `stepsUsed === maxSteps`. Stored as 0/1 in SQLite. */
     hitMaxSteps?: boolean | null;
-}
+};
 /**
  * Update a step execution row. Columns are written conditionally so callers
  * can bump `attempts` / `lastErrorClass` on retry without clobbering timing
@@ -74,4 +86,13 @@ export declare function updateStepExecution(pool: Querier, runId: string, stepId
  * these steps never started.
  */
 export declare function sweepPendingStepExecutions(pool: Querier, runId: string): ResultAsync<void, DbError>;
-export declare function queryStepsByRun(pool: Querier, runId: string): ResultAsync<StepExecutionRow[], DbError>;
+/**
+ * Settle a run's still-`running` rows to `canceled` after an engine cancel.
+ * A canceled child re-raises before it writes a terminal row, so this is the
+ * only writer for a step that the cancel cut. `canceled`, not `skipped`: these
+ * steps started. The `status = 'running'` guard keeps a terminal row that a
+ * child wrote first. `started_at` and `completed_at` are ISO 8601 `TEXT`, so
+ * the duration casts both; it is NULL when `started_at` is NULL.
+ */
+export declare function cancelRunningStepExecutions(pool: Querier, runId: string, reason: string): ResultAsync<void, DbError>;
+export declare function queryStepsByRun(pool: StepRowQuerier, runId: string): ResultAsync<StepExecutionRow[], DbError>;

package/dist/state/step-executions.js

@@ -4,6 +4,7 @@
  * module.
  */
 import { tryMutation, tryQuery } from "../lib/db-result.js";
+import { StepExecutionRowSchema } from "./schema.js";
 /**
  * Seed one `pending` row per plan step at run start (`started_at` NULL — no
  * attempt has happened yet; `attempts`/`hit_max_steps` lean on their column
@@ -136,6 +137,28 @@ export function sweepPendingStepExecutions(pool, runId) {
         });
     });
 }
+/**
+ * Settle a run's still-`running` rows to `canceled` after an engine cancel.
+ * A canceled child re-raises before it writes a terminal row, so this is the
+ * only writer for a step that the cancel cut. `canceled`, not `skipped`: these
+ * steps started. The `status = 'running'` guard keeps a terminal row that a
+ * child wrote first. `started_at` and `completed_at` are ISO 8601 `TEXT`, so
+ * the duration casts both; it is NULL when `started_at` is NULL.
+ */
+export function cancelRunningStepExecutions(pool, runId, reason) {
+    const now = new Date().toISOString();
+    return tryMutation("stepExecutions.cancelRunningStepExecutions", async () => {
+        await pool.query({
+            text: `UPDATE cortex_step_executions
+          SET status = 'canceled',
+              completed_at = $2::text,
+              duration_ms = (EXTRACT(EPOCH FROM ($2::text::timestamptz - started_at::timestamptz)) * 1000)::bigint,
+              error = $3
+          WHERE run_id = $1 AND status = 'running'`,
+            values: [runId, now, reason],
+        });
+    });
+}
 export function queryStepsByRun(pool, runId) {
     return tryQuery("stepExecutions.queryStepsByRun", async () => {
         const result = await pool.query({
@@ -152,7 +175,7 @@ export function queryStepsByRun(pool, runId) {
     });
 }
 function mapStepExecutionRow(row) {
-    return {
+    return StepExecutionRowSchema.parse({
         runId: row.run_id,
         stepId: row.step_id,
         analysisId: row.analysis_id,
@@ -161,14 +184,15 @@ function mapStepExecutionRow(row) {
         status: row.status,
         startedAt: row.started_at ?? null,
         completedAt: row.completed_at ?? null,
-        durationMs: row.duration_ms === null || row.duration_ms === undefined ? null : Number(row.duration_ms),
+        // `duration_ms` is bigint, which `pg` delivers as a string; the schema wants the number.
+        durationMs: row.duration_ms === undefined || row.duration_ms === null ? null : Number(row.duration_ms),
         error: row.error ?? null,
-        attempts: row.attempts ?? 1,
+        attempts: row.attempts === undefined || row.attempts === null ? undefined : Number(row.attempts),
         lastErrorClass: row.last_error_class ?? null,
         finishReason: row.finish_reason ?? null,
         hitMaxSteps: row.hit_max_steps === 1 || row.hit_max_steps === true,
         blockedReason: row.blocked_reason ?? null,
         sandboxRef: row.sandbox_ref ?? null,
         childWorkflowId: row.child_workflow_id ?? null,
-    };
+    });
 }

package/dist/state/tool-outputs.d.ts

@@ -1,4 +1,4 @@
 /** The Postgres realization of the tool output store of the loop, over `cortex_tool_outputs`. */
-import type { Pool } from "pg";
+import type { Querier } from "./db.js";
 import type { ToolOutputStore } from "../loop/tool-output.js";
-export declare function createToolOutputStore(pool: Pool): ToolOutputStore;
+export declare function createToolOutputStore(pool: Querier): ToolOutputStore;

package/dist/state/tool-outputs.js

@@ -1,14 +1,15 @@
 /** The Postgres realization of the tool output store of the loop, over `cortex_tool_outputs`. */
 import { tryMutation, tryQuery } from "../lib/db-result.js";
 function toKeptToolOutput(row) {
+    const threadIdField = row.thread_id === null ? undefined : { threadId: row.thread_id };
     return {
         analysisId: row.analysis_id,
         ref: row.ref,
         toolName: row.tool_name,
         toolCallId: row.tool_call_id,
-        ...(row.thread_id === null ? {} : { threadId: row.thread_id }),
         content: row.content,
         totalLength: row.total_length,
+        ...threadIdField,
     };
 }
 export function createToolOutputStore(pool) {

package/dist/state/vector-store.d.ts

@@ -13,7 +13,7 @@
  * `search_{snake}` shape we ever produce.
  */
 import { ResultAsync } from "neverthrow";
-import type { Pool } from "pg";
+import type { Querier } from "./db.js";
 import { type DbError } from "../lib/db-result.js";
 /**
  * Whether `name` may be interpolated into a statement as an identifier. Shared
@@ -21,24 +21,24 @@ import { type DbError } from "../lib/db-result.js";
  * shape — one invariant, one place to read it.
  */
 export declare function isSqlIdentifier(name: string): boolean;
-export interface CreateIndexInput {
+export type CreateIndexInput = {
     readonly indexName: string;
     readonly dimension: number;
     readonly metric?: "cosine" | "l2" | "ip";
-}
-export interface BuildIndexInput {
+};
+export type BuildIndexInput = {
     readonly indexName: string;
     readonly metric?: "cosine" | "l2" | "ip";
     readonly indexConfig: {
         readonly type: "hnsw";
     };
-}
-export interface UpsertInput {
+};
+export type UpsertInput = {
     readonly indexName: string;
     readonly vectors: readonly number[][];
     readonly metadata?: readonly Record<string, unknown>[];
     readonly ids?: readonly string[];
-}
+};
 /**
  * A narrow delete surface: every entry of one index whose metadata `type` is named.
  *
@@ -47,26 +47,26 @@ export interface UpsertInput {
  * has to be unable to reach another's — a general predicate would make that a review
  * question rather than a type error.
  */
-export interface DeleteByTypeInput {
+export type DeleteByTypeInput = {
     readonly indexName: string;
     readonly types: readonly string[];
-}
-export interface QueryInput {
+};
+export type QueryInput = {
     readonly indexName: string;
     readonly queryVector: readonly number[];
     readonly topK: number;
     readonly filter?: Record<string, unknown>;
-}
-export interface QueryResult {
+};
+export type QueryResult = {
     readonly id: string;
     readonly score: number;
     readonly metadata: Record<string, unknown>;
-}
-export interface VectorStore {
+};
+export type VectorStore = {
     createIndex(input: CreateIndexInput): ResultAsync<void, DbError>;
     buildIndex(input: BuildIndexInput): ResultAsync<void, DbError>;
     upsert(input: UpsertInput): ResultAsync<void, DbError>;
     deleteByType(input: DeleteByTypeInput): ResultAsync<void, DbError>;
     query(input: QueryInput): ResultAsync<QueryResult[], DbError>;
-}
-export declare function createVectorStore(pool: Pool): VectorStore;
+};
+export declare function createVectorStore(pool: Querier): VectorStore;

package/dist/state/vector-store.js

@@ -14,6 +14,7 @@
  */
 import { okAsync } from "neverthrow";
 import { tryMutation, tryQuery } from "../lib/db-result.js";
+import { presentAt } from "../lib/present.js";
 /**
  * The identifier shape and length the harness may interpolate into a statement.
  * An identifier cannot be a bind parameter, so a name reaching SQL has to be
@@ -25,7 +26,13 @@ import { tryMutation, tryQuery } from "../lib/db-result.js";
  * a name that matches it has one byte per character and `length` is the byte count
  * the limit is measured in.
  */
-const SQL_IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
+function isSqlIdentifierShape(name) {
+    if (name.length === 0)
+        return false;
+    const isLowerOrUnderscore = (char) => (char >= "a" && char <= "z") || char === "_";
+    const isWordChar = (char) => isLowerOrUnderscore(char) || (char >= "0" && char <= "9");
+    return isLowerOrUnderscore(name.charAt(0)) && Array.from(name).every(isWordChar);
+}
 const MAX_SQL_IDENTIFIER_BYTES = 63;
 /**
  * Whether `name` may be interpolated into a statement as an identifier. Shared
@@ -33,7 +40,7 @@ const MAX_SQL_IDENTIFIER_BYTES = 63;
  * shape — one invariant, one place to read it.
  */
 export function isSqlIdentifier(name) {
-    return SQL_IDENTIFIER.test(name) && name.length <= MAX_SQL_IDENTIFIER_BYTES;
+    return isSqlIdentifierShape(name) && name.length <= MAX_SQL_IDENTIFIER_BYTES;
 }
 function assertIdent(name) {
     if (!isSqlIdentifier(name)) {
@@ -56,11 +63,8 @@ export function createVectorStore(pool) {
            )`);
             });
         },
-        buildIndex({ indexName, indexConfig }) {
+        buildIndex({ indexName }) {
             assertIdent(indexName);
-            if (indexConfig.type !== "hnsw") {
-                throw new Error(`vector-store: unsupported index type "${indexConfig.type}"`);
-            }
             // m/ef_construction default to 8/32.
             return tryMutation("vectorStore.buildIndex", async () => {
                 await pool.query(`CREATE INDEX IF NOT EXISTS "${indexName}_vector_idx"
@@ -76,7 +80,7 @@ export function createVectorStore(pool) {
             const finalIds = ids ?? vectors.map(() => crypto.randomUUID());
             return tryMutation("vectorStore.upsert", async () => {
                 for (let i = 0; i < vectors.length; i++) {
-                    const vec = toVectorLiteral(vectors[i]);
+                    const vec = toVectorLiteral(presentAt(vectors, i, "the vector at the index"));
                     const meta = JSON.stringify(metadata?.[i] ?? {});
                     await pool.query(`INSERT INTO "${indexName}" (vector_id, embedding, metadata)
              VALUES ($1, $2::vector, $3::jsonb)

package/dist/tasks/data-profile-absorb.d.ts

@@ -31,7 +31,7 @@
 import type { DataProfileResult } from "../contracts/data-profile.js";
 import type { SetMenu } from "../input-scan/menu.js";
 import type { DetectedSets } from "../input-scan/set-types.js";
-import type { MenuOperation } from "../schemas/data-profile-schemas.js";
+import type { MenuOperationInput } from "../schemas/data-profile-schemas.js";
 import { type ProfileResolution } from "./data-profile-resolve.js";
 /** Delta paths named in the repair briefing before the tail folds into a count. */
 export declare const MAX_DELTA_PATHS = 30;
@@ -43,11 +43,11 @@ export type AbsorbOutcome = {
     readonly reason: string;
 } | {
     readonly kind: "full";
-    readonly operations: readonly MenuOperation[];
+    readonly operations: readonly MenuOperationInput[];
     readonly resolution: ProfileResolution;
 } | {
     readonly kind: "partial";
-    readonly operations: readonly MenuOperation[];
+    readonly operations: readonly MenuOperationInput[];
     readonly resolution: ProfileResolution;
     /** Kept files the replayed recipe does not account for — what the agent is woken for. */
     readonly delta: readonly string[];

package/dist/tasks/data-profile-absorb.js

@@ -51,17 +51,19 @@ function keptPaths(detected) {
  */
 function annotationOf(group, kept) {
     const annotations = (group.memberAnnotations ?? []).filter((entry) => kept.has(entry.path));
-    return {
+    const annotation = {
         name: group.name,
         memberRepresents: group.memberRepresents,
         description: group.description,
         role: group.role,
         category: group.category,
-        ...(group.categoryLabel ? { categoryLabel: group.categoryLabel } : {}),
-        ...(group.subtype ? { subtype: group.subtype } : {}),
-        ...(group.categoryReason ? { categoryReason: group.categoryReason } : {}),
-        ...(annotations.length > 0 ? { memberAnnotations: annotations.map((entry) => ({ path: entry.path, note: entry.note })) } : {}),
+        categoryLabel: group.categoryLabel,
+        subtype: group.subtype,
+        categoryReason: group.categoryReason,
     };
+    if (annotations.length > 0)
+        annotation.memberAnnotations = annotations.map((entry) => ({ path: entry.path, note: entry.note }));
+    return annotation;
 }
 class StrandedRecipe extends Error {
 }
@@ -140,21 +142,23 @@ function replayDimension(ctx, dimension) {
         if (!slot) {
             throw new StrandedRecipe(`dimension "${dimension.label}": the template "${binding.template}" no longer carries a slot at position ${binding.slotIndex}`);
         }
-        return { kind: "slot", setId: set.id, slotId: slot.id, ...(observation.note ? { note: observation.note } : {}) };
+        return { kind: "slot", setId: set.id, slotId: slot.id, note: observation.note };
     });
-    return {
+    const reconciliations = dimension.reconciliations?.map((entry) => ({ ...entry }));
+    const replayed = {
         label: dimension.label,
         category: dimension.category,
-        ...(dimension.categoryLabel ? { categoryLabel: dimension.categoryLabel } : {}),
-        ...(dimension.scope ? { scope: dimension.scope } : {}),
-        ...(dimension.description ? { description: dimension.description } : {}),
+        categoryLabel: dimension.categoryLabel,
+        scope: dimension.scope,
+        description: dimension.description,
         observations,
-        ...(dimension.reconciliations && dimension.reconciliations.length > 0
-            ? { reconciliations: dimension.reconciliations.map((entry) => ({ ...entry })) }
-            : {}),
-        ...(dimension.nestsUnder ? { nestsUnder: { ...dimension.nestsUnder } } : {}),
-        ...(dimension.treatmentReason ? { treatmentReason: dimension.treatmentReason } : {}),
+        reconciliations,
+        nestsUnder: dimension.nestsUnder === undefined ? undefined : { ...dimension.nestsUnder },
+        treatmentReason: dimension.treatmentReason,
     };
+    if (reconciliations && reconciliations.length > 0)
+        replayed.reconciliations = reconciliations;
+    return replayed;
 }
 /** Every group id the authored steps named, including a value-mapped split's per-value groups. */
 function namedGroupIds(steps) {
@@ -208,11 +212,12 @@ export function absorbRecipe(prior, detected, menu) {
     }
     const submission = {
         operations,
-        ...(dimensions.length > 0 ? { dimensions } : {}),
         analysisSummary: prior.summary,
         domain: prior.domain ?? "",
         organism: prior.organism ?? null,
     };
+    if (dimensions.length > 0)
+        submission.dimensions = dimensions;
     // Final round by construction: no agent is awake to repair anything this raises, so a
     // contested file sweeps rather than being awarded to whichever step ran first.
     const resolution = resolveProfileSubmission(submission, detected, menu, { finalRound: true });

package/dist/tasks/data-profile-activity.d.ts

@@ -47,7 +47,7 @@ export type ActivityWrite = (part: unknown) => Promise<void>;
  * manifest, a fallback file description) are logged because neither warrants
  * interrupting the activity line.
  */
-export interface ProfileActivityEmitter {
+export type ProfileActivityEmitter = {
     /** Reported before the sandbox is created — the longest wait in a profile, and the one that precedes the agent entirely. */
     sandboxInit(): Promise<void>;
     /**
@@ -72,16 +72,16 @@ export interface ProfileActivityEmitter {
      * phrases are this capability's observable contract, and a call site that
      * composed its own is a call site that can drift from it.
      */
-    forTool(name: string, input: unknown, resolveDetail?: ToolDetailResolver): Promise<void>;
+    forTool(toolUseId: string, name: string, input: unknown, resolveDetail?: ToolDetailResolver): Promise<void>;
     /** Reported for the vector-store pass that indexes per-file descriptions. */
     indexing(): Promise<void>;
     /** The success terminal. Emitted only after the terminal ledger write has landed. */
     complete(): Promise<void>;
     /** The failure terminal, carrying the same user-safe reason the ledger receives. */
     failed(reason: string): Promise<void>;
-}
+};
 /** Identity the emitted parts carry — the workflow's synthetic frame, not a real run. */
-export interface ProfileActivityFrame {
+export type ProfileActivityFrame = {
     /**
      * The constant literal the data-profile workflow uses as its run id. It is the
      * same string for every analysis, so it identifies nothing; consumers are
@@ -92,7 +92,7 @@ export interface ProfileActivityFrame {
     readonly runId: string;
     /** The constant literal step id of the profile's single synthetic step. */
     readonly stepId: string;
-}
+};
 /**
  * Build the profile's activity channel over `write`.
  *

package/dist/tasks/data-profile-activity.js

@@ -19,7 +19,7 @@
  * anything that throws on the way there reaches the failure path having emitted
  * no terminal at all.
  */
-import { activityEmission, activityForTool } from "../sandbox/sandbox-step-translate.js";
+import { activityEmission, activityForTool, toolActivityKey } from "../sandbox/sandbox-step-translate.js";
 /**
  * Build the profile's activity channel over `write`.
  *
@@ -47,10 +47,10 @@ export function createProfileActivityEmitter(write, frame, logger, now) {
             logger.warn("run-event write failed (non-fatal)", { phase, ...logger.errorFields(err) });
         }
     };
-    const emit = async (phase, activity) => {
-        const position = seq++;
+    const emit = async (phase, activity, toolUseId) => {
+        const key = toolUseId === undefined ? seq++ : toolActivityKey(toolUseId);
         const at = new Date(await now()).toISOString();
-        const parts = activityEmission(frame, position, phase, activity, at);
+        const parts = activityEmission(frame, key, phase, activity, at);
         await writeAlone(parts.activity, phase);
         await writeAlone(parts.entry, phase);
     };
@@ -58,7 +58,7 @@ export function createProfileActivityEmitter(write, frame, logger, now) {
         sandboxInit: () => emit("sandbox-init", "Starting sandbox"),
         scanning: () => emit("executing", "Scanning input files"),
         agentStarting: () => emit("executing", "Running data-profiler"),
-        forTool: (name, input, resolveDetail) => emit("executing", activityForTool(name, input, resolveDetail)),
+        forTool: (toolUseId, name, input, resolveDetail) => emit("executing", activityForTool(name, input, resolveDetail), toolUseId),
         indexing: () => emit("indexing", "Indexing input descriptions for search"),
         complete: () => emit("complete", "Profile complete"),
         failed: (reason) => emit("failed", reason),

package/dist/tasks/data-profile-index.d.ts

@@ -34,18 +34,18 @@ export declare const MAX_ENTITY_ENTRIES = 20000;
  * own types and are untouched.
  */
 export declare const PROFILE_INDEX_TYPES: readonly ["input-group", "input-dimension", "input", "input-kind"];
-export interface ProfileIndexEntry {
+export type ProfileIndexEntry = {
     readonly id: string;
     readonly text: string;
     readonly metadata: Record<string, unknown>;
-}
-export interface BuildProfileIndexArgs {
+};
+export type BuildProfileIndexArgs = {
     readonly analysisId: string;
     /** The profile as persisted. Whichever era wrote it, the entries are derived from it alone. */
     readonly result: DataProfileResult;
     /** The scan the profile was taken against — the source of a legacy profile's entity value set. */
     readonly scan?: InputScan;
-}
+};
 /**
  * Build every index entry for a completed profile. Deterministic and model-free: each
  * entry's text is templated from what the agent already wrote and what resolution already

package/dist/tasks/data-profile-index.js

@@ -20,6 +20,7 @@
  * entries (group, dimension, kind, entity) never do. That presence is the discriminator
  * `workspace_search` documents, so a consumer needs no id parsing to tell them apart.
  */
+import { presentFirst } from "../lib/present.js";
 import { dimensionCardinalities, profileDimensions, profileFileRecords, profileGroups } from "../app/data-profile-view.js";
 /** Entity entries built for a legacy profile. Past this the entity tier is a liability, not a search aid. */
 export const MAX_ENTITY_ENTRIES = 20_000;
@@ -36,19 +37,31 @@ export const PROFILE_INDEX_TYPES = ["input-group", "input-dimension", "input", "
 /** Group names named in one legacy entity entry's text. */
 const MAX_GROUPS_IN_ENTITY_TEXT = 6;
 function slug(value) {
-    return (value
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-|-$/g, "")
-        .slice(0, 60) || "unnamed");
+    let out = "";
+    let inRun = false;
+    for (const char of value.toLowerCase()) {
+        if (out.length >= SLUG_MAX_LENGTH)
+            break;
+        const isSlugChar = (char >= "a" && char <= "z") || (char >= "0" && char <= "9");
+        if (!isSlugChar) {
+            inRun = true;
+            continue;
+        }
+        if (inRun && out.length > 0)
+            out += "-";
+        inRun = false;
+        out += char;
+    }
+    return out.slice(0, SLUG_MAX_LENGTH) || "unnamed";
 }
+const SLUG_MAX_LENGTH = 60;
 function slotSummary(slot) {
     return { id: slot.id, location: slot.location, tokenClass: slot.tokenClass, distinctValues: slot.distinctValues };
 }
 function groupEntry(analysisId, group) {
     const category = group.categoryLabel ?? group.category;
     const facts = [`${group.count} members`, `${group.fileCount} files`, group.displayPattern].join(", ");
-    return {
+    const entry = {
         id: `/${analysisId}/group/${group.id}`,
         text: `${group.name} — one member is ${group.memberRepresents}. ${group.description} ${category} held as ${group.role}. (${facts})`,
         metadata: {
@@ -57,14 +70,16 @@ function groupEntry(analysisId, group) {
             name: group.name,
             role: group.role,
             category: group.category,
-            ...(group.categoryLabel ? { categoryLabel: group.categoryLabel } : {}),
+            categoryLabel: group.categoryLabel ? group.categoryLabel : undefined,
             pathPattern: group.displayPattern,
             count: group.count,
             fileCount: group.fileCount,
-            ...(group.slots && group.slots.length > 0 ? { slots: group.slots.map(slotSummary) } : {}),
-            ...(group.unclassified ? { unclassified: true } : {}),
+            slots: group.slots && group.slots.length > 0 ? group.slots.map(slotSummary) : undefined,
         },
     };
+    if (group.unclassified)
+        entry.metadata.unclassified = true;
+    return entry;
 }
 /** One observation as a searchable clause — where the dimension was seen, and what was seen there. */
 function observationSummary(observation) {
@@ -89,7 +104,7 @@ function dimensionEntry(analysisId, dimension) {
             type: "input-dimension",
             dimension: dimension.label,
             category: dimension.category,
-            ...(dimension.categoryLabel ? { categoryLabel: dimension.categoryLabel } : {}),
+            categoryLabel: dimension.categoryLabel ? dimension.categoryLabel : undefined,
             scope: dimension.scope,
             cardinalities: dimensionCardinalities(dimension),
             groups: [...new Set(dimension.observations.flatMap((observation) => (observation.kind === "slot" ? observation.groupIds : [])))],
@@ -101,7 +116,7 @@ function dimensionEntry(analysisId, dimension) {
  * resolves to a file that exists rather than to a synthetic key.
  */
 function memberEntry(analysisId, group, annotation) {
-    const format = group.formats.length === 1 ? group.formats[0].format : undefined;
+    const format = group.formats.length === 1 ? presentFirst(group.formats, "the single format").format : undefined;
     return {
         id: `/${analysisId}/${annotation.path}`,
         text: `${annotation.path} — ${annotation.note} In ${group.name}, where one member is ${group.memberRepresents}.`,
@@ -111,7 +126,7 @@ function memberEntry(analysisId, group, annotation) {
             group: group.id,
             groupName: group.name,
             category: group.category,
-            ...(format ? { format } : {}),
+            format: format ? format : undefined,
         },
     };
 }
@@ -154,7 +169,7 @@ function entityDimensionLabel(dimensions, distinct) {
     return widest?.label ?? "entity";
 }
 function kindEntry(analysisId, group) {
-    const facts = [`${group.count} files`, group.format, group.pattern].filter((fact) => Boolean(fact)).join(", ");
+    const facts = [`${group.count} files`, group.format, group.pattern].flatMap((fact) => (fact ? [fact] : [])).join(", ");
     return {
         id: `/${analysisId}/kind/${slug(group.name)}`,
         text: `${group.name} — ${group.description} One member is ${group.memberRepresents}. (${facts})`,
@@ -163,7 +178,7 @@ function kindEntry(analysisId, group) {
             kind: group.name,
             pathPattern: group.pattern,
             count: group.count,
-            ...(group.format ? { format: group.format } : {}),
+            format: group.format ? group.format : undefined,
         },
     };
 }
@@ -189,9 +204,9 @@ function fileEntry(analysisId, file) {
         metadata: {
             type: "input",
             path: file.path,
-            ...(file.dataType ? { dataType: file.dataType } : {}),
-            ...(file.format ? { format: file.format } : {}),
-            ...(file.tags ? { tags: file.tags } : {}),
+            dataType: file.dataType ? file.dataType : undefined,
+            format: file.format ? file.format : undefined,
+            tags: file.tags ? file.tags : undefined,
         },
     };
 }