@cosmicdrift/kumiko-framework 0.305.0 → 0.307.0

package/src/engine/feature-ast/patterns.ts

@@ -71,7 +71,7 @@ import type {
   AgentHandlerHints,
   ClaimKeyType,
   EscapeHatchDeclaration,
-  RateLimitOption,
+  RateLimitDeclaration,
 } from "../types/handlers";
 import type { HookPhase } from "../types/hooks";
 import type { HttpRouteMethod } from "../types/http-route";
@@ -81,6 +81,7 @@ import type { RelationDefinition } from "../types/relations";
 import type { ScreenDefinition } from "../types/screen";
 import type { TreeActionDef } from "../types/tree-node";
 import type { WorkspaceDefinition } from "../types/workspace";
+import type { RawRefSentinel } from "./extractors/shared";
 import type { SourceLocation } from "./source-location";
 
 // =============================================================================
@@ -367,6 +368,10 @@ export type ScreenPattern = {
 // overrides that derivation explicitly (force-show or force-hide);
 // `agent.risk` ("low" | "mid" | "high") classifies the action's blast
 // radius, defaulting to "mid" for a write handler.
+//
+// access/rateLimit/escapeHatch/agent additionally accept a RawRefSentinel
+// for a non-literal value (imported/same-file const, or a sub-value like
+// `personalData: PD`) that would otherwise lose the reference on render.
 export type WriteHandlerPattern = {
   readonly kind: "writeHandler";
   readonly source: SourceLocation;
@@ -384,12 +389,12 @@ export type WriteHandlerPattern = {
   // handlerBody: the closure body as source text. Always opaque — AI
   // generates raw TypeScript, no DSL interpretation.
   readonly handlerBody?: SourceLocation;
-  readonly access?: AccessRule;
+  readonly access?: AccessRule | RawRefSentinel;
   readonly description?: string;
-  readonly agent?: AgentHandlerHints;
-  readonly rateLimit?: RateLimitOption;
+  readonly agent?: AgentHandlerHints | RawRefSentinel;
+  readonly rateLimit?: RateLimitDeclaration | RawRefSentinel;
   readonly unsafeSkipTransitionGuard?: boolean;
-  readonly escapeHatch?: EscapeHatchDeclaration;
+  readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
 };
 
 // `r.queryHandler(...)` — registers a read handler: name, Zod input schema,
@@ -408,25 +413,27 @@ export type QueryHandlerPattern = {
   readonly handlerName?: string;
   readonly schemaSource?: SourceLocation;
   readonly handlerBody?: SourceLocation;
-  readonly access?: AccessRule;
+  readonly access?: AccessRule | RawRefSentinel;
   readonly description?: string;
-  readonly agent?: AgentHandlerHints;
-  readonly rateLimit?: RateLimitOption;
-  readonly escapeHatch?: EscapeHatchDeclaration;
+  readonly agent?: AgentHandlerHints | RawRefSentinel;
+  readonly rateLimit?: RateLimitDeclaration | RawRefSentinel;
+  readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
 };
 
 // `r.streamHandler(...)` — registers a streaming read handler: name, Zod
-// input schema, async-generator handler closure, plus optional `access` and
-// `rateLimit` rules. Same header/body split and opaque single-reference
-// case as QueryHandlerPattern.
+// input schema, async-generator handler closure, plus optional `access`,
+// `rateLimit`, and `escapeHatch` rules (StreamHandlerDef carries all three
+// at runtime). Same header/body split and opaque single-reference case as
+// QueryHandlerPattern.
 export type StreamHandlerPattern = {
   readonly kind: "streamHandler";
   readonly source: SourceLocation;
   readonly handlerName?: string;
   readonly schemaSource?: SourceLocation;
   readonly handlerBody?: SourceLocation;
-  readonly access?: AccessRule;
-  readonly rateLimit?: RateLimitOption;
+  readonly access?: AccessRule | RawRefSentinel;
+  readonly rateLimit?: RateLimitDeclaration | RawRefSentinel;
+  readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
 };
 
 // `r.hook(type, target, fn, options?)` — attaches a lifecycle hook
@@ -447,7 +454,7 @@ export type HookPattern = {
   readonly target: string | readonly string[] | { readonly allOf: string };
   readonly fnBody: SourceLocation;
   readonly phase?: HookPhase;
-  readonly escapeHatch?: EscapeHatchDeclaration;
+  readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
 };
 
 // `r.job(name, options, handler)` — registers a background job, qualified

package/src/engine/feature-ast/render.ts

@@ -436,6 +436,7 @@ function renderStreamHandler(p: StreamHandlerPattern): string {
   lines.push(`  handler: ${reindentBody(p.handlerBody?.raw ?? "", PATTERN_INDENT)},`);
   if (p.access !== undefined) lines.push(`  access: ${renderValue(p.access)},`);
   if (p.rateLimit !== undefined) lines.push(`  rateLimit: ${renderValue(p.rateLimit)},`);
+  if (p.escapeHatch !== undefined) lines.push(`  escapeHatch: ${renderValue(p.escapeHatch)},`);
   lines.push("});");
   return lines.join("\n");
 }

package/src/engine/feature-ui-extensions.ts

@@ -229,9 +229,9 @@ export function buildUiExtensionsMethods<TName extends string>(
     useExtension(
       extensionNameOrDefinition:
         | string
-        | ({ readonly name: string; readonly entity: NameOrRef } & Record<string, unknown>),
+        | ({ readonly name: string; readonly entity: NameOrRef } & object),
       entityRef?: NameOrRef,
-      options?: Record<string, unknown>,
+      options?: object,
     ): void {
       const [extensionName, resolvedEntityRef, resolvedOptions] =
         typeof extensionNameOrDefinition === "string"
@@ -241,11 +241,12 @@ export function buildUiExtensionsMethods<TName extends string>(
               return [name, entity, rest] as const;
             })();
       const resolvedEntityName = resolveName(resolvedEntityRef);
+      // @cast-boundary engine-bridge — typed per-extension options → erased registration bag
+      const optionsBag = resolvedOptions as Record<string, unknown> | undefined;
       // fw#2914 — cross-cutting escapeHatch convention for hook-context db
-      // access (mirrors r.hook's validation above). Not part of a typed
-      // per-extension options shape: useExtension's bag stays generic, but
-      // this one key is validated for every extension the same way.
-      const escapeHatch = resolvedOptions?.["escapeHatch"];
+      // access (mirrors r.hook's validation above). Validated the same way
+      // for every extension regardless of its typed hook shape.
+      const escapeHatch = optionsBag?.["escapeHatch"];
       if (escapeHatch !== undefined) {
         const reason =
           typeof escapeHatch === "object" && escapeHatch !== null
@@ -261,7 +262,7 @@ export function buildUiExtensionsMethods<TName extends string>(
       state.extensionUsages.push({
         extensionName,
         entityName: resolvedEntityName,
-        options: resolvedOptions,
+        options: optionsBag,
       });
     },
     extensionSelector(extensionName: string, key: { readonly name: string } | string): void {

package/src/engine/index.ts

@@ -98,7 +98,7 @@ export {
 export { declareEscapeHatch } from "./escape-hatch-declaration";
 export type { EmitCtx } from "./event-helpers";
 export { emitEvent, typedPayload } from "./event-helpers";
-export type { KumikoExtensionName } from "./extension-names";
+export type { KumikoExtensionName, TenantResourceExtensionName } from "./extension-names";
 export {
   EXT_DERIVATIVE_OVERLAY_RESOLVER,
   EXT_DERIVATIVE_PUBLIC_PREDICATE,
@@ -124,11 +124,18 @@ export type {
   StorageProviderExtensionHooks,
   StorageProviderHookCtx,
 } from "./extensions/storage-provider";
-export type {
-  TenantDataDestroyHook,
-  TenantDataExtensionHooks,
-  TenantDataHookCtx,
+export {
+  isTenantDataExtensionHooks,
+  type TenantDataDestroyHook,
+  type TenantDataExtensionHooks,
+  type TenantDataHookCtx,
 } from "./extensions/tenant-data";
+export {
+  isTenantResourceExtensionHooks,
+  type TenantResourceDestroyHook,
+  type TenantResourceExtensionHooks,
+  type TenantResourceHookCtx,
+} from "./extensions/tenant-resource";
 export type {
   TenantUserModel,
   UserDataDeleteHook,
@@ -136,6 +143,7 @@ export type {
   UserDataExportHook,
   UserDataExportSnippet,
   UserDataExtensionHooks,
+  UserDataExtensionOptions,
   UserDataHookCtx,
   UserDataStorageProvider,
 } from "./extensions/user-data";
@@ -178,10 +186,13 @@ export type {
   FormFieldLabel,
   FormFieldSpec,
   FormInputType,
+  HandlerHeaderUpdate,
   ParseError,
   ParseResult,
   PatternCategory,
   PatternChange,
+  PatternChangeIssue,
+  PatternChangesParseResult,
   PatternFormSchema,
   PatternId,
   RenderFeatureFileInput,
@@ -195,11 +206,13 @@ export {
   groupByCategory,
   PATTERN_LIBRARY,
   parseFeatureFile,
+  parsePatternChanges,
   parseSourceFile,
   removePattern,
   renderFeatureFile,
   renderPattern,
   replacePattern,
+  updatePattern,
   VERSION_HEADER,
 } from "./feature-ast";
 export {
@@ -392,6 +405,8 @@ export type {
   EscapeHatchTarget,
   EscapeHatchUseEvent,
   EventDef,
+  ExtensionOptionsArgs,
+  ExtensionOptionsFor,
   FeatureDefinition,
   FeatureRegistrar,
   FieldAccess,
@@ -419,6 +434,7 @@ export type {
   JsonbFieldDef,
   KumikoEntityTypeMap,
   KumikoEventTypeMap,
+  KumikoExtensionOptionsMap,
   KumikoHandlerPayloadMap,
   KumikoHandlerResultMap,
   LifecycleHookType,

package/src/engine/types/extension-options-map.ts

@@ -0,0 +1 @@
+export type * from "@cosmicdrift/kumiko-types/extension-options-map";

package/src/engine/types/index.ts

@@ -72,6 +72,12 @@ export type {
   KumikoHandlerPayloadMap,
   KumikoHandlerResultMap,
 } from "@cosmicdrift/kumiko-types/event-type-map";
+// Cross-Feature Compile-Time-Type-Map for r.useExtension options — mirrors KumikoEventTypeMap above.
+export type {
+  ExtensionOptionsArgs,
+  ExtensionOptionsFor,
+  KumikoExtensionOptionsMap,
+} from "@cosmicdrift/kumiko-types/extension-options-map";
 export type {
   BootCheckContext,
   BootCheckFn,

package/src/event-store/__tests__/event-attribution.integration.test.ts

@@ -14,12 +14,13 @@
 //      and stay readable without the new fields.
 
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
-import { UNATTRIBUTED_ORIGIN } from "@cosmicdrift/kumiko-types/event-store-types";
+import { UNATTRIBUTED_ORIGIN, type WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
 import { z } from "zod";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { selectMany } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";
 import { createEntity, createTextField, defineFeature } from "../../engine";
+import type { TenantId } from "../../engine/types";
 import {
   resetEventStore,
   setupTestStack,
@@ -43,8 +44,11 @@ const orderTable = buildEntityTable("attr-order", orderEntity);
 
 const PLACED = "attribution:event:placed";
 const CONFIRMED = "attribution:event:confirmed";
+const PROBED = "attribution:event:probed";
 const PLACE_HANDLER = "attribution:write:order:place";
+const PROBE_HANDLER = "attribution:write:order:probe";
 const CONFIRMER_MSP = "attribution:projection:confirmer";
+const TENANT_ID = "00000000-0000-4000-8000-000000000002" as TenantId;
 
 const attributionFeature = defineFeature("attribution", (r) => {
   r.entity("attr-order", orderEntity);
@@ -75,6 +79,26 @@ const attributionFeature = defineFeature("attribution", (r) => {
     { access: { roles: ["Admin"] } },
   );
 
+  const probed = r.defineEvent("probed", z.object({ orderId: z.uuid() }), { piiFields: "none" });
+
+  // Anonymous, no public-intake declared, no PII field written (nothing to gate).
+  r.writeHandler(
+    "order:probe",
+    z.object({ item: z.string() }),
+    async (event, ctx) => {
+      const created = await orderExecutor.create({ item: event.payload.item }, event.user, ctx.db);
+      if (!created.isSuccess) return created;
+      await ctx.unsafeAppendEvent({
+        aggregateId: String(created.data.id),
+        aggregateType: "attr-order",
+        type: probed.name,
+        payload: { orderId: String(created.data.id) },
+      });
+      return created;
+    },
+    { access: { roles: ["anonymous"] } },
+  );
+
   r.multiStreamProjection({
     name: "confirmer",
     apply: {
@@ -95,7 +119,11 @@ let stack: TestStack;
 const admin = TestUsers.admin;
 
 beforeAll(async () => {
-  stack = await setupTestStack({ features: [attributionFeature], systemHooks: [] });
+  stack = await setupTestStack({
+    features: [attributionFeature],
+    systemHooks: [],
+    anonymousAccess: { defaultTenantId: TENANT_ID },
+  });
   await unsafeCreateEntityTable(stack.db, orderEntity, "attr-order");
 });
 
@@ -107,7 +135,7 @@ afterEach(async () => {
   await resetEventStore(stack, ["read_attribution_orders"]);
 });
 
-type Origin = { feature?: string; handler?: string };
+type Origin = { feature?: string; handler?: string; writeOrigin?: WriteOrigin };
 
 async function originOf(type: string): Promise<Origin> {
   const rows = await selectMany(stack.db, eventsTable);
@@ -165,6 +193,28 @@ describe("#3043 — event attribution from the execution scope", () => {
     });
   });
 
+  test("authenticated write: the event carries no writeOrigin at all", async () => {
+    await stack.http.writeOk(PLACE_HANDLER, { item: "cog" }, admin);
+
+    const origin = await originOf(PLACED);
+    expect(origin.writeOrigin).toBeUndefined();
+  });
+
+  test("anonymous non-intake write: the event is stamped with the gated origin", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: PROBE_HANDLER,
+      payload: { item: "washer" },
+    });
+    expect(res.status).toBe(200);
+
+    const origin = await originOf(PROBED);
+    expect(origin.writeOrigin).toMatchObject({
+      rootHandler: PROBE_HANDLER,
+      anonymousRoot: true,
+      publicIntake: false,
+    });
+  });
+
   test("appendRaw keeps historical metadata verbatim and stays readable", async () => {
     const aggregateId = uuid();
     await appendRaw(stack.db, {

package/src/event-store/admin-api.ts

@@ -9,6 +9,7 @@
 
 import type { DbRunner } from "../db";
 import { constraintOf, isUniqueViolation } from "../db/pg-error";
+import { claimXactId } from "../db/queries/event-store";
 import {
   eventPredecessorExists,
   findExistingEventVersion,
@@ -54,6 +55,9 @@ export async function appendRaw(runner: DbRunner, event: RawEventToAppend): Prom
   const eventVersion = event.eventVersion ?? 1;
 
   try {
+    // See db/queries/event-store.ts's claimXactId — gap-finality needs a
+    // real xact id assigned before this holder's insert.
+    await claimXactId(runner);
     if (event.expectedVersion === 0) {
       await insertRawFirst(runner, event, newVersion, eventVersion);
     } else {
@@ -145,6 +149,7 @@ export async function appendRawBatch(
   });
 
   try {
+    await claimXactId(runner);
     await insertRawEventBatch(runner, valuesClauses.join(", "), params);
   } catch (e) {
     if (isUniqueViolation(e)) {

package/src/event-store/event-store.ts

@@ -1,5 +1,6 @@
 import {
   type EventMetadata,
+  isPersonalDataGated,
   type StoredEvent,
   UNATTRIBUTED_ORIGIN,
 } from "@cosmicdrift/kumiko-types/event-store-types";
@@ -15,6 +16,7 @@ import { encryptEventPayloadPii } from "../crypto/event-pii";
 import type { DbRunner } from "../db";
 import { constraintOf, isUniqueViolation } from "../db/pg-error";
 import {
+  claimXactId,
   insertSubsequentEventRow,
   notifyPgChannel,
   selectAggregateMaxVersion,
@@ -93,14 +95,16 @@ export async function append(db: DbRunner, event: EventToAppend): Promise<Stored
   const eventVersion = toStore.eventVersion ?? 1;
 
   try {
+    await claimXactId(db);
+
     const row =
       toStore.expectedVersion === 0
         ? await insertFirstEvent(db, toStore, newVersion, eventVersion)
         : await insertSubsequentEvent(db, toStore, newVersion, eventVersion);
 
-    // NOTIFY fires on commit (PG buffers NOTIFY per TX), so subscribers never
-    // see a wake-up for an event that later rolled back. Harmless no-op when
-    // no LISTENer is attached.
+    // NOTIFY after the INSERT: outside a transaction each statement commits
+    // on its own, so a NOTIFY sent first would wake the dispatcher before
+    // the row exists.
     await notifyPgChannel(db, EVENTS_PUBSUB_CHANNEL);
 
     return buildStoredEvent(toStore, newVersion, eventVersion, row);
@@ -127,12 +131,15 @@ export async function append(db: DbRunner, event: EventToAppend): Promise<Stored
 // bypass this deliberately — they replay historical rows verbatim.
 function stampOrigin(event: EventToAppend): EventToAppend {
   const origin = requestContext.get();
+  const { writeOrigin: _droppedCallerWriteOrigin, ...restMetadata } = event.metadata;
   return {
     ...event,
     metadata: {
-      ...event.metadata,
+      ...restMetadata,
       feature: origin?.feature ?? UNATTRIBUTED_ORIGIN,
       handler: origin?.handler ?? UNATTRIBUTED_ORIGIN,
+      ...(origin?.writeOrigin &&
+        isPersonalDataGated(origin.writeOrigin) && { writeOrigin: origin.writeOrigin }),
     },
   };
 }
@@ -380,9 +387,11 @@ export async function loadAllEventsByType(
 
 // Stream every event for an aggregate_type across all tenants, batchwise
 // instead of buffered. Memory-bounded: never more than `batchSize` rows
-// resident. Cursor walks `events.id` (bigserial monotonic — concurrent
-// inserts get distinct ids in commit order, so no duplicates and no skips
-// past the cursor).
+// resident. Cursor walks `events.id` (bigserial monotonic, but ids are
+// assigned at INSERT time, not commit time — a sweep can overtake a still-
+// open transaction and its lower id, same gap the event-dispatcher's
+// pending_gaps tracks). Fine for this generator's use case: history sweeps
+// (projection-rebuild, tests) that don't need live, just-committed rows.
 //
 // Use case: projection-rebuild on a large event log (>100k events per
 // aggregate-type). loadAllEventsByType would OOM; this iterator yields