@cosmicdrift/kumiko-framework 0.385.0 → 0.387.0

package/dist/engine/extension-names.d.ts

@@ -8,14 +8,14 @@ import type { UserDataExtensionOptions } from "./extensions/user-data.ts";
 import type { AssignableFromRole } from "./role-assignment.ts";
 import { TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin } from "./tier-resolver-extension.ts";
 /**
- * `userData` — User-Daten-Rights-Hooks (DSGVO Art. 15 + 17 + 20).
+ * `userData` — user-data rights hooks (GDPR Articles 15, 17, and 20).
  *
- * Erwartete Hook-Methoden:
+ * Expected hook methods:
  *   - `export(userId, ctx) => Promise<UserDataExport>`
  *   - `delete(userId, strategy: "delete" | "anonymize", ctx) => Promise<void>`
  *
- * Registriert von: `user-data-rights` (Sprint 2).
- * Genutzt von: jedes Feature mit User-Referenzen (tasks, comments, files, ...).
+ * Registered by: `user-data-rights`.
+ * Used by: every feature with user references (tasks, comments, files, ...).
  */
 export declare const EXT_USER_DATA: "userData";
 export declare const EXT_USER_DATA_ORDER: {
@@ -41,17 +41,16 @@ export declare const EXT_TENANT_DATA: "tenantData";
  */
 export declare const EXT_STORAGE_PROVIDER: "storageProvider";
 /**
- * `fileProvider` — File-Storage-Provider-Plugin-Selection (file-foundation).
+ * `fileProvider` — file-storage provider plugin selection (file-foundation).
  *
- * Provider-Features (file-provider-s3, -inmemory, -s3-env) registrieren eine
- * Implementierung via `r.useExtension(EXT_FILE_PROVIDER, "<name>", { build })`;
- * der per-Tenant Config-Key `provider` waehlt zur Runtime eine aus. Der
- * Framework-Resolver (`createFileProviderForTenant`) liest das, damit Upload-
- * Routes, `ctx.files` UND die DSGVO-Jobs denselben Store treffen.
+ * Provider features (file-provider-s3, -inmemory, -s3-env) register an
+ * implementation via `r.useExtension(EXT_FILE_PROVIDER, "<name>", { build })`;
+ * the per-tenant config key `provider` selects one at runtime. The framework
+ * resolver (`createFileProviderForTenant`) reads it so upload routes,
+ * `ctx.files`, and GDPR jobs all use the same store.
  *
- * Framework-seitig besessen, damit kein String-Drift entsteht — file-
- * foundation MUSS Extension-Point + Config-Key unter genau diesen Namen
- * registrieren.
+ * The framework owns this contract to prevent string drift — file-foundation
+ * MUST register the extension point and config key under exactly these names.
  */
 export declare const EXT_FILE_PROVIDER: "fileProvider";
 export declare const FILE_PROVIDER_CONFIG_KEY: "file-foundation:config:provider";
@@ -85,7 +84,7 @@ export declare const EXT_DERIVATIVE_RENDERER: "derivativeRenderer";
  * serves nothing for that entityType, not even a 403 (404, so existence isn't
  * confirmed to an unauthorised caller).
  *
- * Registered/consumed by: `file-derivatives`' public variant route (#1951).
+ * Registered/consumed by: `file-derivatives`' public variant route.
  */
 export declare const EXT_DERIVATIVE_PUBLIC_PREDICATE: "derivativePublicPredicate";
 /**
@@ -150,9 +149,9 @@ export declare const EXT_TENANT_LIFECYCLE_STATUS: "tenantLifecycleStatus";
 export declare const EXT_ASSIGNABLE_ROLE: "assignableRole";
 export declare const TENANT_MEMBERSHIPS_QUERY: "tenant:query:memberships";
 /**
- * Union aller standardisierten Extension-Namen der Datenschutz-Surface.
- * Nicht alle Extensions im System sind in dieser Liste — andere
- * Features koennen weiterhin eigene Extension-Namen registrieren.
+ * Union of standardized extension names for the privacy surface.
+ * Not every extension in the system is included — other features can still
+ * register their own extension names.
  */
 export type KumikoExtensionName = typeof EXT_USER_DATA | typeof EXT_TENANT_DATA | typeof EXT_STORAGE_PROVIDER | typeof EXT_SEARCH_ADAPTER | typeof EXT_EXTERNAL_RESOURCE | typeof EXT_INFRA_RESOURCE | typeof EXT_FILE_PROVIDER | typeof EXT_DERIVATIVE_RENDERER | typeof EXT_DERIVATIVE_PUBLIC_PREDICATE | typeof EXT_DERIVATIVE_OVERLAY_RESOLVER | typeof EXT_PRINCIPAL_STATUS | typeof EXT_TENANT_LIFECYCLE_STATUS | typeof EXT_ASSIGNABLE_ROLE;
 /** The four `destroyTenant(tenantId, ctx)`-only resource-cleanup extension points. */

package/dist/engine/extension-names.js

@@ -1,42 +1,42 @@
 import { TENANT_TIER_RESOLVER_EXT } from "./tier-resolver-extension.js";
-// Standardisierte Extension-Namen fuer Datenschutz-Hook-Achsen.
+// Standardized extension names for privacy-hook axes.
 //
-// Features registrieren Extensions via:
+// Features register extensions via:
 //   r.extendsRegistrar(EXT_USER_DATA, { hooks: { ... } });
 //
-// Andere Features haengen sich ein via:
+// Other features attach to them via:
 //   r.useExtension(EXT_USER_DATA, "myEntity", { ...hookImpls });
 //
-// Hintergrund: Magic-Strings driften zwischen Bundled-Features (Beispiel:
-// text-content nutzt "Admin" als Rolle, tenant-handler nutzt "TenantAdmin").
-// Constants sind die einzige Quelle der Wahrheit; String-Literale werden
-// in den Sprint-Touchpoints schrittweise ersetzt. Boot-Validator
-// (validateExtensionUsages) checkt dass jedes useExtension einen
-// passenden extendsRegistrar findet — Tippfehler in Constants →
-// Compile-Time-Fail.
+// Background: magic strings drift between bundled features (for example,
+// text-content uses "Admin" as a role, while tenant-handler uses
+// "TenantAdmin"). Constants are the single source of truth; string literals
+// are gradually replaced at the relevant integration points. The boot
+// validator (validateExtensionUsages) checks that every useExtension has a
+// matching extendsRegistrar, so typos in constants cause a compile-time
+// failure.
 //
-// Hook-Signaturen + Boot-Validation pro Extension-Achse kommen mit dem
-// jeweiligen registrierenden Sprint:
-//   userData / tenantData         → Sprint 2 (user-data-rights, retention)
-//   storageProvider                → Sprint 4 (storage-encryption)
-//   searchAdapter / external /     → Sprint 5 (tenant-lifecycle)
+// Hook signatures and boot validation for each extension axis are added by
+// the feature that registers that axis:
+//   userData / tenantData         → (user-data-rights, retention)
+//   storageProvider                → (storage-encryption)
+//   searchAdapter / external /     → (tenant-lifecycle)
 //   infraResource
 /**
- * `userData` — User-Daten-Rights-Hooks (DSGVO Art. 15 + 17 + 20).
+ * `userData` — user-data rights hooks (GDPR Articles 15, 17, and 20).
  *
- * Erwartete Hook-Methoden:
+ * Expected hook methods:
  *   - `export(userId, ctx) => Promise<UserDataExport>`
  *   - `delete(userId, strategy: "delete" | "anonymize", ctx) => Promise<void>`
  *
- * Registriert von: `user-data-rights` (Sprint 2).
- * Genutzt von: jedes Feature mit User-Referenzen (tasks, comments, files, ...).
+ * Registered by: `user-data-rights`.
+ * Used by: every feature with user references (tasks, comments, files, ...).
  */
 export const EXT_USER_DATA = "userData";
-// Order-Bänder für EXT_USER_DATA-Hooks (forget-Pipeline). Der Kontrakt war
-// implizit über zwei Packages verteilt (-100 in custom-fields, 0 in
-// user-data-rights) — ein Host-Hook mit order < REDACT_BEFORE_OWNER liefe
-// VOR den Redaktoren und brächte den Strip-nach-owner-null-Bug zurück
-// (DSGVO-Art.-17-Regression). Regel: Redaktoren < 0 <= owner-mutierende Hooks.
+// Ordering bands for EXT_USER_DATA hooks (forget pipeline). The contract was
+// implicit across two packages (-100 in custom-fields, 0 in
+// user-data-rights), so a host hook with order < REDACT_BEFORE_OWNER would run
+// BEFORE the redactors and reintroduce the strip-after-owner-null bug
+// (GDPR Article 17 regression). Rule: redactors < 0 <= owner-mutating hooks.
 export const EXT_USER_DATA_ORDER = {
     REDACT_BEFORE_OWNER: -100,
     DEFAULT: 0,
@@ -60,23 +60,22 @@ export const EXT_TENANT_DATA = "tenantData";
  */
 export const EXT_STORAGE_PROVIDER = "storageProvider";
 /**
- * `fileProvider` — File-Storage-Provider-Plugin-Selection (file-foundation).
+ * `fileProvider` — file-storage provider plugin selection (file-foundation).
  *
- * Provider-Features (file-provider-s3, -inmemory, -s3-env) registrieren eine
- * Implementierung via `r.useExtension(EXT_FILE_PROVIDER, "<name>", { build })`;
- * der per-Tenant Config-Key `provider` waehlt zur Runtime eine aus. Der
- * Framework-Resolver (`createFileProviderForTenant`) liest das, damit Upload-
- * Routes, `ctx.files` UND die DSGVO-Jobs denselben Store treffen.
+ * Provider features (file-provider-s3, -inmemory, -s3-env) register an
+ * implementation via `r.useExtension(EXT_FILE_PROVIDER, "<name>", { build })`;
+ * the per-tenant config key `provider` selects one at runtime. The framework
+ * resolver (`createFileProviderForTenant`) reads it so upload routes,
+ * `ctx.files`, and GDPR jobs all use the same store.
  *
- * Framework-seitig besessen, damit kein String-Drift entsteht — file-
- * foundation MUSS Extension-Point + Config-Key unter genau diesen Namen
- * registrieren.
+ * The framework owns this contract to prevent string drift — file-foundation
+ * MUST register the extension point and config key under exactly these names.
  */
 export const EXT_FILE_PROVIDER = "fileProvider";
-// Qualifizierter Config-Key, den das file-foundation-Feature registriert
-// (Format `<feature>:config:<key>`). Akzeptierte Kopplung: der Framework-
-// Resolver liegt UNTER dem Feature und liest den Key per String. Umbenennen
-// des file-foundation-Features MUSS diese Konstante mitziehen.
+// Qualified config key registered by the file-foundation feature
+// (format `<feature>:config:<key>`). This coupling is intentional: the
+// framework resolver is below the feature and reads the key by string. Renaming
+// the file-foundation feature MUST be accompanied by changing this constant.
 export const FILE_PROVIDER_CONFIG_KEY = "file-foundation:config:provider";
 // Two roles: boot gate (validateBoot requires its presence once file/image
 // fields are in use) AND the ENV source of the config key above, bridged via
@@ -114,7 +113,7 @@ export const EXT_DERIVATIVE_RENDERER = "derivativeRenderer";
  * serves nothing for that entityType, not even a 403 (404, so existence isn't
  * confirmed to an unauthorised caller).
  *
- * Registered/consumed by: `file-derivatives`' public variant route (#1951).
+ * Registered/consumed by: `file-derivatives`' public variant route.
  */
 export const EXT_DERIVATIVE_PUBLIC_PREDICATE = "derivativePublicPredicate";
 /**

package/dist/engine/extensions/escape-hatch-usage.js

@@ -1,4 +1,4 @@
-// fw#2914 — reads the { escapeHatch: { reason } } convention off a
+// reads the { escapeHatch: { reason } } convention off a
 // `r.useExtension(...)` registration's untyped options bag. Registration-time
 // validation (feature-ui-extensions.ts's useExtension) already rejects an
 // empty reason, but options stays `Record<string, unknown>`, so orchestrators

package/dist/engine/extensions/tenant-data.js

@@ -1,7 +1,7 @@
-// Hook-Signatur-Types für EXT_TENANT_DATA (DSGVO tenant-scoped destroy).
+// Hook signature types for EXT_TENANT_DATA (GDPR tenant-scoped destruction).
 //
 // Mirror of engine/extensions/user-data.ts at tenant granularity.
-// tenant-lifecycle orchestrates destroy via registry.getExtensionUsages(EXT_TENANT_DATA).
+// tenant-lifecycle orchestrates destruction via registry.getExtensionUsages(EXT_TENANT_DATA).
 export function isTenantDataExtensionHooks(o) {
     return typeof o === "object" && o !== null && "destroy" in o && typeof o.destroy === "function";
 }

package/dist/engine/extensions/user-data.d.ts

@@ -2,15 +2,15 @@ import type { TenantDb } from "../../db/tenant-db.ts";
 import type { Registry, TenantId } from "../types/index.ts";
 type UserId = string;
 /**
- * Strategie für den Forget-Pfad pro Entity:
- *   - "delete":    Row physisch entfernen (Profil, Eigene Notizen, Sessions).
- *   - "anonymize": User-Reference auf null + Display-Felder auf
- *                  "[Geloescht]" — typisch für geteilte Daten (Tasks,
- *                  Comments) damit andere User die History nicht verlieren.
+ * Strategy for the forget path per entity:
+ *   - "delete":    Physically remove the row (profile, personal notes, sessions).
+ *   - "anonymize": Set the user reference to null and display fields to
+ *                  "[Geloescht]" — typical for shared data (tasks,
+ *                  comments) so other users do not lose the history.
  *
- * Cleanup-Job (Sprint 2 data-retention) entscheidet pro Entity über
- * Retention-Policy, welche Strategie greift. blockDelete-Entries lösen
- * IMMER `anonymize` aus damit Aufbewahrungs-Pflicht respektiert wird.
+ * The cleanup job applies the retention policy per entity to select the
+ * strategy. blockDelete entries ALWAYS use `anonymize` to respect retention
+ * obligations.
  */
 export type UserDataDeleteStrategy = "delete" | "anonymize";
 /**
@@ -27,7 +27,7 @@ export type UserDataDeleteStrategy = "delete" | "anonymize";
  */
 export type TenantUserModel = "single-user" | "multi-user";
 /**
- * fw#2914 — `db` is a tenant-filtered `TenantDb`, bound to `tenantId`
+ * `db` is a tenant-filtered `TenantDb`, bound to `tenantId`
  * (or the per-user sub-tx in the forget path). Unfiltered access needs
  * `escapeHatch: { reason }` on the `r.useExtension(...)` registration,
  * then `ctx.db.unsafeRaw()`.
@@ -82,15 +82,15 @@ export interface UserDataHookCtx {
     readonly userEmailBeforeDelete?: string | null;
 }
 /**
- * Pro Feature/Entity-Snippet das im Export-Bundle landet. Sprint 2
- * orchestriert die JSON-Serialisierung; Hooks geben Plain-Records.
+ * Feature/entity snippet included in the export bundle. The export job
+ * orchestrates JSON serialization; hooks return plain records.
  */
 export interface UserDataExportSnippet {
     readonly entity: string;
     readonly rows: ReadonlyArray<Record<string, unknown>>;
     /**
-     * Optional: signed-URLs für File-Refs. user-data-rights packt sie
-     * separat ins ZIP unter `files/`. Andere Hooks lassen das leer.
+     * Optional signed URLs for file references. user-data-rights puts them
+     * separately in the ZIP under `files/`. Other hooks leave this empty.
      */
     readonly fileRefs?: ReadonlyArray<{
         readonly fileRefId: string;
@@ -99,22 +99,21 @@ export interface UserDataExportSnippet {
     }>;
 }
 /**
- * Export-Hook: Sammelt alle Daten einer Entity die zu einem User
- * gehören. Wird im Daten-Export-Job pro registrierter Entity einmal
- * aufgerufen. Idempotent — kann mehrfach aufgerufen werden ohne
- * Side-Effects.
+ * Export hook: collects all data belonging to a user for an entity. It is
+ * called once per registered entity by the data export job. Idempotent — it
+ * can be called multiple times without side effects.
  *
- * Sprint 2 user-data-rights ruft das via Iteration über alle
- * `r.useExtension(EXT_USER_DATA, ...)`-Registrierungen.
+ * The data-rights runner invokes this by iterating over all
+ * `r.useExtension(EXT_USER_DATA, ...)` registrations.
  */
 export type UserDataExportHook = (ctx: UserDataHookCtx) => Promise<UserDataExportSnippet | null>;
 /**
- * Forget-Hook: Löscht oder anonymisiert die Entity-Rows die zu einem
- * User gehören. Strategy kommt vom Cleanup-Job (kann per Entity
- * unterschiedlich sein wegen Retention-Policy).
+ * Forget hook: deletes or anonymizes entity rows belonging to a user. The
+ * cleanup job supplies the strategy, which may differ by entity because of
+ * the retention policy.
  *
- * Idempotent — wenn der Job zweimal läuft (Crash-Recovery), darf der
- * Hook nicht crashen.
+ * Idempotent — if the job runs twice during crash recovery, the hook must not
+ * crash.
  *
  * Return additive to `void`: a hook can return `{status:"ok"}` or
  * `{status:"incomplete", reason}` to signal a partial success to the

package/dist/engine/factories.d.ts

@@ -7,13 +7,13 @@ export declare function createTextField<R extends true | false = false>(override
 };
 /**
  * Long-form text field for source-code, markdown, blog-posts, email-
- * templates — anything that can be megabytes large. Type-level differs
- * from `text`: keine sortable/searchable/filterable/format options.
- * DB-mapping ist identisch zu text (PG text ist unbounded).
+ * templates — anything that can be megabytes large. Its type-level API
+ * differs from `text`: it has no sortable/searchable/filterable/format options.
+ * The DB mapping is identical to text (`PG text` is unbounded).
  *
- * Soft-cap default: kein maxLength (PG text ist 1 GB hart begrenzt).
- * Setze einen explicit `maxLength` wenn du ein verirrtes Browser-Paste
- * früh ablehnen willst (z.B. 1_000_000 = 1 MB).
+ * Soft-cap default: no maxLength (`PG text` has a 1 GB hard limit).
+ * Set an explicit `maxLength` to reject an accidental browser paste early
+ * (for example, `1_000_000 = 1 MB`).
  */
 /**
  * Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`).
@@ -112,12 +112,12 @@ export declare function createDateField<R extends true | false = false>(override
     required: R;
 };
 /**
- * UTC-Instant — für Ereignisse die zu einem bestimmten Zeitpunkt passieren
- * (createdAt, loginAt, actualPickupAt). Temporal.Instant intern.
+ * UTC instant for events occurring at a specific point in time
+ * (createdAt, loginAt, actualPickupAt). Uses Temporal.Instant internally.
  *
- * Mit `locatedBy: "<name>Tz"` wird das Feld zum Wall-Clock-Pair eines
- * Termins an einem Ort — bevorzuge dafür `createLocatedTimestampField()`,
- * das EIN atomares Feld statt eines lose verdrahteten Pairs erzeugt.
+ * With `locatedBy: "<name>Tz"`, the field becomes a wall-clock pair for an
+ * appointment at a location — prefer `createLocatedTimestampField()` instead,
+ * which creates one atomic field rather than a loosely connected pair.
  */
 export declare function createTimestampField<R extends true | false = false>(overrides?: Partial<Omit<TimestampFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
     required?: R;
@@ -125,8 +125,9 @@ export declare function createTimestampField<R extends true | false = false>(ove
     required: R;
 };
 /**
- * IANA-Zonenname (z.B. "Europe/Berlin"). Wird im Boot/Schema-Validator
- * via `Intl.supportedValuesOf("timeZone")` geprüft (kommt im Zod-Schritt).
+ * IANA time-zone name (for example, "Europe/Berlin"). The boot/schema
+ * validator checks it using `Intl.supportedValuesOf("timeZone")` during the
+ * Zod step.
  */
 export declare function createTzField<R extends true | false = false>(overrides?: Partial<Omit<TzFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
     required?: R;

package/dist/engine/factories.js

@@ -24,7 +24,7 @@ function resolvePersonalFlags(personal, reason) {
         userOwned: { ownerField: personal.of, ...(whenAbsent !== undefined && { whenAbsent }) },
     };
 }
-// Resolves the author-facing `personal`/`find` annotations (kumiko-framework#2250)
+// Resolves the author-facing `personal`/`find` annotations
 // into the internal ResolvedPiiFlags every factory below merges into its
 // return value. `personal`, `find`, `reason` never survive into the field def.
 function expandPersonalAnnotations(overrides) {
@@ -73,7 +73,7 @@ function missingTextFieldStanceError(factoryName) {
 function isNonEmptyString(value) {
     return typeof value === "string" && value.trim().length > 0;
 }
-// Fail-closed stance gate (kumiko-framework#2921) for the two text-shaped
+// Fail-closed stance gate for the two text-shaped
 // factories — runs before expandPersonalAnnotations so an untyped JS caller
 // (no compiler to stop it) can't slip an unannotated text field past the
 // type layer either. The typed signature above already rejects a
@@ -109,13 +109,12 @@ function assertTextFieldStance(factoryName, overrides) {
         throw missingTextFieldStanceError(factoryName);
     }
 }
-// Generic über `R extends true | false` (statt `boolean`) damit
-// `createTextField({ required: true })` literal `required: true` im
-// Return-Type behält. `boolean` würde widenen — EntityTable<E>'s
-// Mapped-Type könnte dann nicht zwischen `required: true` und
-// `required: false` dispatchen, jede Column würde zu nullable
-// degradieren. Default `R = false` matcht den runtime-default. Pattern
-// in jeder required-bearing factory unten.
+// Use generic `R extends true | false` instead of `boolean` so
+// `createTextField({ required: true })` preserves the literal `required: true`
+// in the return type. Widening to `boolean` would prevent EntityTable<E>'s
+// Mapped-Type from distinguishing `required: true` from `required: false`,
+// making every column nullable. Default `R = false` matches the runtime
+// default. This pattern is used in every required-bearing factory below.
 export function createTextField(overrides) {
     assertTextFieldStance("createTextField", overrides);
     return {
@@ -129,13 +128,13 @@ export function createTextField(overrides) {
 }
 /**
  * Long-form text field for source-code, markdown, blog-posts, email-
- * templates — anything that can be megabytes large. Type-level differs
- * from `text`: keine sortable/searchable/filterable/format options.
- * DB-mapping ist identisch zu text (PG text ist unbounded).
+ * templates — anything that can be megabytes large. Its type-level API
+ * differs from `text`: it has no sortable/searchable/filterable/format options.
+ * The DB mapping is identical to text (`PG text` is unbounded).
  *
- * Soft-cap default: kein maxLength (PG text ist 1 GB hart begrenzt).
- * Setze einen explicit `maxLength` wenn du ein verirrtes Browser-Paste
- * früh ablehnen willst (z.B. 1_000_000 = 1 MB).
+ * Soft-cap default: no maxLength (`PG text` has a 1 GB hard limit).
+ * Set an explicit `maxLength` to reject an accidental browser paste early
+ * (for example, `1_000_000 = 1 MB`).
  */
 /**
  * Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`).
@@ -277,10 +276,10 @@ export function createEmbeddedListField(schema, overrides) {
         multiple: true,
     };
 }
-// Free-form jsonb-Spalte — siehe `JsonbFieldDef`-Doku. Schema-less, default
-// `{}`, NOT NULL. Hauptnutzer: custom-fields-Bundle (host-entity's
-// `customFields`-Spalte). Andere valid uses: tenant-config-blobs, AI-
-// inferred-metadata, future tags-arrays.
+// Free-form jsonb column — see the `JsonbFieldDef` documentation. Schema-less,
+// defaults to `{}`, and is NOT NULL. Primarily used by the custom-fields
+// bundle for the host entity's `customFields` column; other valid uses include
+// tenant configuration blobs, AI-inferred metadata, and future tag arrays.
 export function createJsonbField(overrides) {
     return {
         type: "jsonb",
@@ -295,17 +294,17 @@ export function createDateField(overrides) {
     }; // @cast-boundary engine-payload
 }
 /**
- * UTC-Instant — für Ereignisse die zu einem bestimmten Zeitpunkt passieren
- * (createdAt, loginAt, actualPickupAt). Temporal.Instant intern.
+ * UTC instant for events occurring at a specific point in time
+ * (createdAt, loginAt, actualPickupAt). Uses Temporal.Instant internally.
  *
- * Mit `locatedBy: "<name>Tz"` wird das Feld zum Wall-Clock-Pair eines
- * Termins an einem Ort — bevorzuge dafür `createLocatedTimestampField()`,
- * das EIN atomares Feld statt eines lose verdrahteten Pairs erzeugt.
+ * With `locatedBy: "<name>Tz"`, the field becomes a wall-clock pair for an
+ * appointment at a location — prefer `createLocatedTimestampField()` instead,
+ * which creates one atomic field rather than a loosely connected pair.
  */
 export function createTimestampField(overrides) {
-    // Object-Build vermeidet hartcodiertes `required: false` im literal —
-    // das würde TS dazu bringen, R auf `boolean` zu widenen statt das
-    // literal `true`/`false` aus dem overrides-Argument zu inferieren.
+    // Building the object this way avoids hardcoding `required: false` in the
+    // literal, which would make TypeScript widen R to `boolean` instead of
+    // inferring the `true`/`false` literal from the overrides argument.
     return {
         ...expandPersonalAnnotations(overrides),
         type: "timestamp",
@@ -313,8 +312,9 @@ export function createTimestampField(overrides) {
     };
 }
 /**
- * IANA-Zonenname (z.B. "Europe/Berlin"). Wird im Boot/Schema-Validator
- * via `Intl.supportedValuesOf("timeZone")` geprüft (kommt im Zod-Schritt).
+ * IANA time-zone name (for example, "Europe/Berlin"). The boot/schema
+ * validator checks it using `Intl.supportedValuesOf("timeZone")` during the
+ * Zod step.
  */
 export function createTzField(overrides) {
     return {
@@ -372,14 +372,15 @@ export function createFilesField(overrides) {
 export function createImagesField(overrides) {
     return { type: "images", ...expandPersonalAnnotations(overrides) };
 }
-// `F` läuft OHNE Constraint im Generic-Param damit TS die literal-types
-// einzelner Field-Defs durchzieht (required: true bleibt true, nicht
-// boolean). Constraint-Match gegen FieldsMap würde widenen — siehe TS-
-// Issue um Constraint-Inferenz auf strukturellen Records. Stattdessen
-// validieren wir die Conformance via conditional return type: wenn F
-// nicht FieldsMap-compat ist, kollabiert der Return zu `never`.
-// `const F`: inline field literals (`{ type: "reference", ... }`) keep their
-// `type` literal without `as const`; otherwise it widens to string → `never`.
+// Leave `F` unconstrained so TypeScript preserves the literal types of
+// individual field definitions (`required: true` remains `true`, not
+// `boolean`). Constraining it to FieldsMap would widen them — see the
+// TypeScript issue concerning constraint inference for structural records.
+// Instead, conformance is validated through the conditional return type: if F
+// is not compatible with FieldsMap, the return type collapses to `never`.
+// `const F` preserves the `type` literal in inline field literals
+// (`{ type: "reference", ... }`) without `as const`; otherwise it widens to
+// string and produces `never`.
 export function createEntity(def) {
     return {
         softDelete: false,

package/dist/engine/feature-ast/entity-field-types.js

@@ -1,7 +1,7 @@
 // Shared field-type validation for EntityDefinition. Used by both the
 // static extractor (extractEntity, parse-time ParseError) and the runtime
 // PatternChange validator (pattern-change-schema.ts) so the two never drift
-// into reporting different "unknown field type" catalogues (#3137).
+// into reporting different "unknown field type" catalogues.
 import { FIELD_TYPE_NAMES } from "@cosmicdrift/kumiko-types/fields";
 import { isPlainObject, isRawRefSentinel } from "./extractors/shared.js";
 /**

package/dist/engine/feature-ast/extractors/handlers.js

@@ -256,7 +256,7 @@ export function parseHandlerCall(call, sourceFile, methodName) {
     // (`r.writeHandler(eventCreateHandler)`, `r.queryHandler(someQuery())`)
     // that resolveObjectLiteralArg above couldn't turn into an object literal
     // (imported binding, factory call, ...). Keep it recognised as this kind
-    // instead of ParseErroring — see #1007. Opaque: renderWriteHandler/
+    // instead of ParseErroring. Opaque: renderWriteHandler/
     // renderQueryHandler re-emit `source.raw` verbatim when handlerName is
     // undefined.
     if (args.length === 1 && isRawRefSentinel(readDataLiteralNode(first))) {

package/dist/engine/feature-ast/extractors/hooks.js

@@ -230,7 +230,7 @@ export function extractHook(call, sourceFile) {
         ...escapeHatchOutcome,
     });
 }
-// guard:dup-ok — intentionale Parallele zu extractTree (round6); verschiedene Feature-AST-Extraktoren by design
+// guard:dup-ok — intentional parallel to extractTree; different Feature-AST extractors by design
 export function extractAuthClaims(call, sourceFile) {
     const arg = call.getArguments()[0];
     if (!arg) {

package/dist/engine/feature-ast/extractors/shared.d.ts

@@ -47,8 +47,7 @@ export declare function readStringOrRaw(node: Node): string | RawRefSentinel | u
  * Like readStringLiteralArgs, but an argument that resolves to a raw-ref
  * sentinel is kept as that sentinel instead of failing the whole call. Used
  * where a value stands in for a single name/key and inlining its resolved
- * string would corrupt the render roundtrip (e.g. `r.requires(someFeature.name)`
- * — see #1009).
+ * string would corrupt the render roundtrip (e.g. `r.requires(someFeature.name)`).
  */
 export declare function readStringOrRawArgs(call: CallExpression): readonly (string | RawRefSentinel)[] | undefined;
 export { isPlainObject } from "../../../utils/is-plain-object.ts";
@@ -67,7 +66,7 @@ export type NameLiteralRef = {
 };
 /**
  * Like `readNameLiteral`, but for callers that must preserve an
- * identifier-authored name across a render → parse round-trip (see #2111).
+ * identifier-authored name across a render → parse round-trip.
  * `raw` is populated only when the node resolved via an identifier — a
  * string-literal node has nothing worth preserving beyond its value, and
  * setting `raw` for it too would make `JSON.stringify(value)` and

package/dist/engine/feature-ast/extractors/shared.js

@@ -147,8 +147,7 @@ export function readStringOrRaw(node) {
  * Like readStringLiteralArgs, but an argument that resolves to a raw-ref
  * sentinel is kept as that sentinel instead of failing the whole call. Used
  * where a value stands in for a single name/key and inlining its resolved
- * string would corrupt the render roundtrip (e.g. `r.requires(someFeature.name)`
- * — see #1009).
+ * string would corrupt the render roundtrip (e.g. `r.requires(someFeature.name)`).
  */
 export function readStringOrRawArgs(call) {
     const out = [];
@@ -229,7 +228,7 @@ function resolveIdentifierToStringLiteral(identifier) {
 }
 /**
  * Like `readNameLiteral`, but for callers that must preserve an
- * identifier-authored name across a render → parse round-trip (see #2111).
+ * identifier-authored name across a render → parse round-trip.
  * `raw` is populated only when the node resolved via an identifier — a
  * string-literal node has nothing worth preserving beyond its value, and
  * setting `raw` for it too would make `JSON.stringify(value)` and