@cosmicdrift/kumiko-framework 0.1.0

package/src/engine/pattern-library/types.ts

@@ -0,0 +1,255 @@
+// Forms-Schema metadata — describes how a FeaturePattern is rendered as
+// a Designer form, fed to an LLM as a JSON-Schema, or surfaced in the
+// MCP-Server tool list. One schema, three consumers — that's the whole
+// point of factoring this out of the hand-rolled C5 skeleton.
+//
+// **NOT a DSL.** The Source-of-Truth for a feature stays
+// `defineFeature.ts` — the AST-visitor (feature-ast/parse.ts) reads it
+// and the renderer (feature-ast/render.ts) writes it. This file is
+// pure metadata for UI / LLM-prompt rendering: how to display the
+// already-parsed FeaturePattern in a form. No alternative parser, no
+// alternative syntax, no second canonical representation.
+//
+// **Vokabular** (12 input-types):
+//
+//   text                  — single-line string (name / label / id)
+//   textarea              — multi-line string (description / SQL / readme)
+//   number                — numeric (version / fromVersion / rateLimit.limit)
+//   boolean               — checkbox (softDelete / default / openToAll)
+//   select                — closed enum (idType / hookType / method)
+//   string-list           — readonly string[] (featureNames / roles)
+//   code-block            — opaque TS source-span, read-only in the form
+//                            (schemaSource / handlerBody / fnBody)
+//   entity-fields-editor  — per-row editor for EntityDefinition.fields
+//   key-value-map         — generic { [key]: structured-value } editor
+//                            (config.keys / translations.keys / applyBodies)
+//   discriminated-union   — tagged sub-form (AccessRule: roles vs openToAll)
+//   entity-ref            — string with autocomplete against the registry
+//   json-readonly         — opaque pretty-printed JSON (Unknown / extension)
+//
+// **Path notation:** `path` references the value's location inside the
+// FeaturePattern object using dot-separated keys (`definition.fields`,
+// `access.roles`, `templates.email`). Numeric indices use the bracket
+// form (`columns.0`). The Designer/LLM uses paths for read & write —
+// the patcher (C2) consumes pattern-level updates only, so paths are
+// purely a UI concern at this stage.
+
+import type { FeaturePatternKind } from "../feature-ast/patterns";
+
+// =============================================================================
+// Field input types
+// =============================================================================
+
+export type FormInputType =
+  | "text"
+  | "textarea"
+  | "number"
+  | "boolean"
+  | "select"
+  | "string-list"
+  | "code-block"
+  | "entity-fields-editor"
+  | "key-value-map"
+  | "discriminated-union"
+  | "entity-ref"
+  | "json-readonly";
+
+// =============================================================================
+// Field spec — one entry per editable property of a pattern
+// =============================================================================
+
+/**
+ * Bilingual labels — Designer renders the user's locale, falls back to
+ * `en`. AI-Builder uses `en` exclusively (cheaper prompts, single
+ * grounding language for the model).
+ */
+export type FormFieldLabel = {
+  readonly en: string;
+  readonly de?: string;
+};
+
+/**
+ * Common shape every field carries — the input-specific fields are added
+ * by the discriminated subtypes below.
+ */
+type FormFieldBase = {
+  /**
+   * Dot/bracket-path inside the FeaturePattern. e.g. "entityName",
+   * "definition.fields", "access.roles", "templates.email".
+   */
+  readonly path: string;
+  readonly label: FormFieldLabel;
+  /**
+   * Short hint shown below the input. Optional — keep terse, the
+   * Designer / LLM is the doc consumer, not the casual reader.
+   */
+  readonly hint?: FormFieldLabel;
+  /**
+   * Whether the form should refuse to submit when this field is empty.
+   * Defaults to `false`. Validation runs *before* the patch hits the
+   * file — caller-side guard.
+   */
+  readonly required?: boolean;
+  /**
+   * Read-only fields are surfaced for context but never edited (e.g.
+   * `kind` discriminator, opaque source-spans on mixed patterns).
+   */
+  readonly readOnly?: boolean;
+};
+
+export type TextField = FormFieldBase & {
+  readonly input: "text";
+  readonly placeholder?: string;
+  readonly maxLength?: number;
+  readonly pattern?: string;
+};
+
+export type TextareaField = FormFieldBase & {
+  readonly input: "textarea";
+  readonly placeholder?: string;
+  readonly rows?: number;
+};
+
+export type NumberField = FormFieldBase & {
+  readonly input: "number";
+  readonly min?: number;
+  readonly max?: number;
+  readonly step?: number;
+};
+
+export type BooleanField = FormFieldBase & {
+  readonly input: "boolean";
+};
+
+export type SelectOption = {
+  readonly value: string;
+  readonly label: FormFieldLabel;
+};
+
+export type SelectField = FormFieldBase & {
+  readonly input: "select";
+  readonly options: readonly SelectOption[];
+};
+
+export type StringListField = FormFieldBase & {
+  readonly input: "string-list";
+  /** Per-item placeholder, e.g. "feature-name". */
+  readonly itemPlaceholder?: string;
+};
+
+export type CodeBlockField = FormFieldBase & {
+  readonly input: "code-block";
+  /**
+   * The source language for syntax highlighting. The skeleton renders
+   * everything as plain TS; later iterations can branch on `zod` /
+   * `tsx` for dedicated highlighters.
+   */
+  readonly language: "typescript" | "tsx" | "zod";
+};
+
+/**
+ * Editor for `EntityDefinition.fields` — a row per field with name,
+ * type-discriminator, plus type-specific knobs. Modeled as a single
+ * input-type because the structure is too rich for a generic
+ * key-value-map (each row's right-hand side is itself a discriminated
+ * union over FieldDefinition variants).
+ */
+export type EntityFieldsEditorField = FormFieldBase & {
+  readonly input: "entity-fields-editor";
+};
+
+/**
+ * Generic `{ [key]: value }` editor — value-shape is described by an
+ * inner FormSchema applied to each entry. Used for config-keys,
+ * translations, projection.applyBodies, notification.templates.
+ */
+export type KeyValueMapField = FormFieldBase & {
+  readonly input: "key-value-map";
+  /** Placeholder for new keys. */
+  readonly keyPlaceholder?: string;
+  /** What input renders for each value. Recursive — keep it simple. */
+  readonly valueInput: FormInputType;
+};
+
+export type DiscriminatedUnionField = FormFieldBase & {
+  readonly input: "discriminated-union";
+  /** Tag-property name (e.g. "type" for hook-target, "kind" for relation). */
+  readonly discriminator: string;
+  /** Each branch carries its own field-list. */
+  readonly variants: ReadonlyArray<{
+    readonly tag: string;
+    readonly label: FormFieldLabel;
+    readonly fields: readonly FormFieldSpec[];
+  }>;
+};
+
+export type EntityRefField = FormFieldBase & {
+  readonly input: "entity-ref";
+  /**
+   * If true, the input also accepts cross-feature references like
+   * `auth:event:loggedIn`. Default is feature-local only.
+   */
+  readonly allowQualified?: boolean;
+};
+
+export type JsonReadonlyField = FormFieldBase & {
+  readonly input: "json-readonly";
+};
+
+export type FormFieldSpec =
+  | TextField
+  | TextareaField
+  | NumberField
+  | BooleanField
+  | SelectField
+  | StringListField
+  | CodeBlockField
+  | EntityFieldsEditorField
+  | KeyValueMapField
+  | DiscriminatedUnionField
+  | EntityRefField
+  | JsonReadonlyField;
+
+// =============================================================================
+// Pattern schema — top-level metadata for one FeaturePattern kind
+// =============================================================================
+
+/**
+ * High-level grouping the Designer uses for navigation: data shapes
+ * (entity / relation), behaviour (handler / hook), UI (screen / nav),
+ * meta (config / metric / secret), background (job / projection),
+ * cross-cutting (notification / authClaims / httpRoute), advanced
+ * (extendsRegistrar / unknown). Order in the Designer panel is alpha
+ * inside a category.
+ */
+export type PatternCategory =
+  | "data"
+  | "behaviour"
+  | "ui"
+  | "meta"
+  | "background"
+  | "cross-cutting"
+  | "advanced";
+
+export type PatternFormSchema = {
+  readonly kind: FeaturePatternKind;
+  readonly label: FormFieldLabel;
+  /** Short blurb shown in the Designer's "add new pattern" dialog. */
+  readonly summary: FormFieldLabel;
+  readonly category: PatternCategory;
+  /**
+   * Editability matches feature-ast's `getEditability()`:
+   *   - "static"  → fully form-driven, no closures
+   *   - "mixed"   → header is form, body is opaque code-block
+   *   - "opaque"  → entire pattern is read-only
+   */
+  readonly editability: "static" | "mixed" | "opaque";
+  /**
+   * Singleton kinds appear at most once per feature (requires,
+   * toggleable, config, …). The Designer hides "Add" once the
+   * singleton is present.
+   */
+  readonly singleton?: boolean;
+  /** Ordered list of editable fields. */
+  readonly fields: readonly FormFieldSpec[];
+};

package/src/engine/projection-helpers.ts

@@ -0,0 +1,85 @@
+import { eq } from "drizzle-orm";
+import type { DbRunner } from "../db/connection";
+import type { StoredEvent } from "../event-store/event-store";
+import type { MultiStreamApplyContext } from "../pipeline/multi-stream-apply-context";
+import type { MultiStreamApplyFn, ProjectionTable, SingleStreamApplyFn } from "./types/projection";
+
+// Typed-Apply-Helper für r.projection.apply: erlaubt per-event-type
+// typed event.payload-Access ohne SingleStreamApplyFn-Generic durch die
+// ganze ProjectionDefinition propagieren zu müssen.
+//
+// Der Helper ist ein purer Type-Vehikel — zur Laufzeit identitäts-fn:
+//
+//   apply: {
+//     "user.created": defineApply<UserCreatedPayload>(async (event, tx) => {
+//       // event.payload ist UserCreatedPayload, nicht Record<string, unknown>
+//       await tx.insert(usersTable).values({ id: event.aggregateId, ...event.payload });
+//     }),
+//   }
+//
+// Default-Generic = Record<string, unknown> behält rückwärtskompatibles
+// Verhalten für Apply-Handler die ohne Type-Argument geschrieben sind.
+export function defineApply<TPayload = Record<string, unknown>>(
+  fn: (event: StoredEvent<TPayload>, tx: DbRunner) => Promise<void>,
+): SingleStreamApplyFn {
+  // @cast-boundary engine-bridge — typed user-fn → erased internal storage
+  return fn as SingleStreamApplyFn;
+}
+
+// Pendant für r.multiStreamProjection.apply — bekommt zusätzlich ctx.
+export function defineMspApply<TPayload = Record<string, unknown>>(
+  fn: (event: StoredEvent<TPayload>, tx: DbRunner, ctx: MultiStreamApplyContext) => Promise<void>,
+): MultiStreamApplyFn {
+  // @cast-boundary engine-bridge — typed user-fn → erased internal storage
+  return fn as MultiStreamApplyFn;
+}
+
+// UPDATE <projection-table> SET <fields> WHERE id = event.aggregateId.
+// The "event drives one row by aggregate id" shape is what 90 % of state-
+// machine projections look like: every status-change event maps to a single
+// column update on the projection's own row. Pass a literal object for
+// fixed values, or a reducer-style function when the new value comes from
+// the event payload.
+//
+//   r.projection({
+//     name: "invoice-status",
+//     source: "invoice",
+//     table: invoiceTable,
+//     apply: {
+//       [INVOICE.sent]: setFields(invoiceTable, { status: "sent" }),
+//       [INVOICE.statusForced]: setFields(invoiceTable, (e) => {
+//         const p = e.payload as { newStatus: InvoiceStatus };
+//         return { status: p.newStatus };
+//       }),
+//     },
+//   });
+//
+// The projection table must expose an `id` column typed as the aggregate's
+// stream id — every executor-managed aggregate table does. Use a raw apply
+// function when the update targets a different key or needs JOIN/SET logic.
+export function setFields(
+  table: ProjectionTable,
+  fields:
+    | Record<string, unknown>
+    | ((event: Parameters<SingleStreamApplyFn>[0]) => Record<string, unknown>),
+): SingleStreamApplyFn {
+  const idCol = (table as Record<string, unknown>)["id"]; // @cast-boundary dynamic-key
+  if (!idCol) {
+    throw new Error(
+      "setFields: projection table has no 'id' column — pass a custom apply function for tables keyed on another column.",
+    );
+  }
+  return async (event, tx) => {
+    const values = typeof fields === "function" ? fields(event) : fields;
+    // ProjectionTable erases its column shape on purpose (the framework
+    // does not know user table shapes). Drizzle's tx.update().set() is
+    // strict about the concrete row, so we feed it the erased value; the
+    // type-safety guarantee for `values` lives at the setFields call-site.
+    // biome-ignore lint/suspicious/noExplicitAny: see note above.
+    const set = values as any;
+    await tx
+      .update(table)
+      .set(set)
+      .where(eq(idCol as never, event.aggregateId)); // @cast-boundary db-operator
+  };
+}

package/src/engine/qualified-name.ts

@@ -0,0 +1,122 @@
+// Qualified Name (QN) system: unified naming pattern for all framework identifiers.
+// Pattern: "scope:type:name" — colon-separated, kebab-case segments.
+//
+// The name part can contain colons for sub-structure (e.g. "task:create").
+// Scope and type are always single segments. Name is everything after the second colon.
+//
+// Examples:
+//   "tasks:write:task:create"      → scope=tasks, type=write, name=task:create
+//   "system:hook:search-index"     → scope=system, type=hook, name=search-index
+//   "billing:notify:invoice-sent"  → scope=billing, type=notify, name=invoice-sent
+
+// Built-in QN types used by the framework.
+// Features can define additional types — the type segment is validated for format only, not membership.
+export const QnTypes = {
+  write: "write",
+  query: "query",
+  hook: "hook",
+  job: "job",
+  notify: "notify",
+  event: "event",
+  channel: "channel",
+  config: "config",
+  secret: "secret",
+  screen: "screen",
+  nav: "nav",
+} as const;
+
+export type BuiltinQnType = (typeof QnTypes)[keyof typeof QnTypes];
+
+// QnType is string — framework types are predefined, but features can use custom types.
+export type QnType = string;
+
+const QN_SEGMENT = /^[a-z][a-z0-9-]*$/;
+
+export type ParsedQn = {
+  scope: string;
+  type: string;
+  name: string; // may contain colons (e.g. "task:create")
+};
+
+function validateSegment(value: string, label: string, context?: string): void {
+  if (!QN_SEGMENT.test(value)) {
+    const suffix = context ? ` in "${context}"` : "";
+    throw new Error(`Invalid QN ${label} "${value}"${suffix}: must match ${QN_SEGMENT}`);
+  }
+}
+
+// Build a qualified name from parts. Validates all segments.
+// The name can contain colons for sub-structure (e.g. "task:create").
+export function qn(scope: string, type: QnType, name: string): string {
+  validateSegment(scope, "scope");
+  validateSegment(type, "type");
+  for (const part of name.split(":")) {
+    validateSegment(part, "name");
+  }
+  return `${scope}:${type}:${name}`;
+}
+
+// Parse a qualified name string into its parts.
+// Splits on the first two colons — everything after is the name (which may contain colons).
+export function parseQn(value: string): ParsedQn {
+  const first = value.indexOf(":");
+  if (first < 0)
+    throw new Error(`Invalid QN "${value}": expected at least 3 colon-separated segments`);
+  const second = value.indexOf(":", first + 1);
+  if (second < 0)
+    throw new Error(`Invalid QN "${value}": expected at least 3 colon-separated segments`);
+
+  const scope = value.slice(0, first);
+  const type = value.slice(first + 1, second);
+  const name = value.slice(second + 1);
+
+  validateSegment(scope, "scope", value);
+  validateSegment(type, "type", value);
+  for (const part of name.split(":")) {
+    validateSegment(part, "name", value);
+  }
+
+  return { scope, type, name };
+}
+
+// Check if a string is a valid qualified name.
+export function isValidQn(value: string): boolean {
+  try {
+    parseQn(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// True if `name` is a valid QN segment (lowercase letters, digits, dashes;
+// starts with a letter). Same rule as `QN_SEGMENT` — kept public so feature
+// registration can reject bad names at the source instead of at registry-boot.
+export function isKebabSegment(name: string): boolean {
+  return QN_SEGMENT.test(name);
+}
+
+// Build a fully-qualified entity name from a feature name + QN type + short
+// name, running both names through toKebab first. This is the canonical
+// "how the registry qualifies things" helper — both createRegistry and
+// validateBoot need it, and they previously duplicated the literal
+// `qn(toKebab(feature), type, toKebab(short))` expression. Keeping it here
+// means a single place to change if the qualification rule ever evolves.
+export function qualifyEntityName(featureName: string, type: QnType, shortName: string): string {
+  return qn(toKebab(featureName), type, toKebab(shortName));
+}
+
+// Convert camelCase or dot.separated strings to kebab-case.
+// "task.create" → "task-create"
+// "ticketAssigned" → "ticket-assigned"
+// "billing-period.create" → "billing-period-create"
+// "monthlyReport" → "monthly-report"
+// Already kebab-case → unchanged
+// Colons are preserved: "task:create" → "task:create"
+export function toKebab(input: string): string {
+  return input
+    .replace(/\./g, "-") // dots → dashes
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2") // consecutive uppercase: SSEBroadcast → SSE-Broadcast
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2") // camelCase boundaries: ticketAssigned → ticket-Assigned
+    .toLowerCase();
+}

package/src/engine/read-claim.ts

@@ -0,0 +1,31 @@
+import type { ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, SessionUser } from "./types";
+
+// Read a feature-declared claim from a SessionUser.
+//
+// The generic is inferred from the handle's `type` literal, so call sites
+// get the right narrowed return type without a cast:
+//
+//   const DriverClaims = r.claimKeys(...);
+//   const teamId = readClaim(user, DriverClaims.teamId);    // string | undefined
+//   const regionId = readClaim(user, DriverClaims.regionId); // number | undefined
+//
+// Returns undefined when:
+// - user.claims is absent entirely (hook system didn't populate anything)
+// - the specific handle's qualified name isn't in user.claims (feature's
+//   r.authClaims hook didn't return this inner-key for this user)
+//
+// The cast is unchecked. The declared handle type is a contract between the
+// feature's r.claimKey + r.authClaims return; the resolver's runtime check
+// flags drift with a warning, but readClaim itself trusts the declaration.
+// If you need schema-level validation of a claim value, wrap it with zod
+// at the call-site.
+export function readClaim<T extends ClaimKeyType>(
+  user: SessionUser,
+  handle: ClaimKeyHandle<T>,
+): ClaimKeyJsType<T> | undefined {
+  const claims = user.claims;
+  if (!claims) return undefined;
+  const raw = claims[handle.name];
+  if (raw === undefined || raw === null) return undefined;
+  return raw as ClaimKeyJsType<T>;
+}