@cosmicdrift/kumiko-framework 0.333.0 → 0.335.0

package/dist/pipeline/tenant-timezone-cache.js

@@ -10,20 +10,27 @@ const DEFAULT_TTL_MS = 5 * 60 * 1000;
 const DEFAULT_MAX_ENTRIES = 1000;
 export function createTenantTimezoneCache(opts = {}) {
     const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
-    const maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    // 0 or negative would never evict (size < max is never true) and grow unbounded.
+    const maxEntries = Math.max(1, opts.maxEntries ?? DEFAULT_MAX_ENTRIES);
     const now = opts.now ?? (() => Date.now());
     // Map insertion order doubles as LRU order: touch = delete+re-insert.
     const entries = new Map();
+    let generation = 0;
     function evictOldestIfFull() {
         // skip: cache has room, nothing to evict
         if (entries.size < maxEntries)
             return;
         const oldestKey = entries.keys().next().value;
-        // skip: defensive — only reachable if maxEntries is 0 (cache disabled) and entries is empty
+        // skip: defensive — maxEntries >= 1 guarantees a non-empty map here
         if (oldestKey === undefined)
             return;
         entries.delete(oldestKey);
     }
+    function set(tenantId, value) {
+        entries.delete(tenantId);
+        evictOldestIfFull();
+        entries.set(tenantId, { value, expiresAt: now() + ttlMs });
+    }
     return {
         get(tenantId) {
             const hit = entries.get(tenantId);
@@ -37,15 +44,22 @@ export function createTenantTimezoneCache(opts = {}) {
             entries.set(tenantId, hit);
             return { value: hit.value };
         },
-        set(tenantId, value) {
-            entries.delete(tenantId);
-            evictOldestIfFull();
-            entries.set(tenantId, { value, expiresAt: now() + ttlMs });
+        set,
+        generation() {
+            return generation;
+        },
+        setIfFresh(tenantId, value, generationAtRead) {
+            // skip: an invalidation ran since the read started, the value may be pre-write
+            if (generationAtRead !== generation)
+                return;
+            set(tenantId, value);
         },
         invalidate(tenantId) {
+            generation++;
             entries.delete(tenantId);
         },
         clear() {
+            generation++;
             entries.clear();
         },
         size() {

package/dist/pipeline/write-result-masking.d.ts

@@ -0,0 +1,6 @@
+import type { WriteResult } from "../engine/types/index.js";
+import type { BatchCommand, BatchResult, DispatchContext } from "./dispatch-shared.js";
+type EntityLookup = Pick<DispatchContext["registry"], "getHandlerEntity" | "getEntity">;
+export declare function maskWriteResultForClient(registry: EntityLookup, handlerType: string, result: WriteResult): WriteResult;
+export declare function maskBatchResultForClient(registry: EntityLookup, commands: readonly BatchCommand[], batch: BatchResult): BatchResult;
+export {};

package/dist/pipeline/write-result-masking.js

@@ -0,0 +1,36 @@
+import { maskWriteOnlyFields } from "../engine/field-access.js";
+import { isLifecycleResult } from "./dispatcher-utils.js";
+function maskLifecycleOrRow(entity, data) {
+    if (typeof data !== "object" || data === null || Array.isArray(data))
+        return data;
+    if (!isLifecycleResult(data))
+        return maskWriteOnlyFields(entity, data); // @cast-boundary engine-payload
+    if (data.kind === "save") {
+        return {
+            ...data,
+            data: maskWriteOnlyFields(entity, data.data),
+            changes: maskWriteOnlyFields(entity, data.changes),
+            previous: maskWriteOnlyFields(entity, data.previous),
+        };
+    }
+    return { ...data, data: maskWriteOnlyFields(entity, data.data) };
+}
+// Copy-on-mask: the original results still feed postSaveBatch hooks, which
+// need the plaintext. Only what leaves the dispatcher is masked.
+export function maskWriteResultForClient(registry, handlerType, result) {
+    if (!result.isSuccess)
+        return result;
+    const entityName = registry.getHandlerEntity(handlerType);
+    const entity = entityName ? registry.getEntity(entityName) : undefined;
+    if (!entity)
+        return result;
+    const data = maskLifecycleOrRow(entity, result.data);
+    return data === result.data ? result : { ...result, data };
+}
+export function maskBatchResultForClient(registry, commands, batch) {
+    const results = batch.results.map((result, index) => {
+        const command = commands[index];
+        return command ? maskWriteResultForClient(registry, command.type, result) : result;
+    });
+    return { ...batch, results };
+}

package/dist/redis/pubsub-signal.d.ts

@@ -1,3 +1,4 @@
+import { type RedisClientOptions } from "./client.js";
 export type PubSubSignal = {
     publish(channel: string, payload: unknown): void;
     onMessage(listener: (channel: string, payload: unknown) => void): void;
@@ -7,5 +8,6 @@ export type PubSubSignalOptions = {
     readonly redisUrl: string;
     readonly channelPattern: string;
     readonly label: string;
+    readonly clientOptions?: RedisClientOptions;
 };
 export declare function createRedisPubSubSignal(opts: PubSubSignalOptions): PubSubSignal;

package/dist/redis/pubsub-signal.js

@@ -9,8 +9,8 @@ function logConnectionError(label, role) {
     };
 }
 export function createRedisPubSubSignal(opts) {
-    const publisher = createRedisClient(opts.redisUrl);
-    const subscriber = createRedisClient(opts.redisUrl);
+    const publisher = createRedisClient(opts.redisUrl, opts.clientOptions);
+    const subscriber = createRedisClient(opts.redisUrl, opts.clientOptions);
     publisher.on("error", logConnectionError(opts.label, "publisher"));
     subscriber.on("error", logConnectionError(opts.label, "subscriber"));
     const listeners = new Set();

package/dist/schema-cli.js

@@ -14,7 +14,7 @@ import { assertValidMigrationName, baselineMigrations, createDbConnection, diffR
 import { validateBoot } from "./engine/boot-validator.js";
 import { createRegistry } from "./engine/registry.js";
 import { createEventsTable } from "./event-store/index.js";
-import { queueRebuildsFromMarkers, runPendingRebuilds } from "./migrations/index.js";
+import { queueRebuildsFromMarkers, reportPendingRebuildRun, runPendingRebuilds, } from "./migrations/index.js";
 import { createEventConsumerStateTable, createProjectionStateTable } from "./pipeline/index.js";
 import { ensureTemporalPolyfill } from "./time/index.js";
 const SNAPSHOT_FILENAME = ".snapshot.json";
@@ -49,6 +49,7 @@ function nextSequenceNumber(migrationsDir) {
     }
     return max + 1;
 }
+const SCHEMA_SUBCOMMANDS = ["generate", "validate", "apply", "baseline", "status"];
 /**
  * Runs a schema-CLI subcommand. `appCwd` is the app workspace root (where
  * `kumiko/schema.ts` + `kumiko/migrations/` live). Returns a process exit code.
@@ -319,18 +320,7 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                     });
                     const registry = createRegistry(options.features);
                     const rebuildRun = await runPendingRebuilds(db, registry, { thisRunTables });
-                    if (rebuildRun.rebuilt.length > 0) {
-                        out.log(`  Rebuild ${rebuildRun.rebuilt.length} Projection(s)…`);
-                        for (const r of rebuildRun.rebuilt) {
-                            out.log(`    ↻ ${r.projection} (${r.eventsProcessed} events)`);
-                        }
-                        out.log("");
-                    }
-                    if (rebuildRun.failed.length > 0) {
-                        throw new Error(`Projection rebuild failed for: ${rebuildRun.failed
-                            .map((f) => `${f.projection} (${f.error})`)
-                            .join("; ")}. Table(s) stay queued in kumiko_pending_rebuilds — retried on the next apply.`);
-                    }
+                    reportPendingRebuildRun(rebuildRun, out.log);
                 }
                 return 0;
             }
@@ -421,7 +411,7 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
             // move on without ever running a migration.
             if (sub !== undefined) {
                 out.err(`  Unbekanntes Subcommand: "${sub}"`);
-                out.err("  Erlaubt: generate | validate | apply | baseline | status");
+                out.err(`  Erlaubt: ${SCHEMA_SUBCOMMANDS.join(" | ")}`);
                 return 1;
             }
             out.log("");

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-jobs.js

@@ -76,24 +76,36 @@ 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) {
+                    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/shared-entities.d.ts

@@ -9,6 +9,7 @@ export declare const sharedWidgetEntity: import("@cosmicdrift/kumiko-types/field
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -31,6 +32,7 @@ export declare const sharedWidgetTable: import("../db/table-builder.js").EntityT
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -53,6 +55,7 @@ export declare const sharedUserEntity: import("@cosmicdrift/kumiko-types/fields"
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -73,6 +76,7 @@ export declare const sharedUserEntity: import("@cosmicdrift/kumiko-types/fields"
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -93,6 +97,7 @@ export declare const sharedUserEntity: import("@cosmicdrift/kumiko-types/fields"
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -118,6 +123,7 @@ export declare const sharedUserTable: import("../db/table-builder.js").EntityTab
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -138,6 +144,7 @@ export declare const sharedUserTable: import("../db/table-builder.js").EntityTab
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -158,6 +165,7 @@ export declare const sharedUserTable: import("../db/table-builder.js").EntityTab
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -183,6 +191,7 @@ export declare const sharedItemEntity: import("@cosmicdrift/kumiko-types/fields"
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -224,6 +233,7 @@ export declare const sharedItemTable: import("../db/table-builder.js").EntityTab
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;

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

@@ -5,7 +5,7 @@ export type { ParsedRefTarget } from "../engine/parse-ref-target.js";
 export { parseRefTarget } from "../engine/parse-ref-target.js";
 export type { FieldsOrGroupsSection } from "../engine/screen-helpers.js";
 export { evalFieldCondition, explicitListScreenId, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
-export type { BooleanFieldDef, DateFieldDef, EmbeddedDerivedCellDef, EntityDefinition, FieldDefinition, FileFieldDef, FilesFieldDef, ImageFieldDef, ImagesFieldDef, NumberFieldDef, SelectFieldDef, SelectOptionTone, TextFieldDef, } from "../engine/types/fields.js";
+export type { BooleanFieldDef, DateFieldDef, EmbeddedDerivedCellDef, EntityDefinition, FieldDefinition, FileFieldDef, FilesFieldDef, ImageFieldDef, ImagesFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, SelectFieldDef, SelectOptionTone, TextFieldDef, } from "../engine/types/fields.js";
 export type { AccessRule, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, RoleAccessPersonalData, RoleAccessRule, } from "../engine/types/handlers.js";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";
 export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav.js";
@@ -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.333.0",
+  "version": "0.335.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.333.0",
-    "@cosmicdrift/kumiko-types": "0.333.0",
+    "@cosmicdrift/kumiko-http": "0.335.0",
+    "@cosmicdrift/kumiko-types": "0.335.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.333.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.335.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },