@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

package/dist/engine/validate-projection-allowlist.js

@@ -0,0 +1,164 @@
+// Boot-validation for r.step.unsafeProjection* allowlist.
+//
+// Q10 declared the allowlist a hard requirement: every unsafeProjection*
+// step must target a table that the owning feature explicitly declared
+// via r.requires.projection("table_name"), and that table must NOT be
+// one of the registered aggregate-tables (those are managed via
+// r.entity / r.step.aggregate.*). Boot-error otherwise.
+//
+// Mechanism: each writeHandler that uses the perform-pipeline form ships
+// a closure. We invoke it once at boot with a minimal dummy event to
+// extract the immutable step-list, then walk the list looking for the
+// known unsafeProjection-* kinds. Resolvers (the per-step arg-callbacks)
+// don't run at build time, so dummy event-payloads are fine.
+//
+// CLOSURE-BODY CONTRACT: the pipeline-closure body (the function passed
+// to `stepsPipeline(...)`) must produce its step-list deterministically based
+// on the step-builder `r` alone. Reading `event.payload` outside of
+// resolvers (i.e. at the top of the closure, not inside a step's `row:`
+// or `data:` callback) is forbidden — at boot the dummy payload is `{}`
+// and a closure that branches on payload-fields would pass validation
+// while production calls produce a different step-list. A throw at
+// boot-time is surfaced cleanly; a quietly-different step-list is not
+// caught by this validator. A future lint-rule will enforce the contract
+// statically; today it lives in this comment + the StepBuilder doc.
+import { KUMIKO_META_SYMBOL, KUMIKO_NAME_SYMBOL, } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { getStep } from "./define-step.js";
+import { buildPipelineSteps } from "./pipeline.js";
+// Listed step-kinds whose `args.table` must be in the owning feature's
+// r.requires.projection allowlist. Extend as further unsafeProjection.*
+// steps land — don't pre-list hypothetical kinds (CLAUDE.md: don't design
+// for scenarios that can't happen).
+const UNSAFE_PROJECTION_KINDS = new Set(["unsafeProjectionUpsert", "unsafeProjectionDelete"]);
+// Sub-pipeline arg-paths come from `defineStep({ subPaths: [...] })` —
+// each builder declares its own (e.g. branch's onTrue/onFalse, forEach's
+// do). Walking via the registry means nested unsafeProjection-* in NEW
+// sub-step-builders is automatically caught the moment the builder
+// registers itself; no central map to keep in sync. Followup #15.
+function* walkAllSteps(steps) {
+    for (const step of steps) {
+        yield step;
+        const def = getStep(step.kind);
+        const subPaths = def?.subPaths;
+        if (!subPaths || subPaths.length === 0)
+            continue;
+        const args = step.args;
+        for (const path of subPaths) {
+            const subSteps = args[path];
+            if (Array.isArray(subSteps)) {
+                yield* walkAllSteps(subSteps);
+            }
+        }
+    }
+}
+// table()/buildEntityTable spread column handles as enumerable props, so an
+// entity field named `tableName`/`source` would shadow the matching meta key —
+// the canonical meta under KUMIKO_META_SYMBOL is the only collision-safe source.
+function resolveTableNameFromStep(table) {
+    if (typeof table === "object" && table !== null) {
+        // Canonical meta under the unshadowable symbol — preferred path.
+        const meta = table[KUMIKO_META_SYMBOL];
+        if (meta !== null && typeof meta === "object") {
+            const metaName = meta["tableName"];
+            if (typeof metaName === "string")
+                return metaName;
+        }
+        // Plain meta (deriveEntityTableMeta / defineUnmanagedTable — no handle-spread).
+        if ("source" in table &&
+            "tableName" in table &&
+            typeof table["tableName"] === "string") {
+            return table["tableName"];
+        }
+        // drizzle pgTable
+        const name = table[KUMIKO_NAME_SYMBOL];
+        if (typeof name === "string")
+            return name;
+    }
+    throw new Error(`validate-projection-allowlist: cannot resolve table name from ${String(table)}`);
+}
+const DUMMY_USER = {
+    id: "00000000-0000-0000-0000-000000000000",
+    tenantId: "00000000-0000-0000-0000-000000000000",
+    roles: [],
+};
+/**
+ * Validate every feature's pipeline-form writeHandlers against:
+ *   1. the owning feature's r.requires.projection allowlist
+ *   2. the cross-feature aggregate-table set (registered via r.entity)
+ *
+ * Throws on the first violation (fail-fast, consistent with other
+ * boot-validations).
+ */
+export function validateProjectionAllowlist(features) {
+    // Aggregate-tables across all features. Map table-name → owning feature.
+    // Two features registering r.entity on the same table is always a bug —
+    // physical PG-collision aside, the second feature's writes would replay
+    // the first feature's projections (and vice-versa). Detect and surface
+    // here so the error names BOTH owners; without this, the silent-set
+    // would point any later unsafeProjection-error at the wrong feature.
+    // Followup #8.
+    const aggregateTables = new Map();
+    for (const f of features) {
+        for (const [entityName, entity] of Object.entries(f.entities ?? {})) {
+            const tableName = entity.table ?? entityName;
+            const existing = aggregateTables.get(tableName);
+            if (existing && existing !== f.name) {
+                throw new Error(`Aggregate-table "${tableName}" is registered by both feature "${existing}" and feature "${f.name}" via r.entity. ` +
+                    `Each aggregate-table must have a single owning feature — pick distinct table names ` +
+                    `(via createEntity({ table: "..." })) or remove the duplicate r.entity registration.`);
+            }
+            aggregateTables.set(tableName, f.name);
+        }
+    }
+    for (const f of features) {
+        for (const [handlerName, handler] of Object.entries(f.writeHandlers)) {
+            const perform = handler.perform;
+            if (perform?.__kind !== "pipeline")
+                continue;
+            let steps;
+            try {
+                const dummyEvent = {
+                    type: handlerName,
+                    payload: {},
+                    user: DUMMY_USER,
+                };
+                steps = buildPipelineSteps(perform, dummyEvent);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                throw new Error(`[Feature ${f.name}] writeHandler "${handlerName}" pipeline-closure threw at boot: ${message}. ` +
+                    `Closure body must produce the step list without reading event-payload fields ` +
+                    `(those belong inside step resolvers).`);
+            }
+            for (const step of walkAllSteps(steps)) {
+                // Tier-2 step-discovery (Q9): require explicit opt-in via
+                // r.requires.step("<kind>") for any tier-2+ step. Tier-1 is implicit.
+                const def = getStep(step.kind);
+                if (def?.tier === 2 && !f.requiredSteps.has(step.kind)) {
+                    throw new Error(`[Feature ${f.name}] writeHandler "${handlerName}" uses tier-2 step "${step.kind}" ` +
+                        `but did not declare it via r.requires.step("${step.kind}"). ` +
+                        `Add the declaration in defineFeature("${f.name}", r => { r.requires.step("${step.kind}"); ... }).`);
+                }
+                if (!UNSAFE_PROJECTION_KINDS.has(step.kind))
+                    continue;
+                const stepArgs = step.args;
+                if (!stepArgs.table) {
+                    throw new Error(`[Feature ${f.name}] writeHandler "${handlerName}" has a ${step.kind} step ` +
+                        `without a \`table\` argument.`);
+                }
+                const tableName = resolveTableNameFromStep(stepArgs.table);
+                const aggregateOwner = aggregateTables.get(tableName);
+                if (aggregateOwner) {
+                    throw new Error(`[Feature ${f.name}] writeHandler "${handlerName}" uses ${step.kind} on table "${tableName}", ` +
+                        `but that table is the aggregate-projection of feature "${aggregateOwner}" (registered via r.entity). ` +
+                        `Aggregate-tables MUST be mutated through r.step.aggregate.* — see step-vocabulary.md Q10.`);
+                }
+                if (!f.requiredProjections.has(tableName)) {
+                    throw new Error(`[Feature ${f.name}] writeHandler "${handlerName}" uses ${step.kind} on table "${tableName}", ` +
+                        `but the feature did not declare it via r.requires.projection("${tableName}"). ` +
+                        `Add the declaration in defineFeature("${f.name}", r => { r.requires.projection("${tableName}"); ... }).`);
+                }
+            }
+        }
+    }
+}

package/dist/engine/validation.d.ts

@@ -0,0 +1,3 @@
+import type { Registry, ValidationError } from "./types/index.js";
+export type { ValidationError };
+export declare function runValidation(registry: Registry, hookName: string, data: Readonly<Record<string, unknown>>): readonly ValidationError[] | null;

package/dist/engine/validation.js

@@ -0,0 +1,23 @@
+import { parseQn, toKebab } from "./qualified-name.js";
+export function runValidation(registry, hookName, data) {
+    const errors = [];
+    // hookName is a qualified name like "feature:write:task:create".
+    // Validation hooks are stored with the unqualified short name in the feature definition.
+    const parsed = parseQn(hookName);
+    for (const [featureName, feature] of registry.features) {
+        if (toKebab(featureName) !== parsed.scope)
+            continue;
+        const validationHooks = feature.hooks?.validation;
+        if (!validationHooks)
+            continue;
+        // Find the hook by matching the QN name segment against the stored short name.
+        // Both use colon convention (e.g. "task:create"), so direct match works.
+        const hook = validationHooks[parsed.name];
+        if (hook) {
+            const result = hook(data);
+            if (result)
+                errors.push(...result);
+        }
+    }
+    return errors.length > 0 ? errors : null;
+}

package/dist/engine/where-rule-lint.d.ts

