@cosmicdrift/kumiko-framework 0.334.0 → 0.336.0

package/dist/search/meilisearch-adapter.js

@@ -39,6 +39,12 @@ export function createMeilisearchAdapter(options) {
     // always wins and is never overwritten by the lazy default — its promise
     // sits in the map exactly like a lazily-triggered one.
     const configuredTenants = new Map();
+    // Exact inverse of meilisearchTenantIndex. A bare startsWith(prefix) would also
+    // match a longer sibling prefix (`kumiko_` vs `kumiko_staging_`) sharing the
+    // instance; tenant ids never contain `_`, which excludes that sibling.
+    function isOwnTenantIndex(uid) {
+        return uid.startsWith(prefix) && /^t[0-9A-Za-z-]+$/.test(uid.slice(prefix.length));
+    }
     async function applyConfig(tenantId, config) {
         const index = client.index(meilisearchTenantIndex(prefix, tenantId));
         const fields = config.rankingFields ?? config.searchableFields;
@@ -124,18 +130,23 @@ export function createMeilisearchAdapter(options) {
             for (let offset = 0;; offset += INDEX_LIST_PAGE_SIZE) {
                 const page = await client.getIndexes({ limit: INDEX_LIST_PAGE_SIZE, offset });
                 for (const index of page.results) {
-                    if (index.uid.startsWith(prefix))
+                    if (isOwnTenantIndex(index.uid))
                         uids.push(index.uid);
                 }
                 if (page.results.length === 0 || offset + page.results.length >= page.total)
                     break;
             }
-            for (const uid of uids) {
-                await awaitSucceededTask(client.deleteIndex(uid), REMOVE_TOLERATED_ERROR_CODES);
+            // Cleared even when a delete throws midway: otherwise ensureConfigured treats the
+            // already-dropped tenants as configured and the next index() recreates an
+            // unconfigured index ("not filterable" on filtered search).
+            try {
+                for (const uid of uids) {
+                    await awaitSucceededTask(client.deleteIndex(uid), REMOVE_TOLERATED_ERROR_CODES);
+                }
+            }
+            finally {
+                configuredTenants.clear();
             }
-            // Otherwise ensureConfigured treats the dropped tenants as configured and the
-            // next index() recreates an unconfigured index ("not filterable" on filtered search).
-            configuredTenants.clear();
             return uids.length;
         },
         async removeBatch(tenantId, items) {

package/dist/search/purge-subject.js

@@ -12,7 +12,7 @@ import { isSelfPiiField } from "../crypto/is-self-pii-field.js";
 import { collectSearchableSubjectFields } from "../crypto/subject-resolver.js";
 import { resolveTableName } from "../db/entity-table-meta.js";
 import { executeRawQueryRead } from "../db/queries/raw-sql.js";
-import { tableExists } from "../db/schema-inspection.js";
+import { columnNamesOf, tableExists } from "../db/schema-inspection.js";
 import { toSnakeCase } from "../utils/case.js";
 function finalizePredicateParts(parts, params) {
     if (parts.length === 0)
@@ -140,8 +140,8 @@ subject) {
     const seen = new Set();
     for (const feature of features.values()) {
         for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
-            const fields = collectSearchableSubjectFields(entity);
-            if (fields.length === 0)
+            const declaredFields = collectSearchableSubjectFields(entity);
+            if (declaredFields.length === 0)
                 continue;
             const tableName = resolveTableName(entityName, entity, undefined);
             // Same post-eraseKey hazard as nullBlindIndexesForSubject (fw#2550):
@@ -149,6 +149,11 @@ subject) {
             // (and the audit event after it).
             if (!(await tableExists(db, tableName)))
                 continue;
+            // A migrated table can still lack a later-added searchable column.
+            const columns = await columnNamesOf(db, tableName);
+            const fields = declaredFields.filter((f) => columns.has(toSnakeCase(f)));
+            if (fields.length === 0)
+                continue;
             const predicate = buildSubjectPredicate(entity, fields, likePattern, entityName, subject);
             const rows = await collectMatchingRowsForEntity(db, tableName, predicate.sql, predicate.params);
             for (const row of rows) {

package/dist/stack/drain-event-consumers.js

@@ -17,6 +17,9 @@ export async function drainEventConsumers(stack, consumerNames, options) {
             "multiStreamProjection is wired for this stack.");
     }
     const maxPasses = options?.maxPasses ?? DEFAULT_MAX_PASSES;
+    if (!Number.isInteger(maxPasses) || maxPasses < 1) {
+        throw new Error("drainEventConsumers: maxPasses must be a positive integer");
+    }
     const target = await getEventsHighWaterMark(db);
     for (let pass = 0; pass < maxPasses; pass++) {
         await eventDispatcher.runOnce();

package/dist/stack/drain-jobs.d.ts

@@ -17,4 +17,6 @@ export type DrainJobsStack = {
     readonly eventDispatcher?: EventDispatcher;
     readonly jobRunner?: JobRunner;
 };
-export declare function drainJobs(stack: DrainJobsStack, tracker: JobFailureTracker): Promise<void>;
+export declare function drainJobs(stack: DrainJobsStack, tracker: JobFailureTracker, options?: {
+    readonly timeoutMs?: number;
+}): Promise<void>;

package/dist/stack/drain-jobs.js

@@ -12,6 +12,9 @@ const DRAIN_IDLE_POLL_MS = 25;
 // enqueue that lands just after the first idle read still gets picked up
 // by the second pass instead of racing straight past it.
 const REQUIRED_IDLE_PASSES = 2;
+// Below the 15s per-test budget so a stuck drain reports what is open rather
+// than surfacing as a bare test timeout.
+const DEFAULT_DRAIN_TIMEOUT_MS = 10_000;
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -47,6 +50,26 @@ export function createJobFailureTracker() {
         },
     };
 }
+// Diagnostic only: lets the deadline error name what was still open.
+async function describeLaggingConsumers(db, consumerNames) {
+    // skip: no shared consumers wired — nothing to catch up on.
+    if (consumerNames.length === 0)
+        return [];
+    const target = await getEventsHighWaterMark(db);
+    const lagging = [];
+    for (const name of consumerNames) {
+        const state = await getConsumerState(db, name);
+        if (state && state.lastProcessedEventId < target) {
+            lagging.push(`${name} (status=${state.status}, lastProcessedEventId=${state.lastProcessedEventId}, target=${target})`);
+        }
+    }
+    return lagging;
+}
+async function drainTimeoutError(db, consumerNames, timeoutMs, pending) {
+    const lagging = await describeLaggingConsumers(db, consumerNames);
+    return new Error(`drainJobs: not drained after ${timeoutMs}ms — pending jobs: ${pending}, ` +
+        `consumers behind: ${lagging.length === 0 ? "none" : lagging.join("; ")}`);
+}
 async function sharedConsumersCaughtUp(db, consumerNames) {
     // skip: no shared consumers wired — nothing to catch up on.
     if (consumerNames.length === 0)
@@ -66,8 +89,12 @@ async function sharedConsumersCaughtUp(db, consumerNames) {
     }
     return allCaughtUp;
 }
-export async function drainJobs(stack, tracker) {
+// Fails a stuck drain with a diagnosis instead of a generic test-runner timeout.
+// It only bounds the loop; it never replaces waiting for real work.
+export async function drainJobs(stack, tracker, options) {
     const { db, eventDispatcher, jobRunner } = stack;
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
     if (!jobRunner) {
         throw new Error("drainJobs: stack.jobRunner is undefined — pass `jobs: {...}` to setupTestStack and " +
             "register at least one r.job(...) so a runner is built.");
@@ -76,24 +103,39 @@ export async function drainJobs(stack, tracker) {
         .filter((consumer) => (consumer.delivery ?? "shared") === "shared")
         .map((consumer) => consumer.name);
     try {
-        let consecutiveIdlePasses = 0;
-        while (consecutiveIdlePasses < REQUIRED_IDLE_PASSES) {
-            await eventDispatcher?.runOnce();
-            const pending = await jobRunner.countPendingJobs();
-            const caughtUp = await sharedConsumersCaughtUp(db, sharedConsumerNames);
-            consecutiveIdlePasses = pending === 0 && caughtUp ? consecutiveIdlePasses + 1 : 0;
-            if (consecutiveIdlePasses < REQUIRED_IDLE_PASSES) {
-                await Promise.race([tracker.waitForActivity(), sleep(DRAIN_IDLE_POLL_MS)]);
+        try {
+            let consecutiveIdlePasses = 0;
+            while (consecutiveIdlePasses < REQUIRED_IDLE_PASSES) {
+                await eventDispatcher?.runOnce();
+                const pending = await jobRunner.countPendingJobs();
+                const caughtUp = await sharedConsumersCaughtUp(db, sharedConsumerNames);
+                consecutiveIdlePasses = pending === 0 && caughtUp ? consecutiveIdlePasses + 1 : 0;
+                if (consecutiveIdlePasses < REQUIRED_IDLE_PASSES) {
+                    if (Date.now() > deadline) {
+                        throw await drainTimeoutError(db, sharedConsumerNames, timeoutMs, pending);
+                    }
+                    await Promise.race([tracker.waitForActivity(), sleep(DRAIN_IDLE_POLL_MS)]);
+                }
             }
         }
+        catch (err) {
+            // A failed job often kills its consumer, so the drain error is only the follow-up symptom.
+            if (tracker.failures.size === 0)
+                throw err;
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`${message}; ${describeJobFailures(tracker)}`, { cause: err });
+        }
         if (tracker.failures.size > 0) {
-            const details = [...tracker.failures.values()]
-                .map((failure) => `${failure.jobName}: ${failure.error}`)
-                .join("; ");
-            throw new Error(`drainJobs: job(s) failed: ${details}`);
+            throw new Error(`drainJobs: ${describeJobFailures(tracker)}`);
         }
     }
     finally {
         tracker.clear();
     }
 }
+function describeJobFailures(tracker) {
+    const details = [...tracker.failures.values()]
+        .map((failure) => `${failure.jobName}: ${failure.error}`)
+        .join("; ");
+    return `job(s) failed: ${details}`;
+}

package/dist/stack/table-helpers.js

@@ -117,12 +117,6 @@ function renderColumnType(col) {
  * rebuilding it.
  */
 export async function resetEventStore(stack, extraTables = []) {
-    // A pass the dispatcher's own timer/LISTEN already started (from a
-    // preceding test) may still be writing into the tables truncated below —
-    // drain it first so the TRUNCATE never races a write it didn't cause.
-    if (stack.eventDispatcher) {
-        await stack.eventDispatcher.drain();
-    }
     const frameworkTables = [
         "kumiko_events",
         "kumiko_event_consumers",
@@ -131,8 +125,16 @@ export async function resetEventStore(stack, extraTables = []) {
         "kumiko_projections",
     ];
     const extraNames = extraTables.map((t) => (typeof t === "string" ? t : tableNameOf(t)));
-    await truncateTablesRestartIdentity(stack.db, [...frameworkTables, ...extraNames]);
+    const truncateAndReregister = async () => {
+        await truncateTablesRestartIdentity(stack.db, [...frameworkTables, ...extraNames]);
+        await stack.eventDispatcher?.ensureRegistered();
+    };
+    // The dispatcher's own timer/LISTEN must not start a pass between the
+    // TRUNCATE and the consumer re-registration, so they are paused for the whole reset.
     if (stack.eventDispatcher) {
-        await stack.eventDispatcher.ensureRegistered();
+        await stack.eventDispatcher.withBackgroundPassesPaused(truncateAndReregister);
+    }
+    else {
+        await truncateAndReregister();
     }
 }

package/dist/testing/closed-connection-error.js

@@ -2,10 +2,9 @@
 // the production matcher checks driver-specific codes a fake can't reproduce.
 import postgres from "postgres";
 import { isClosedConnectionError } from "../bun-db/query.js";
+import { requireEnv } from "../stack/db.js";
 export function testDatabaseUrl() {
-    return (process.env["TEST_DATABASE_URL"] ??
-        process.env["DATABASE_URL"] ??
-        "postgresql://kumiko:kumiko@localhost:15432/kumiko_test");
+    return requireEnv("TEST_DATABASE_URL");
 }
 const MAX_WARMUP_ROUNDS = 10;
 const READS_PER_ROUND = 5;

package/dist/testing/wait-for.js

@@ -30,6 +30,7 @@ fn, options) {
                 // skip: condition already true — no further polling
                 return;
             }
+            lastError = undefined;
         }
         catch (err) {
             lastError = err;

package/dist/ui-types/index.d.ts

@@ -14,7 +14,7 @@ export { metricField } from "../engine/types/screen.js";
 export type { TargetRef } from "../engine/types/target-ref.js";
 export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node.js";
 export type { WorkspaceDefinition } from "../engine/types/workspace.js";
-export { PROJECTION_DETAIL_ENTITY, WRITE_FORM_SECTION_ENTITY, } from "../i18n/required-surface-keys.js";
+export { ACTION_FORM_ENTITY, PROJECTION_DETAIL_ENTITY, WRITE_FORM_SECTION_ENTITY, } from "../i18n/required-surface-keys.js";
 export type { AppSchema, FeatureSchema, QualifiedContentCollection, WorkspaceSchema, } from "./app-schema.js";
 export { type Formality, formalLocaleTag } from "./formality.js";
 export type { ListRowMetaColumnType, ListRowMetaReference, ReferenceLookupSource, SystemReferenceLabel, } from "./list-row-meta.js";

package/dist/ui-types/index.js

@@ -25,7 +25,7 @@ export { parseRefTarget } from "../engine/parse-ref-target.js";
 export { evalFieldCondition, explicitListScreenId, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";
 export { metricField } from "../engine/types/screen.js";
-export { PROJECTION_DETAIL_ENTITY, WRITE_FORM_SECTION_ENTITY, } from "../i18n/required-surface-keys.js";
+export { ACTION_FORM_ENTITY, PROJECTION_DETAIL_ENTITY, WRITE_FORM_SECTION_ENTITY, } from "../i18n/required-surface-keys.js";
 export { formalLocaleTag } from "./formality.js";
 export { LIST_ROW_META_COLUMNS, LIST_ROW_META_REFERENCES, REFERENCE_LOOKUP_SOURCES, SYSTEM_REFERENCE_LABELS, } from "./list-row-meta.js";
 export { resolveTranslationValue, translationValueOtherText, } from "./plural.js";

package/dist/upgrade-cli.d.ts

@@ -2,6 +2,7 @@ export type UpgradeCliOut = {
     readonly log: (line: string) => void;
     readonly err: (line: string) => void;
 };
+export declare function findFeatureChangelogFiles(featuresDir: string): string[];
 export declare function findPackageChangelogFiles(cwd: string): string[];
 export declare function findFeaturesDirs(cwd: string): string[];
 export declare function findCodemodScriptsRoot(repoRoot: string): string | null;

package/dist/upgrade-cli.js

@@ -56,10 +56,10 @@ function readChangelogFile(filePath) {
         return [];
     }
 }
-function collectChangelogs(featuresDir) {
+export function findFeatureChangelogFiles(featuresDir) {
     if (!existsSync(featuresDir))
         return [];
-    const entries = [];
+    const files = [];
     const features = readdirSync(featuresDir, { withFileTypes: true })
         .filter((d) => d.isDirectory())
         .map((d) => d.name);
@@ -71,9 +71,13 @@ function collectChangelogs(featuresDir) {
         const srcLayout = join(featuresDir, name, "src", "changes.json");
         const flatLayout = join(featuresDir, name, "changes.json");
         const changelogPath = existsSync(srcLayout) ? srcLayout : flatLayout;
-        entries.push(...readChangelogFile(changelogPath));
+        if (existsSync(changelogPath))
+            files.push(changelogPath);
     }
-    return entries;
+    return files;
+}
+function collectChangelogs(featuresDir) {
+    return findFeatureChangelogFiles(featuresDir).flatMap(readChangelogFile);
 }
 // bundled-features is excluded: findFeaturesDirs collects it per feature
 // (src/<feature>/changes.json), every other package has one src/changes.json.
@@ -99,7 +103,8 @@ export function findPackageChangelogFiles(cwd) {
         const scopeDir = join(dir, "node_modules/@cosmicdrift");
         if (existsSync(scopeDir)) {
             const pkgNames = readdirSync(scopeDir, { withFileTypes: true })
-                .filter((d) => d.isDirectory() && d.name !== "kumiko-bundled-features")
+                // Dirent has lstat semantics: workspace-linked packages are symlinks.
+                .filter((d) => (d.isDirectory() || d.isSymbolicLink()) && d.name !== "kumiko-bundled-features")
                 .map((d) => d.name);
             for (const name of pkgNames) {
                 if (seenNames.has(name))
@@ -257,21 +262,21 @@ function writeUpgradeMarker(targetDir, marker) {
     mkdirSync(dir, { recursive: true });
     writeFileSync(join(dir, "upgrade-state.json"), `${JSON.stringify(marker, null, 2)}\n`, "utf-8");
 }
-// Missing, unreadable, or invalid marker means no baseline was ever recorded
-// — most commonly a bootstrap app that never ran `--apply` (fw#2299) — so
-// this reports "no marker" instead of throwing.
+// A missing marker is a bootstrap app that never ran `--apply` (fw#2299); an
+// existing but unreadable one must not silently fall back to the installed
+// version, or a bare `--apply` would skip every codemod in between.
 function readMarkerVersion(targetDir) {
     const markerPath = join(targetDir, ".kumiko", "upgrade-state.json");
     if (!existsSync(markerPath))
-        return null;
+        return { kind: "missing" };
     try {
         const parsed = JSON.parse(readFileSync(markerPath, "utf-8"));
         return typeof parsed.version === "string" && SEMVER_RE.test(parsed.version)
-            ? parsed.version
-            : null;
+            ? { kind: "ok", version: parsed.version }
+            : { kind: "invalid" };
     }
     catch {
-        return null;
+        return { kind: "invalid" };
     }
 }
 /** Highest pending version strictly below the earliest open manual breaking
@@ -337,10 +342,12 @@ markerVersion) {
             : "  ✓ No breaking changes pending.");
         if (!dryRun) {
             const markerVer = markerVersionForPending(pending, manualEntries, markerVersion);
+            const pendingManual = manualEntries.map((e) => ({ version: e.version, title: e.title }));
             writeUpgradeMarker(targetDir, {
                 version: markerVer,
                 appliedAt: Temporal.Now.instant().toString(),
                 codemods: [],
+                ...(pendingManual.length > 0 && { pendingManual }),
             });
             out.log(`  ✓ Applied 0 codemod(s). Wrote ${join(targetDir, ".kumiko/upgrade-state.json")}`);
             logManualMarkerOutcome(out, manualEntries, markerVer);
@@ -431,7 +438,14 @@ export async function runUpgradeCli(argv, cwd, out, options) {
     // when the marker says otherwise — a bare `--apply` would then always
     // report "Nothing new" and bootstrap the marker onto the installed
     // version, hiding breaking changes the marker never actually saw.
-    const currentVersion = fromFlag ?? readMarkerVersion(targetDir) ?? installedVersion;
+    const marker = fromFlag === undefined ? readMarkerVersion(targetDir) : { kind: "missing" };
+    if (marker.kind === "invalid") {
+        out.err("");
+        out.err("  invalid .kumiko/upgrade-state.json, fix it or pass --from <version>");
+        out.err("");
+        return 1;
+    }
+    const currentVersion = fromFlag ?? (marker.kind === "ok" ? marker.version : undefined) ?? installedVersion;
     if (!currentVersion) {
         out.err("");
         out.err("  Could not detect Kumiko version.");
@@ -465,10 +479,17 @@ export async function runUpgradeCli(argv, cwd, out, options) {
     if (getFlag(args, "apply")) {
         // Marker must reflect what is actually installed under the target (or
         // cwd), not the filter baseline above — otherwise CI stays green forever.
-        const markerVersion = (dirFlag ? readCurrentVersion(targetDir) : null) ?? installedVersion ?? currentVersion;
+        const markerVersion = dirFlag ? readCurrentVersion(targetDir) : installedVersion;
         const dryRun = getFlag(args, "dry-run");
+        if (markerVersion === null && !dryRun) {
+            out.err("");
+            out.err(`  Could not detect the installed Kumiko version under ${targetDir}.`);
+            out.err("  Refusing to write an upgrade marker without it (--from is only a filter).");
+            out.err("");
+            return 1;
+        }
         out.log("");
-        const code = await applyCodemods(out, pending, repoRoot, targetDir, dryRun, markerVersion);
+        const code = await applyCodemods(out, pending, repoRoot, targetDir, dryRun, markerVersion ?? currentVersion);
         out.log("");
         return code;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.334.0",
+  "version": "0.336.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -206,8 +206,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.334.0",
-    "@cosmicdrift/kumiko-types": "0.334.0",
+    "@cosmicdrift/kumiko-http": "0.336.0",
+    "@cosmicdrift/kumiko-types": "0.336.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -223,7 +223,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.334.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.336.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },