@cosmicdrift/kumiko-types 0.327.0 → 0.328.0

package/dist/handlers.js

@@ -0,0 +1,49 @@
+// AccessRule can arrive from untyped sources (pattern-library JSON, Designer)
+// where `openToAll` doesn't actually match the declared union — narrow via
+// `unknown` instead of trusting the static type, deny on anything malformed.
+export function isOpenToAllGranted(rule) {
+    if (!("openToAll" in rule))
+        return false;
+    const openToAll = rule.openToAll;
+    if (typeof openToAll !== "object" || openToAll === null)
+        return false;
+    if (!("reason" in openToAll) || typeof openToAll.reason !== "string")
+        return false;
+    return openToAll.reason.trim().length > 0;
+}
+// UI-visibility predicate — DEFAULT-VISIBLE, the opposite stance from
+// `hasAccess`/AccessRule's own default-deny doc above: an unset `access`
+// means every signed-in user may see the screen/nav/workspace, not nobody.
+// The engine's dispatcher access check stays default-deny; this only
+// decides what a client renders/lists, never what a handler accepts.
+// Same `unknown`-narrowing caution as isOpenToAllGranted — `access` can
+// arrive from untyped sources.
+export function isUiAccessGranted(access, userRoles) {
+    if (access === undefined)
+        return true;
+    if ("openToAll" in access)
+        return isOpenToAllGranted(access);
+    if (userRoles === undefined)
+        return false;
+    if (!("roles" in access))
+        return false;
+    return access.roles.some((role) => userRoles.includes(role));
+}
+export function normalizeEventPiiSubject(spec) {
+    if ("subjectField" in spec) {
+        return { kind: "user", ownerField: spec.subjectField, whenAbsent: undefined };
+    }
+    if (spec.personal === "tenant")
+        return { kind: "tenant" };
+    if (spec.personal === "self")
+        return { kind: "self" };
+    return { kind: "user", ownerField: spec.personal.of, whenAbsent: spec.personal.whenAbsent };
+}
+export function isRateLimitDisabled(v) {
+    return v !== undefined && "disabled" in v && v.disabled === true;
+}
+// Marker set by defineEntityQueryHandler on both of its verbs. A string, not
+// a Symbol(), for the same reason as PAGED_QUERY_HANDLER_BRAND: a symlinked
+// workspace can evaluate a module twice, and two Symbol() calls would not
+// compare equal across those instances.
+export const ENTITY_CONVENTION_QUERY_BRAND = "__kumikoEntityConventionQuery";

package/dist/hook-phase.d.ts

@@ -0,0 +1 @@
+export type HookPhase = "inTransaction" | "afterCommit";

package/dist/hook-phase.js

@@ -0,0 +1 @@
+export {};

package/dist/hooks.d.ts

@@ -0,0 +1,75 @@
+import type { StoredEvent } from "./event-store-types.js";
+import type { AppContext } from "./handlers.js";
+import type { HookPhase } from "./hook-phase.js";
+import type { EntityId } from "./identifiers.js";
+export type ValidationError = {
+    readonly field: string;
+    readonly error: string;
+};
+export type ValidationHookFn = (data: Readonly<Record<string, unknown>>) => readonly ValidationError[] | null;
+export type SaveContext = {
+    readonly kind: "save";
+    readonly id: EntityId;
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly changes: Readonly<Record<string, unknown>>;
+    readonly previous: Readonly<Record<string, unknown>>;
+    readonly isNew: boolean;
+    readonly entityName?: string | undefined;
+    readonly event?: StoredEvent | undefined;
+};
+export type DeleteContext = {
+    readonly kind: "delete";
+    readonly id: EntityId;
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly entityName?: string | undefined;
+    readonly event?: StoredEvent | undefined;
+};
+export type LifecycleResult = SaveContext | DeleteContext;
+export type PreSaveHookFn = (changes: Record<string, unknown>, context: AppContext & {
+    readonly previous: Readonly<Record<string, unknown>>;
+    readonly isNew: boolean;
+}) => Promise<Record<string, unknown>>;
+export type PostSaveHookFn = (result: SaveContext, context: AppContext) => Promise<void>;
+export type PostSaveBatchHookFn = (results: readonly SaveContext[], context: AppContext) => Promise<void>;
+export type PreDeleteHookFn = (payload: DeleteContext, context: AppContext) => Promise<void>;
+export type PostDeleteHookFn = (payload: DeleteContext, context: AppContext) => Promise<void>;
+export type PostDeleteBatchHookFn = (payloads: readonly DeleteContext[], context: AppContext) => Promise<void>;
+export type PreQueryHookFn = (payload: Record<string, unknown>, context: AppContext) => Promise<Record<string, unknown>>;
+export type PostQueryHookFn = (result: {
+    readonly entityName: string | undefined;
+    readonly rows: ReadonlyArray<Record<string, unknown>>;
+}, context: AppContext) => Promise<{
+    rows: ReadonlyArray<Record<string, unknown>>;
+}>;
+export type LifecycleHookFn = PreSaveHookFn | PostSaveHookFn | PreDeleteHookFn | PostDeleteHookFn | PreQueryHookFn | PostQueryHookFn;
+export type { HookPhase } from "./hook-phase.js";
+export type HookOwner = {
+    readonly featureName?: string;
+};
+export type PhasedHook<TFn> = {
+    readonly fn: TFn;
+    readonly phase: HookPhase;
+} & HookOwner;
+export type OwnedFn<TFn> = {
+    readonly fn: TFn;
+} & HookOwner;
+export type HookMap = {
+    readonly validation?: Readonly<Record<string, ValidationHookFn>>;
+    readonly preSave?: Readonly<Record<string, readonly OwnedFn<PreSaveHookFn>[]>>;
+    readonly postSave?: Readonly<Record<string, readonly PhasedHook<PostSaveHookFn>[]>>;
+    readonly preDelete?: Readonly<Record<string, readonly PhasedHook<PreDeleteHookFn>[]>>;
+    readonly postDelete?: Readonly<Record<string, readonly PhasedHook<PostDeleteHookFn>[]>>;
+    readonly preQuery?: Readonly<Record<string, readonly OwnedFn<PreQueryHookFn>[]>>;
+    readonly postQuery?: Readonly<Record<string, readonly OwnedFn<PostQueryHookFn>[]>>;
+};
+export type EntityHookMap = {
+    readonly postSave?: Readonly<Record<string, readonly PhasedHook<PostSaveHookFn>[]>>;
+    readonly preDelete?: Readonly<Record<string, readonly PhasedHook<PreDeleteHookFn>[]>>;
+    readonly postDelete?: Readonly<Record<string, readonly PhasedHook<PostDeleteHookFn>[]>>;
+    readonly postQuery?: Readonly<Record<string, readonly OwnedFn<PostQueryHookFn>[]>>;
+};
+export type SearchPayloadContributorFn = (args: {
+    readonly entityName: string;
+    readonly entityId: EntityId;
+    readonly state: Record<string, unknown>;
+}) => Record<string, unknown> | Promise<Record<string, unknown>>;

package/dist/hooks.js

@@ -0,0 +1 @@
+export {};

package/dist/http-route.d.ts

@@ -0,0 +1,52 @@
+import type { Context } from "hono";
+/** Subset von HTTP-Methoden den wir aktiv unterstützen. Hono spricht
+ *  alle, aber das hier sind die einzigen die ein Feature-Author
+ *  realistisch deklariert. */
+export type HttpRouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+/** Dependencies die der Handler vom Framework bekommt. App-Author kann
+ *  die App selbst aufrufen (`deps.app.fetch(...)` für intern-call) oder
+ *  direkt per dispatcher Daten ziehen. Db/Redis sind die rohen Connections
+ *  — wer Tenant-Scope braucht muss durch dispatcher.query gehen.
+ *
+ *  Hono-typing: `Context<any, any>` weil das Hono-Type-Param-Setup nur
+ *  intern relevant ist. Concrete Hono-app wird im Boot-Path zugewiesen. */
+export type HttpRouteHandlerDeps = {
+    /** Die Hono-app — Handler kann via app.fetch(...) interne Routes
+     *  ansprechen (z.B. /api/query mit der vollen Auth-/Anonymous-Chain). */
+    readonly app: import("hono").Hono<any, any>;
+    /** Run a query handler in-process, forcing a SPECIFIC tenant — WITHOUT
+     *  going through the public /api/query HTTP layer (no header parsing, no
+     *  anonymousAccess tenant resolution). The synthesized caller carries
+     *  anonymous-level access ONLY (same role a real anonymous request would
+     *  have, no more) — the primitive forces the tenant, not the privilege
+     *  level, so it stays safe to call from any `anonymous: true` route
+     *  without risking a field-level disclosure a real anonymous caller
+     *  couldn't already get. Use this whenever the route needs a tenant
+     *  other than the one the request resolves to (e.g. always
+     *  SYSTEM_TENANT_ID regardless of the visited host) — spoofing that via
+     *  an internal X-Tenant header on `app.fetch(...)` is indistinguishable
+     *  from an external client and gets rejected by resolverTrust:
+     *  "authoritative" anonymousAccess configs (see auth-middleware.ts). */
+    readonly systemQuery: (type: string, payload: unknown, tenantId: import("./identifiers.js").TenantId) => Promise<unknown>;
+    /** Caller IP resolved via the server's configured, trustedProxyHops-aware
+     *  resolver (same one requestIdMiddleware uses for `/api/*`) — a route
+     *  handler needing the caller's IP (rate limiting, audit) should read
+     *  this instead of parsing X-Forwarded-For itself, which trusts
+     *  whichever hop count the deployment actually has in front of it. */
+    readonly clientIp: string;
+};
+export type HttpRouteHandler = (c: Context<any, any>, deps: HttpRouteHandlerDeps) => Response | Promise<Response>;
+export type HttpRouteDefinition = {
+    /** HTTP-Methode — bei Hono-Mount via app.{get,post,...}(path). */
+    readonly method: HttpRouteMethod;
+    /** URL-Pfad (Hono-Pattern, z.B. "/feed.xml" oder "/og/:tenantId.png"). */
+    readonly path: string;
+    /** true = public, no session required. false = mounted behind the
+     *  session auth chain (no anonymous fallthrough, PAT rate limit,
+     *  origin + CSRF guards) — a request without a session gets 401. The
+     *  handler reads the caller via getUser(c). */
+    readonly anonymous: boolean;
+    /** Hono-Handler. Bekommt Hono-Context + Framework-Deps; returnt
+     *  Response (sync oder async). */
+    readonly handler: HttpRouteHandler;
+};

package/dist/http-route.js

@@ -0,0 +1,13 @@
+// HTTP route definition — feature-declared HTTP endpoints outside
+// the /api/write|query|batch pipeline. Use case: RSS/Atom feeds, OpenAPI
+// specs, OG image generators, webhook receivers — anything where the
+// feature author controls the wire format themselves.
+//
+// Pattern symmetric to r.queryHandler / r.writeHandler: definition as
+// part of the feature (not the app bootstrapping). Phase-3 multi-tenant
+// becomes trivial because tenant context is picked up via host resolution.
+//
+// Escape-hatch stays: runProdApp.extraRoutes (declarative list with
+// `entry` tier) for hand-rolled routes that have nothing to do with a
+// feature (e.g. platform-specific static-serving logic).
+export {};

package/dist/identifiers.d.ts

@@ -0,0 +1,8 @@
+export type TenantId = string;
+export declare const UUID_SHAPE_PATTERN = "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$";
+export declare function isUuid(value: unknown): value is string;
+export declare function parseTenantId(value: unknown): TenantId | null;
+export declare const SYSTEM_TENANT_ID: TenantId;
+export declare function isSystemTenant(tenantId: TenantId | null | undefined): boolean;
+export declare const SYSTEM_USER_ID = "00000000-0000-0000-0000-000000000000";
+export type EntityId = number | string;

package/{src/identifiers.ts → dist/identifiers.js}

@@ -2,11 +2,6 @@
 // travels through the framework. One declaration per concept so future
 // representation changes (branded types, UUID validation, opaque wrappers)
 // land in a single place.
-
-// Tenant identifier — UUID string today. May become branded/opaque later
-// without touching call sites.
-export type TenantId = string;
-
 // Lowercase UUID (any RFC-4122 variant). Strict enough to keep client-
 // supplied junk (e.g. SQL fragments, path-traversal probes) out of the
 // pipeline; loose enough that v4 / v7 / nil all match. Any caller that
@@ -18,46 +13,34 @@ export type TenantId = string;
 // exact same shape instead of growing a second copy that drifts.
 export const UUID_SHAPE_PATTERN = "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$";
 const TENANT_ID_REGEX = new RegExp(UUID_SHAPE_PATTERN);
-
 // Shared shape check for any UUID-formatted identifier crossing an
 // untrusted boundary (fileRefId, entity ids, ...) — same loose,
 // version-agnostic regex as TENANT_ID_REGEX (v4/v7/nil all match), kept as
 // one predicate so call sites don't grow their own copy of the shape.
-export function isUuid(value: unknown): value is string {
-  return typeof value === "string" && TENANT_ID_REGEX.test(value);
+export function isUuid(value) {
+    return typeof value === "string" && TENANT_ID_REGEX.test(value);
 }
-
 // Validates a candidate string against the tenantId format and returns it
 // as a TenantId, or `null` when it doesn't match. Use at every system
 // boundary that admits untrusted input (HTTP headers, cookies, query
 // params). Returning null instead of throwing keeps the caller in charge
 // of the rejection shape — middleware returns 400, batch jobs may filter
 // + log, and unit tests don't need a try/catch.
-export function parseTenantId(value: unknown): TenantId | null {
-  return isUuid(value) ? value : null;
+export function parseTenantId(value) {
+    return isUuid(value) ? value : null;
 }
-
 // "System-scope" tenant marker: handlers carry this tenantId when the event
 // doesn't belong to any particular tenant (reference data, cross-tenant
 // jobs, global config). The concrete UUID is a valid v4 (not all-zeroes —
 // Postgres' UUID type rejects invalid variants), chosen to be easy to
 // eyeball in logs. Central constant so call sites don't re-type the string
 // and the isSystemTenant() check stays in sync.
-export const SYSTEM_TENANT_ID: TenantId = "00000000-0000-4000-8000-000000000000";
-
-export function isSystemTenant(tenantId: TenantId | null | undefined): boolean {
-  return !tenantId || tenantId === SYSTEM_TENANT_ID;
+export const SYSTEM_TENANT_ID = "00000000-0000-4000-8000-000000000000";
+export function isSystemTenant(tenantId) {
+    return !tenantId || tenantId === SYSTEM_TENANT_ID;
 }
-
 // "No human caller" marker on event-store `createdBy`. Stringified so it
 // round-trips through SessionUser.id; not a real UUID, and createdBy is text.
 // Lives here rather than next to createSystemUser() so client-side code (the
 // reference-label map) can read it without importing a runtime module.
 export const SYSTEM_USER_ID = "00000000-0000-0000-0000-000000000000";
-
-// Primary-key identifier for any entity row. Two shapes coexist because of
-// the entity-def `idType` switch: classic CRUD entities keep `serial` (number),
-// while tenant + ES aggregates run on `uuid` (string). Call sites that pass
-// the id through to the DB layer stay agnostic; only code that formats ids
-// for URLs, logs, or cache keys needs `String(id)` — JS coerces both safely.
-export type EntityId = number | string;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1 @@
+export {};

package/dist/kms-adapter-types.d.ts

@@ -0,0 +1,68 @@
+import type { TenantId } from "./identifiers.js";
+export type SubjectId = {
+    readonly kind: "user";
+    readonly userId: string;
+} | {
+    readonly kind: "tenant";
+    readonly tenantId: TenantId;
+} | {
+    readonly kind: "record";
+    readonly entity: string;
+    readonly id: string;
+};
+export type SubjectKey = string;
+export declare function subjectKeyForUser(userId: string): SubjectKey;
+export declare function subjectKeyForTenant(tenantId: TenantId): SubjectKey;
+export declare const RECORD_ENTITY_PATTERN: RegExp;
+export declare function subjectKeyForRecord(entity: string, id: string): SubjectKey;
+export declare function subjectIdToKey(subject: SubjectId): SubjectKey;
+export declare function subjectIdFromKey(key: SubjectKey): SubjectId;
+export interface KmsContext {
+    readonly tenantId?: TenantId;
+    readonly requestId: string;
+    readonly userId?: string;
+    readonly eraseReason?: string;
+}
+export interface KmsHealth {
+    readonly ok: boolean;
+    readonly latencyMs: number;
+    readonly details?: Record<string, unknown>;
+}
+export type SubjectDek = Buffer;
+interface KmsAdapterBase {
+    /**
+     * Creates a fresh subject key. Throws KeyAlreadyExistsError when the
+     * subject already has one — including an erased tombstone: a shredded
+     * subject must never get a new key, or forget could be undone by
+     * re-encrypting under it.
+     */
+    createKey(subject: SubjectId, ctx: KmsContext): Promise<void>;
+    /**
+     * Erases the key material immediately; the tombstone row stays for the
+     * audit trail. Idempotent — repeat calls and unknown subjects are no-ops.
+     */
+    eraseKey(subject: SubjectId, ctx: KmsContext): Promise<void>;
+    /** Probe for boot + readiness. Throws when the backend is unreachable. */
+    health(): Promise<KmsHealth>;
+}
+export interface LocalKeyKmsAdapter extends KmsAdapterBase {
+    readonly capabilities: {
+        readonly mode: "local-key";
+    };
+    /**
+     * Throws KeyErasedError after eraseKey (callers render "[[erased]]"),
+     * KeyNotFoundError when the subject never had a key (typically a bug).
+     */
+    getKey(subject: SubjectId, ctx: KmsContext): Promise<SubjectDek>;
+}
+export interface RemoteCryptoKmsAdapter extends KmsAdapterBase {
+    readonly capabilities: {
+        readonly mode: "remote-crypto";
+    };
+    encrypt(subject: SubjectId, plaintext: Uint8Array, ctx: KmsContext): Promise<Uint8Array>;
+    /** Same error contract as LocalKeyKmsAdapter.getKey. */
+    decrypt(subject: SubjectId, ciphertext: Uint8Array, ctx: KmsContext): Promise<Uint8Array>;
+}
+export type KmsAdapter = LocalKeyKmsAdapter | RemoteCryptoKmsAdapter;
+export declare function isLocalKeyKmsAdapter(adapter: KmsAdapter): adapter is LocalKeyKmsAdapter;
+export {};

package/dist/kms-adapter-types.js

@@ -0,0 +1,49 @@
+export function subjectKeyForUser(userId) {
+    return `user:${userId}`;
+}
+export function subjectKeyForTenant(tenantId) {
+    return `tenant:${tenantId}`;
+}
+// Registry entity names are identifier-shaped; a free-form aggregate_type
+// (events-schema.ts is a plain text column) could otherwise mint a record
+// key that subjectIdSchema (forget-subject.write.ts) later refuses to
+// shred — enforced once here so minting and shredding can never disagree.
+export const RECORD_ENTITY_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
+export function subjectKeyForRecord(entity, id) {
+    if (!RECORD_ENTITY_PATTERN.test(entity)) {
+        throw new Error(`Invalid record entity for subject key: "${entity}" — must match ${RECORD_ENTITY_PATTERN}`);
+    }
+    if (id === "")
+        throw new Error("Invalid record id for subject key: empty");
+    return `record:${entity}:${id}`;
+}
+export function subjectIdToKey(subject) {
+    switch (subject.kind) {
+        case "user":
+            return subjectKeyForUser(subject.userId);
+        case "tenant":
+            return subjectKeyForTenant(subject.tenantId);
+        case "record":
+            return subjectKeyForRecord(subject.entity, subject.id);
+    }
+}
+export function subjectIdFromKey(key) {
+    if (key.startsWith("user:"))
+        return { kind: "user", userId: key.slice("user:".length) };
+    if (key.startsWith("tenant:")) {
+        return { kind: "tenant", tenantId: key.slice("tenant:".length) }; // @cast-boundary parse of a key this module minted
+    }
+    if (key.startsWith("record:")) {
+        const rest = key.slice("record:".length);
+        const separatorIndex = rest.indexOf(":");
+        const entity = separatorIndex === -1 ? "" : rest.slice(0, separatorIndex);
+        const id = separatorIndex === -1 ? "" : rest.slice(separatorIndex + 1);
+        if (entity === "" || id === "")
+            throw new Error(`Invalid subject key: ${key}`);
+        return { kind: "record", entity, id };
+    }
+    throw new Error(`Invalid subject key: ${key}`);
+}
+export function isLocalKeyKmsAdapter(adapter) {
+    return adapter.capabilities.mode === "local-key";
+}

package/dist/logger.d.ts

@@ -0,0 +1,7 @@
+export type Logger = {
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+    debug(msg: string, data?: Record<string, unknown>): void;
+    child(context: Record<string, unknown>): Logger;
+};

package/dist/logger.js

@@ -0,0 +1 @@
+export {};

package/dist/multi-stream-apply-context-types.d.ts

@@ -0,0 +1,18 @@
+import type { DerivativesContext } from "./derivatives-types.js";
+import type { StoredEvent } from "./event-store-types.js";
+import type { KumikoEventTypeMap } from "./event-type-map.js";
+import type { Registry } from "./feature.js";
+import type { FileContext } from "./file-handle-types.js";
+import type { AppendEventFn, UnsafeAppendEventFn } from "./handlers.js";
+import type { SecretsContext } from "./secrets-types.js";
+export type MultiStreamApplyContext<TMap extends object = KumikoEventTypeMap> = {
+    readonly appendEvent: AppendEventFn<TMap>;
+    readonly unsafeAppendEvent: UnsafeAppendEventFn;
+    readonly loadAggregate: (aggregateId: string, options?: {
+        readonly asOf?: Temporal.Instant;
+    }) => Promise<readonly StoredEvent[]>;
+    readonly registry: Registry;
+    readonly files?: FileContext;
+    readonly derivatives?: DerivativesContext;
+    readonly secrets?: SecretsContext;
+};

package/dist/multi-stream-apply-context-types.js

@@ -0,0 +1 @@
+export {};

package/dist/nav-icon.d.ts

@@ -0,0 +1,3 @@
+export declare const NAV_ICON_KEYS: readonly ["dashboard", "layout-grid", "book-open", "clipboard-list", "package", "gauge", "list", "table", "layers", "building", "calculator", "wallet", "coins", "credit-card", "piggy-bank", "receipt", "chart", "bar-chart", "trending", "sparkles", "wand", "calendar", "file", "folder", "folder-open", "home", "bell", "shield", "shield-check", "send", "settings", "users", "user", "search", "tag", "key", "link", "palette", "share", "server", "mail", "lock", "hash", "download", "upload", "rocket", "plus", "languages", "trash", "x", "check", "arrow-left", "arrow-right", "copy", "pencil", "eye", "eye-off", "filter", "refresh", "more-horizontal", "more-vertical", "external-link", "chevron-down", "chevron-left", "chevron-right", "save", "undo", "archive", "star", "flag", "clock", "map-pin", "phone", "printer", "alert-triangle", "info", "check-circle", "x-circle", "loader", "mic", "circle-stop", "image"];
+export type NavIconKey = (typeof NAV_ICON_KEYS)[number];
+export type IconKey = NavIconKey;

package/dist/nav-icon.js

@@ -0,0 +1,100 @@
+// Closed vocabulary of nav and button icon keys. NavDefinition.icon,
+// ScreenNavSugar.icon, ConfigMask.icon and ButtonProps.icon/iconEnd are all
+// typed against this union, so an unregistered key is a compile error at the
+// r.nav()/r.screen()/config-mask/button call site instead of a silent
+// missing-icon at runtime.
+//
+// The renderer-web NAV_ICONS map (packages/renderer-web/src/icons.tsx) is
+// checked against this same union via `satisfies`, so the two can't drift —
+// add a key here only together with its lucide-react entry there, and vice
+// versa.
+//
+// Declared as a runtime tuple (not just a type) so callers that sit outside
+// this repo's `tsc --build` project graph (e.g. samples, external consumers
+// resolving from a stale published type) still get a runtime-checkable
+// vocabulary — the boot-validator's validateActionHasIcon checks a declared
+// icon against NAV_ICON_KEYS instead of trusting "not undefined".
+export const NAV_ICON_KEYS = [
+    "dashboard",
+    "layout-grid",
+    "book-open",
+    "clipboard-list",
+    "package",
+    "gauge",
+    "list",
+    "table",
+    "layers",
+    "building",
+    "calculator",
+    "wallet",
+    "coins",
+    "credit-card",
+    "piggy-bank",
+    "receipt",
+    "chart",
+    "bar-chart",
+    "trending",
+    "sparkles",
+    "wand",
+    "calendar",
+    "file",
+    "folder",
+    "folder-open",
+    "home",
+    "bell",
+    "shield",
+    "shield-check",
+    "send",
+    "settings",
+    "users",
+    "user",
+    "search",
+    "tag",
+    "key",
+    "link",
+    "palette",
+    "share",
+    "server",
+    "mail",
+    "lock",
+    "hash",
+    "download",
+    "upload",
+    "rocket",
+    "plus",
+    "languages",
+    "trash",
+    "x",
+    "check",
+    "arrow-left",
+    "arrow-right",
+    "copy",
+    "pencil",
+    "eye",
+    "eye-off",
+    "filter",
+    "refresh",
+    "more-horizontal",
+    "more-vertical",
+    "external-link",
+    "chevron-down",
+    "chevron-left",
+    "chevron-right",
+    "save",
+    "undo",
+    "archive",
+    "star",
+    "flag",
+    "clock",
+    "map-pin",
+    "phone",
+    "printer",
+    "alert-triangle",
+    "info",
+    "check-circle",
+    "x-circle",
+    "loader",
+    "mic",
+    "circle-stop",
+    "image",
+];

package/dist/nav.d.ts

@@ -0,0 +1,39 @@
+import type { AccessRule } from "./handlers.js";
+import type { NavIconKey } from "./nav-icon.js";
+import type { TargetRef } from "./target-ref.js";
+import type { TreeAction } from "./tree-node.js";
+export type { IconKey, NavIconKey } from "./nav-icon.js";
+export type NavDefinition = {
+    readonly id: string;
+    readonly label: string;
+    readonly icon?: NavIconKey;
+    readonly parent?: string;
+    readonly order?: number;
+    readonly screen?: string;
+    readonly target?: TargetRef;
+    readonly actions?: readonly TreeAction[];
+    readonly createAction?: TreeAction;
+    readonly provider?: boolean;
+    readonly access?: AccessRule;
+    readonly workspaces?: readonly string[];
+};
+/** Client editor format for r.contentCollection() — not template body storage formats. */
+export type ContentEditorFormat = "plain" | "rich" | "markdown";
+export type ContentCollectionDefinition = {
+    readonly id: string;
+    readonly kind: string;
+    readonly access?: AccessRule;
+    readonly ownership?: "tenant" | "user";
+    readonly contentFormat?: ContentEditorFormat;
+    readonly variableSchema?: Readonly<Record<string, string>>;
+    readonly nav: {
+        readonly label: string;
+        readonly icon?: NavIconKey;
+        readonly parent?: string;
+        readonly order?: number;
+        readonly access?: AccessRule;
+        readonly workspaces?: readonly string[];
+        readonly createAction?: TreeAction;
+        readonly actions?: readonly TreeAction[];
+    };
+};

package/dist/nav.js

@@ -0,0 +1 @@
+export {};

package/dist/observability/index.d.ts

@@ -0,0 +1,3 @@
+export type { Counter, Gauge, Histogram, Meter, MetricDefinition, MetricLabels, MetricsHandle, MetricType, } from "./metric.js";
+export type { ObservabilityOptions, ObservabilityProvider, SamplingConfig, SensitiveFilterConfig, } from "./provider.js";
+export type { SerializedTraceContext, Span, SpanAttributes, SpanAttributeValue, SpanKind, SpanStatus, StartSpanOptions, Tracer, } from "./span.js";

package/dist/observability/index.js

@@ -0,0 +1,2 @@
+// Barrel for observability types. Split into span/metric/provider so each module stays focused.
+export {};

package/dist/observability/metric.d.ts

@@ -0,0 +1,34 @@
+export type MetricLabels = Record<string, string | number | boolean>;
+export type MetricType = "counter" | "histogram" | "gauge";
+export type MetricDefinition = {
+    readonly name: string;
+    readonly type: MetricType;
+    readonly description?: string;
+    readonly labels?: readonly string[];
+    readonly buckets?: readonly number[];
+    readonly unit?: string;
+    readonly tenantLabel?: boolean;
+};
+export interface Counter {
+    inc(value?: number, labels?: MetricLabels): void;
+}
+export interface Histogram {
+    observe(value: number, labels?: MetricLabels): void;
+}
+export interface Gauge {
+    set(value: number, labels?: MetricLabels): void;
+    inc(value?: number, labels?: MetricLabels): void;
+    dec(value?: number, labels?: MetricLabels): void;
+}
+export interface Meter {
+    registerMetric(def: MetricDefinition): void;
+    counter(name: string): Counter;
+    histogram(name: string): Histogram;
+    gauge(name: string): Gauge;
+    definitions(): ReadonlyMap<string, MetricDefinition>;
+}
+export interface MetricsHandle {
+    inc(name: string, labels?: MetricLabels, value?: number): void;
+    observe(name: string, value: number, labels?: MetricLabels): void;
+    set(name: string, value: number, labels?: MetricLabels): void;
+}

package/dist/observability/metric.js

@@ -0,0 +1,3 @@
+// Metric + Meter contract. Feature code interacts through ctx.metrics
+// (MetricsHandle); the framework wires Counter/Histogram/Gauge behind that.
+export {};