@@ -0,0 +1,2 @@
+export declare function tableColumnSqlNames(table: unknown): ReadonlySet<string>;
+export declare function assertQualifiedWhereFragment(sqlText: string, columnSqlNames: ReadonlySet<string>, scope: string): void;

package/dist/engine/where-rule-lint.js

@@ -0,0 +1,171 @@
+// Static lint for `WhereRule` SQL fragments (fw#2639).
+//
+// A `where`-rule hands the framework raw SQL. If the author writes an
+// unqualified column name inside a correlated subquery, Postgres binds it
+// to the innermost table instead of the outer one — the intended predicate
+// silently collapses into a tautology (`t.x = t.x`) and the rule grants
+// every row instead of none. This module is a text-level lint (no SQL
+// parser) that catches the two shapes that always mean "this rule is
+// broken": a bare column reference inside a subquery that shadows an outer
+// column, and a literal self-comparison.
+import { KUMIKO_COLUMNS_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { toSnakeCase } from "../db/table-builder.js";
+const IDENT_SRC = `"(?:[^"]|"")+"|[A-Za-z_][A-Za-z0-9_$]*`;
+const QUALIFIED_SRC = `(?:${IDENT_SRC})(?:\\.(?:${IDENT_SRC}))?`;
+const TOKEN_RE = new RegExp(IDENT_SRC, "g");
+const SELF_COMPARISON_RE = new RegExp(`(${QUALIFIED_SRC})\\s*(?<![!<>=])=(?!=)\\s*(${QUALIFIED_SRC})`, "g");
+const QUALIFIED_PARSE_RE = new RegExp(`^(${IDENT_SRC})(?:\\.(${IDENT_SRC}))?$`);
+// Resolve the SQL column names a table exposes, so the lint can tell a
+// real column reference apart from a table alias / function name / SQL
+// keyword. Returns an empty set when nothing is derivable (fail-open on
+// the lint itself would be worse than skipping it).
+export function tableColumnSqlNames(table) {
+    if (table === null || typeof table !== "object")
+        return new Set();
+    const cols = table[KUMIKO_COLUMNS_SYMBOL];
+    if (cols && typeof cols === "object") {
+        const names = new Set();
+        for (const col of Object.values(cols)) {
+            if (col && typeof col === "object") {
+                const nameVal = col["name"];
+                if (typeof nameVal === "string")
+                    names.add(nameVal.toLowerCase());
+            }
+        }
+        return names;
+    }
+    // Plain-object fallback (tests): no Drizzle column-symbol map, so every
+    // object-valued key is treated as a field and mapped to its SQL name the
+    // same way columnSqlName() in ownership.ts does for hand-rolled tables.
+    const names = new Set();
+    for (const [key, value] of Object.entries(table)) {
+        if (value && typeof value === "object") {
+            names.add(toSnakeCase(key).toLowerCase());
+        }
+    }
+    return names;
+}
+function skipLineComment(sql, i) {
+    let j = i;
+    while (j < sql.length && sql[j] !== "\n")
+        j++;
+    return j;
+}
+function skipBlockComment(sql, i) {
+    let j = i + 2;
+    while (j < sql.length && !(sql[j] === "*" && sql[j + 1] === "/"))
+        j++;
+    return j + 2;
+}
+function skipQuotedLiteral(sql, i) {
+    let j = i + 1;
+    while (j < sql.length) {
+        if (sql[j] === "'" && sql[j + 1] === "'") {
+            j += 2;
+            continue;
+        }
+        if (sql[j] === "'") {
+            j++;
+            break;
+        }
+        j++;
+    }
+    return j;
+}
+function stripCommentsAndStrings(sqlText) {
+    let result = "";
+    let i = 0;
+    const len = sqlText.length;
+    while (i < len) {
+        const ch = sqlText[i];
+        if (ch === "-" && sqlText[i + 1] === "-") {
+            i = skipLineComment(sqlText, i);
+            result += " ";
+            continue;
+        }
+        if (ch === "/" && sqlText[i + 1] === "*") {
+            i = skipBlockComment(sqlText, i);
+            result += " ";
+            continue;
+        }
+        if (ch === "'") {
+            i = skipQuotedLiteral(sqlText, i);
+            result += " ";
+            continue;
+        }
+        result += ch;
+        i++;
+    }
+    return result;
+}
+function normalizeIdent(raw) {
+    if (raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"')) {
+        return raw.slice(1, -1).replace(/""/g, '"').toLowerCase();
+    }
+    return raw.toLowerCase();
+}
+function normalizeQualifiedRef(raw) {
+    const parsed = QUALIFIED_PARSE_RE.exec(raw);
+    if (!parsed)
+        return normalizeIdent(raw);
+    const first = normalizeIdent(parsed[1] ?? "");
+    const second = parsed[2];
+    return second === undefined ? first : `${first}.${normalizeIdent(second)}`;
+}
+// Rule 1: `X = Y` where X and Y are textually the same (optionally
+// once-qualified) identifier is always a tautology, subquery or not.
+function findSelfComparison(cleaned) {
+    SELF_COMPARISON_RE.lastIndex = 0;
+    let match = SELF_COMPARISON_RE.exec(cleaned);
+    while (match !== null) {
+        const left = match[1] ?? "";
+        const right = match[2] ?? "";
+        if (normalizeQualifiedRef(left) === normalizeQualifiedRef(right)) {
+            return left.trim();
+        }
+        match = SELF_COMPARISON_RE.exec(cleaned);
+    }
+    return null;
+}
+// Rule 2: inside a subquery, a bare identifier that happens to name a
+// column on the OUTER table is the fail-open shape — Postgres resolves it
+// against the innermost table first. A qualifier (`t.x`) or a table/alias
+// name immediately followed by `.` is not a column reference and is
+// ignored.
+function findUnqualifiedColumnReference(cleaned, columnSqlNames) {
+    TOKEN_RE.lastIndex = 0;
+    let match = TOKEN_RE.exec(cleaned);
+    while (match !== null) {
+        const start = match.index;
+        const end = start + match[0].length;
+        const precededByDot = start > 0 && cleaned[start - 1] === ".";
+        const followedByDot = cleaned[end] === ".";
+        if (!precededByDot && !followedByDot) {
+            const normalized = normalizeIdent(match[0]);
+            if (columnSqlNames.has(normalized))
+                return normalized;
+        }
+        match = TOKEN_RE.exec(cleaned);
+    }
+    return null;
+}
+// Throws (fail-closed) instead of shipping a where-rule that would silently
+// fail-open at request time. Called both as a runtime backstop
+// (ownership.ts#ruleToFragment) and as a boot-time probe
+// (boot-validator/ownership.ts).
+export function assertQualifiedWhereFragment(sqlText, columnSqlNames, scope) {
+    const cleaned = stripCommentsAndStrings(sqlText);
+    const selfComparison = findSelfComparison(cleaned);
+    if (selfComparison !== null) {
+        throw new Error(`[Kumiko Ownership] ${scope}: where-rule SQL compares "${selfComparison}" with itself — this is a tautology that matches every row. Remove the redundant comparison or compare against a real bound value / a different, properly qualified column.`);
+    }
+    // skip: without a subquery there is no inner table to shadow — a bare
+    // column reference cannot bind against anything but the outer table, so
+    // the fail-open shape this lint targets is impossible here.
+    if (!/\bSELECT\b/i.test(cleaned))
+        return;
+    const unqualified = findUnqualifiedColumnReference(cleaned, columnSqlNames);
+    if (unqualified !== null) {
+        throw new Error(`[Kumiko Ownership] ${scope}: where-rule SQL references column "${unqualified}" unqualified inside a subquery. Postgres binds an unqualified name to the innermost table first, which silently turns the ownership predicate into a tautology (fail-open). Qualify it with the outer table, e.g. \`\${ctx.tableName}.${unqualified}\`.`);
+    }
+}

package/dist/engine/write-handler-qn-extract.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Regex for a valid write-handler QN shape.
+ * 3 segments (feature:write:handler) or 4+ (feature:write:entity:verb).
+ */
+export declare const WRITE_HANDLER_QN_FORMAT_RE: RegExp;
+/** Extract string-literal write-handler QNs from TS/TSX source text. */
+export declare function extractDispatcherWriteQnsFromSource(source: string): readonly string[];
+export type WriteHandlerQnValidation = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Validate a single QN against optional known set (kebab-normalized). */
+export declare function validateDispatcherWriteQn(qn: string, knownQns: ReadonlySet<string>): WriteHandlerQnValidation;

package/dist/engine/write-handler-qn-extract.js

@@ -0,0 +1,36 @@
+import { toKebab } from "./qualified-name.js";
+/**
+ * Regex for a valid write-handler QN shape.
+ * 3 segments (feature:write:handler) or 4+ (feature:write:entity:verb).
+ */
+export const WRITE_HANDLER_QN_FORMAT_RE = /^[a-zA-Z][a-zA-Z0-9-]*:write:[a-zA-Z][a-zA-Z0-9-]*(:[a-zA-Z][a-zA-Z0-9-]*)*$/;
+// Matches `dispatcher.write("qn", ...)` and `<expr>.write("qn", ...)` —
+// same surface the CI guard scans. Dynamic QNs (variables, templates) are
+// intentionally skipped (known limitation, documented in #403).
+const DISPATCHER_WRITE_LITERAL_RE = /\.write\s*\(\s*["']([^"']+)["']/g;
+/** Extract string-literal write-handler QNs from TS/TSX source text. */
+export function extractDispatcherWriteQnsFromSource(source) {
+    const out = new Set();
+    for (const match of source.matchAll(DISPATCHER_WRITE_LITERAL_RE)) {
+        const qn = match[1];
+        if (qn)
+            out.add(qn);
+    }
+    return [...out];
+}
+/** Validate a single QN against optional known set (kebab-normalized). */
+export function validateDispatcherWriteQn(qn, knownQns) {
+    if (!WRITE_HANDLER_QN_FORMAT_RE.test(qn)) {
+        return {
+            ok: false,
+            reason: `invalid QN format: "${qn}" — expected "<feature>:write:<handler>"`,
+        };
+    }
+    if (knownQns.size > 0 && !knownQns.has(toKebab(qn))) {
+        return {
+            ok: false,
+            reason: `unknown write handler: "${qn}" — not registered via r.writeHandler(...)`,
+        };
+    }
+    return { ok: true };
+}

package/dist/entrypoint/index.d.ts

@@ -0,0 +1,83 @@
+import type { Hono } from "hono";
+import type { AuthRoutesConfig } from "../api/auth-routes.js";
+import type { JwtHelper, JwtKeyring } from "../api/jwt.js";
+import type { ServerOptions } from "../api/server.js";
+import type { SseBroker } from "../api/sse-broker.js";
+import type { PgClient } from "../db/connection.js";
+import type { AppContext, Registry } from "../engine/types/index.js";
+import type { JobRunner, JobRunnerOptions } from "../jobs/job-runner.js";
+import type { Lifecycle } from "../lifecycle/index.js";
+import type { ObservabilityOptions, ObservabilityProvider } from "../observability/index.js";
+import type { Dispatcher, DispatcherOptions } from "../pipeline/dispatcher.js";
+import type { EventDedup, EventDispatcher } from "../pipeline/index.js";
+import type { SystemHooks } from "../pipeline/lifecycle-pipeline.js";
+export type BaseEntrypointOptions = {
+    readonly registry: Registry;
+    readonly context: AppContext;
+    readonly jwtSecret: string | JwtKeyring;
+    readonly jwtIssuer?: string;
+    readonly observability?: ObservabilityProvider;
+    readonly observabilityOptions?: ObservabilityOptions;
+    readonly dispatcherOptions?: Omit<DispatcherOptions, "lifecycle">;
+    readonly systemHooks?: SystemHooks;
+    readonly eventDedup?: EventDedup;
+    readonly lifecycle?: Lifecycle;
+};
+type JobsBlock = {
+    readonly redisUrl: string;
+    readonly queueNamePrefix?: string;
+    readonly getActiveTenantIds?: JobRunnerOptions["getActiveTenantIds"];
+    readonly onJobStart?: JobRunnerOptions["onJobStart"];
+    readonly onJobComplete?: JobRunnerOptions["onJobComplete"];
+    readonly onJobFailed?: JobRunnerOptions["onJobFailed"];
+};
+export type ApiEntrypointOptions = BaseEntrypointOptions & {
+    readonly auth?: AuthRoutesConfig;
+    readonly anonymousAccess?: ServerOptions["anonymousAccess"];
+    readonly sseBroker?: SseBroker;
+    readonly rateLimit?: ServerOptions["rateLimit"];
+    readonly maxRequestBytes?: ServerOptions["maxRequestBytes"];
+    readonly readiness?: ServerOptions["readiness"];
+    readonly metrics?: ServerOptions["metrics"];
+    readonly extraRoutes?: ServerOptions["extraRoutes"];
+    readonly jobs?: JobsBlock & {
+        readonly runLocalJobs?: boolean;
+    };
+    readonly eventDispatcher?: ServerOptions["eventDispatcher"] & {
+        readonly runLocal?: boolean;
+    };
+    readonly trustedProxyHops?: ServerOptions["trustedProxyHops"];
+};
+export type WorkerEntrypointOptions = BaseEntrypointOptions & JobsBlock & {
+    readonly eventDispatcher?: ServerOptions["eventDispatcher"];
+};
+export type AllInOneEntrypointOptions = ApiEntrypointOptions & WorkerEntrypointOptions;
+export type ApiEntrypoint = {
+    readonly app: Hono;
+    readonly jwt: JwtHelper;
+    readonly sseBroker: SseBroker;
+    readonly lifecycle: Lifecycle;
+    readonly observability: ObservabilityProvider;
+    readonly dispatcher: Dispatcher;
+    readonly eventDispatcher?: EventDispatcher;
+    readonly mode: "api";
+    start(): Promise<void>;
+    stop(): Promise<void>;
+};
+export type WorkerEntrypoint = {
+    readonly lifecycle: Lifecycle;
+    readonly eventDispatcher: EventDispatcher;
+    readonly jobRunner: JobRunner;
+    readonly observability: ObservabilityProvider;
+    readonly dispatcher: Dispatcher;
+    readonly mode: "worker";
+    start(): Promise<void>;
+    stop(): Promise<void>;
+};
+export type AllInOneEntrypoint = Omit<ApiEntrypoint, "mode"> & Omit<WorkerEntrypoint, "mode"> & {
+    readonly mode: "all-in-one";
+};
+export declare function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoint;
+export declare function createWorkerEntrypoint(options: WorkerEntrypointOptions): WorkerEntrypoint;
+export declare function createAllInOneEntrypoint(options: AllInOneEntrypointOptions): AllInOneEntrypoint;
+export type { PgClient };