@jini-ai/admin 0.3.0 → 0.3.6

package/dist/core/ports/entities.d.ts

@@ -0,0 +1,302 @@
+/**
+ * @file `AdminEntityPort` — the one port that is generic over the entity it fronts.
+ *
+ * ## Why this port is shaped differently from every other one here
+ *
+ * Every other port in this directory names a fixed capability with a fixed row shape:
+ * `AdminMembersPort` returns `AdminMember`, `AdminSeoPort` returns `AdminSeoMeta`. That works
+ * because the capability is the same everywhere it is wired — a member is a member.
+ *
+ * An application's own entities are not like that. A recipe app has recipes and authors; a
+ * warehouse app has pallets and SKUs. There is no fixed row shape to write down, and force-fitting
+ * one onto an existing port is lossy in a way that shows up immediately: mapping an app's `Author`
+ * onto `AdminMember` has to invent a `status`, and drops every field (`bio`) the app actually has.
+ *
+ * So this port carries its own schema. An adapter declares an {@link AdminEntityDescriptor}, and
+ * the row type is *derived* from it ({@link AdminEntityRow}) rather than declared twice. A host
+ * screen reads the descriptor to decide what to render, which is what makes one screen able to
+ * render any entity with no per-entity code.
+ *
+ * ## What this port deliberately does NOT carry
+ *
+ * - **No `workspaceId`, and no other host-specific field.** If a field cannot be produced by an app
+ *   with no database, it does not belong on a generic row. Multi-tenancy is the adapter's business,
+ *   held in its own closure, invisible here. This is the single rule that keeps an adapter for a
+ *   plain in-memory array as short as an adapter for a real backend.
+ * - **No response envelope.** `list` returns {@link AdminEntityPage}, `get` returns the row itself
+ *   — never `{ entity }` or `{ items }`-plus-metadata. {@link AdminEntityPage} is not a
+ *   counterexample: `nextCursor` is pagination state that has nowhere else to live, not a wrapper
+ *   around the payload.
+ * - **No `expectedVersion` on `update`.** Every other write in this package carries one. It is
+ *   omitted here because an in-memory store has no version column, and requiring one would make the
+ *   smallest honest adapter impossible to write. An entity that wants optimistic concurrency
+ *   declares a `version` field of kind `"integer"` and enforces it inside its own `update`. This is
+ *   a real weakening relative to the other ports, stated rather than hidden, and worth revisiting
+ *   the first time a genuinely multi-writer entity appears.
+ * - **No publication lifecycle.** `AdminEntry`-style `draft`/`published` belongs to a CMS entry, not
+ *   to an arbitrary entity. An app that wants one declares a `status` field of kind `"text"`.
+ * - **No per-operation authorization seam** (no `canCreate`/`canDelete`). Consistent with every
+ *   other port here, and with `AdminPanel.permissions` being affordance-only — but worth naming,
+ *   because a generic CRUD surface over arbitrary application data is where that gap starts to
+ *   matter more than it does on a fixed screen.
+ *
+ * Types only, like every file in this directory. The runtime half — registration, descriptor
+ * validation, and the erasure a generic screen consumes — lives in `../entities/rules.ts`.
+ */
+/**
+ * The closed set of field kinds an entity may declare.
+ *
+ * **Closed deliberately**, unlike the reference-implementation-derived unions elsewhere in this
+ * directory (see `README.md`'s `T | (string & {})` idiom). A kind is not a label: each member here
+ * is a promise that a rendering layer knows how to display and edit it, and that a persistence
+ * layer knows its storage class. A host cannot add a seventh kind by widening a string — it would
+ * render as nothing. Adding a kind is a change to this package.
+ *
+ * `"media"` and `"enum"` are deliberately absent. `"media"` is the same shape as `"relation"` at
+ * rest (a foreign id stored as text) and differs only in needing a media *picker*, which needs
+ * `AdminMediaPort` wired; adding it before that picker exists would ship a kind indistinguishable
+ * from `"text"`. `"enum"` has a real unresolved question (does a queryable enum index the label or
+ * the ordinal?) and no forcing case.
+ */
+export type AdminEntityFieldKind = 'text' | 'integer' | 'real' | 'boolean' | 'datetime' | 'relation' | 'json';
+/** Fields common to every kind. `relation` adds `target`; `json` narrows `queryable`. */
+interface AdminEntityFieldBase {
+    /**
+     * The key this field occupies on a row.
+     *
+     * **No identifier grammar is imposed here, and that is deliberate.** The identifier grammar that
+     * gates a CMS content-type key (`^[a-z][a-z0-9_]{0,63}$`) is load-bearing where a field name
+     * reaches SQL DDL — it does not reach it here. Applying it to this descriptor would reject
+     * `authorId` and `createdAt`, i.e. would require an application to rename its own fields in order
+     * to get an admin. An app that is *also* persisted through the CMS maps names in its adapter,
+     * where the mapping is visible, rather than in its descriptor.
+     *
+     * `"id"` is reserved: every row already has one (see {@link AdminEntityRow}).
+     */
+    readonly name: string;
+    /** Human-readable column/label text. Falls back to {@link AdminEntityFieldBase.name}. */
+    readonly label?: string;
+    /** When true, the row type makes this field non-optional — see {@link AdminEntityRow}. */
+    readonly required?: boolean;
+    /**
+     * Whether a backend can filter or order on this field without a full scan.
+     *
+     * **Currently advisory in both directions, and nothing enforces either half.** A screen is
+     * expected to offer filter/sort controls only for `queryable` fields, and an adapter is expected
+     * to reject a filter on a non-queryable one rather than silently scanning — but this is a
+     * type-only port, so both are obligations rather than guarantees. An in-memory adapter (every
+     * app's first one) filters anything happily, so a filter that is a full scan in production looks
+     * correct in development. Read this flag as documentation of intent, not as a capability.
+     */
+    readonly queryable?: boolean;
+}
+/** A value stored inline: text, a number, a flag, or an ISO-8601 timestamp. */
+export type AdminEntityScalarField = AdminEntityFieldBase & {
+    readonly kind: 'text' | 'integer' | 'real' | 'boolean' | 'datetime';
+};
+/** A foreign id pointing at another registered entity. */
+export type AdminEntityRelationField = AdminEntityFieldBase & {
+    readonly kind: 'relation';
+    /**
+     * The {@link AdminEntityDescriptor.name} this field points at. Checked against the registry at
+     * composition time (`createAdminEntityRegistry`), not by the type system — a descriptor does not
+     * know which other descriptors it will be registered beside.
+     *
+     * **No referential integrity is implied anywhere.** Nothing validates that the stored id names a
+     * live row: not this port, not a rendering layer, not a persistence layer. A deleted target
+     * leaves a dangling reference, and a screen's honest rendering of that is the raw id, visibly
+     * marked as unresolved — not a blank cell.
+     */
+    readonly target: string;
+};
+/**
+ * An arbitrary JSON value stored verbatim.
+ *
+ * Exists because no scalar kind can hold a list or a nested object, and an application's own
+ * entities routinely have one (a recipe's ingredients). Storage-only: never indexed, never
+ * filtered, never ordered — which is why `queryable` is typed `false | undefined` here, making
+ * `queryable: true` on a json field a compile error rather than a runtime rejection.
+ */
+export type AdminEntityJsonField = Omit<AdminEntityFieldBase, 'queryable'> & {
+    readonly kind: 'json';
+    readonly queryable?: false;
+};
+/**
+ * One declared field. A discriminated union rather than a flat interface with optional extras, so
+ * `relation` can *require* its `target` instead of documenting that it needs one.
+ */
+export type AdminEntityField = AdminEntityScalarField | AdminEntityRelationField | AdminEntityJsonField;
+/** What an entity is: a name, labels, a title field, and its fields. */
+export interface AdminEntityDescriptor {
+    /**
+     * Stable machine name — the URL segment a generic screen routes on, and the value a
+     * {@link AdminEntityRelationField.target} names. Must equal the key this descriptor's port is
+     * registered under (enforced by `createAdminEntityRegistry`), so there is exactly one name for
+     * an entity rather than a registry key and a descriptor name that can drift apart.
+     */
+    readonly name: string;
+    readonly labelSingular: string;
+    readonly labelPlural: string;
+    /**
+     * Which field renders as a row's human-readable title — in lists, and in every relation picker
+     * that points at this entity.
+     *
+     * **Cannot be constrained to "a `text` field on this same descriptor" by the type system** without
+     * a conditional type heavy enough to make every descriptor's errors unreadable, so it is checked
+     * at registration instead. A typo here is not a small bug: it makes every relation picker
+     * pointing at this entity show `undefined` for every row.
+     */
+    readonly titleField: string;
+    readonly fields: readonly AdminEntityField[];
+}
+/** The runtime type each kind's value takes on a row. */
+interface AdminEntityKindValue {
+    text: string;
+    datetime: string;
+    integer: number;
+    real: number;
+    boolean: boolean;
+    /** A foreign id — same storage class as `text`. */
+    relation: string;
+    /** Storage-only, so nothing may consume it without narrowing first. */
+    json: unknown;
+}
+type AdminEntityFieldValue<F extends AdminEntityField> = F extends {
+    kind: infer K extends AdminEntityFieldKind;
+} ? K extends keyof AdminEntityKindValue ? AdminEntityKindValue[K] : never : never;
+type AdminEntityRequiredNames<F extends AdminEntityField> = F extends {
+    required: true;
+} ? F['name'] : never;
+/**
+ * The row shape a descriptor describes — derived, never hand-written.
+ *
+ * Requires the descriptor to be declared `as const satisfies AdminEntityDescriptor`: without
+ * `as const` the field names widen to `string` and every key collapses. Fields declared
+ * `required: true` are non-optional; everything else is optional. `id` is always present and is
+ * never a declared field.
+ *
+ * @example
+ * const recipe = {
+ *   name: 'recipe', labelSingular: 'Recipe', labelPlural: 'Recipes', titleField: 'title',
+ *   fields: [
+ *     { name: 'title', kind: 'text', required: true },
+ *     { name: 'authorId', kind: 'relation', target: 'author', required: true },
+ *     { name: 'ingredients', kind: 'json' },
+ *   ],
+ * } as const satisfies AdminEntityDescriptor;
+ * // AdminEntityRow<typeof recipe> is
+ * //   { id: string; title: string; authorId: string; ingredients?: unknown }
+ */
+export type AdminEntityRow<D extends AdminEntityDescriptor> = {
+    readonly id: string;
+} & {
+    readonly [F in D['fields'][number] as F['name'] & AdminEntityRequiredNames<F>]: AdminEntityFieldValue<F>;
+} & {
+    readonly [F in D['fields'][number] as F['name'] & Exclude<F['name'], AdminEntityRequiredNames<F>>]?: AdminEntityFieldValue<F>;
+};
+/** One filter clause. `field` should name a `queryable` field — see that flag's own caveat. */
+export interface AdminEntityFilter {
+    readonly field: string;
+    readonly op: 'eq' | 'neq' | 'lt' | 'lte' | 'gt' | 'gte';
+    readonly value: string | number | boolean;
+}
+export interface AdminEntityListQuery {
+    /** Maximum rows in the returned page. An adapter may return fewer; it must not return more. */
+    readonly limit?: number;
+    /**
+     * Opaque forward cursor, taken verbatim from a prior page's {@link AdminEntityPage.nextCursor}.
+     *
+     * **Not an offset.** An offset cannot be made stable under concurrent writes — a row inserted
+     * before the current position shifts every later page by one, silently duplicating or skipping a
+     * row. Every backend this port is likely to front can express keyset pagination over
+     * `(sortField, id)` instead.
+     *
+     * **Forward-only, by decision rather than by accident.** There is no `prevCursor`, because a
+     * backwards keyset walk needs a reversed comparator this port does not express. A screen that
+     * wants a "Previous" control holds the cursors it has already visited itself; that history is
+     * screen state and does not survive a reload.
+     */
+    readonly cursor?: string;
+    readonly filter?: readonly AdminEntityFilter[];
+    /**
+     * Ordering, applied by the adapter over the whole collection *before* the page is cut.
+     *
+     * Ordering is a server concern and this is the only place it may be expressed. Sorting a page
+     * after it has been cut reorders the rows on screen and nothing else — correct-looking at one
+     * page, meaningless at two, and no value-comparison test detects the difference.
+     */
+    readonly sort?: {
+        readonly field: string;
+        readonly direction: 'asc' | 'desc';
+    };
+}
+export interface AdminEntityPage<TRow> {
+    readonly items: readonly TRow[];
+    /**
+     * Cursor for the next page, or `null` on the last one.
+     *
+     * Required rather than optional — matching `AdminFormSubmissionPage`, this package's other
+     * cursor-paginated shape — because forgetting it silently caps every list at one page, which
+     * looks entirely correct until a collection outgrows one. `null` is a decision an adapter has to
+     * type out.
+     */
+    readonly nextCursor: string | null;
+    /**
+     * Total rows matching the query, when the adapter can count cheaply.
+     *
+     * Genuinely optional, unlike `nextCursor`: omitting it degrades one label, and forcing a count
+     * query on every list read to satisfy the type would be worse than not having the label.
+     */
+    readonly total?: number;
+}
+/**
+ * CRUD over one application-defined entity.
+ *
+ * `D` is the descriptor *value's* type (`typeof recipeDescriptor`), not `AdminEntityDescriptor` —
+ * that is what lets `list`/`get`/`create` return rows typed from the declaration.
+ *
+ * Note that `AdminEntityPort<SomeSpecificDescriptor>` is **not** assignable to
+ * `AdminEntityPort<AdminEntityDescriptor>`: `create`/`update` take the row type as a parameter and
+ * are therefore contravariant in it. A screen generic over all entities consumes
+ * {@link AdminErasedEntityPort} instead, reached through `eraseEntityPort`.
+ */
+export interface AdminEntityPort<D extends AdminEntityDescriptor> {
+    readonly descriptor: D;
+    list(query?: AdminEntityListQuery): Promise<AdminEntityPage<AdminEntityRow<D>>>;
+    get(id: string): Promise<AdminEntityRow<D> | null>;
+    create(input: Omit<AdminEntityRow<D>, 'id'>): Promise<AdminEntityRow<D>>;
+    update(id: string, patch: Partial<Omit<AdminEntityRow<D>, 'id'>>): Promise<AdminEntityRow<D>>;
+    /**
+     * Optional. An entity that cannot be deleted omits it, and a generic screen renders no delete
+     * affordance — the same "absence means the capability does not exist" convention
+     * `AdminMembersPort` uses for its deliberately missing `enableMember`.
+     */
+    remove?(id: string): Promise<void>;
+}
+/** A row with its field types erased, as a screen generic over all entities sees it. */
+export type AdminEntityRowData = Record<string, unknown> & {
+    readonly id: string;
+};
+/**
+ * {@link AdminEntityPort} with its descriptor generic erased — what a screen that renders *any*
+ * entity actually holds. Produced only by `eraseEntityPort`; never implemented directly.
+ */
+export interface AdminErasedEntityPort {
+    readonly descriptor: AdminEntityDescriptor;
+    list(query?: AdminEntityListQuery): Promise<AdminEntityPage<AdminEntityRowData>>;
+    get(id: string): Promise<AdminEntityRowData | null>;
+    create(input: Record<string, unknown>): Promise<AdminEntityRowData>;
+    update(id: string, patch: Record<string, unknown>): Promise<AdminEntityRowData>;
+    remove?(id: string): Promise<void>;
+}
+/**
+ * The assembled registry: entity name -> port, with each port's own type preserved.
+ *
+ * Same inference shape as `AdminClient` — a host's entities and any Jini-shipped ones would be
+ * indistinguishable here, and registering one is a line in an object literal.
+ */
+export type AdminEntityRegistry<TPorts extends Record<string, AdminEntityPort<AdminEntityDescriptor>>> = {
+    readonly [K in keyof TPorts]: TPorts[K];
+};
+export {};
+//# sourceMappingURL=entities.d.ts.map

package/dist/core/ports/entities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../../src/core/ports/entities.ts"],"names":[],"mappings":"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"}

package/dist/core/ports/entities.js

@@ -0,0 +1,47 @@
+/**
+ * @file `AdminEntityPort` — the one port that is generic over the entity it fronts.
+ *
+ * ## Why this port is shaped differently from every other one here
+ *
+ * Every other port in this directory names a fixed capability with a fixed row shape:
+ * `AdminMembersPort` returns `AdminMember`, `AdminSeoPort` returns `AdminSeoMeta`. That works
+ * because the capability is the same everywhere it is wired — a member is a member.
+ *
+ * An application's own entities are not like that. A recipe app has recipes and authors; a
+ * warehouse app has pallets and SKUs. There is no fixed row shape to write down, and force-fitting
+ * one onto an existing port is lossy in a way that shows up immediately: mapping an app's `Author`
+ * onto `AdminMember` has to invent a `status`, and drops every field (`bio`) the app actually has.
+ *
+ * So this port carries its own schema. An adapter declares an {@link AdminEntityDescriptor}, and
+ * the row type is *derived* from it ({@link AdminEntityRow}) rather than declared twice. A host
+ * screen reads the descriptor to decide what to render, which is what makes one screen able to
+ * render any entity with no per-entity code.
+ *
+ * ## What this port deliberately does NOT carry
+ *
+ * - **No `workspaceId`, and no other host-specific field.** If a field cannot be produced by an app
+ *   with no database, it does not belong on a generic row. Multi-tenancy is the adapter's business,
+ *   held in its own closure, invisible here. This is the single rule that keeps an adapter for a
+ *   plain in-memory array as short as an adapter for a real backend.
+ * - **No response envelope.** `list` returns {@link AdminEntityPage}, `get` returns the row itself
+ *   — never `{ entity }` or `{ items }`-plus-metadata. {@link AdminEntityPage} is not a
+ *   counterexample: `nextCursor` is pagination state that has nowhere else to live, not a wrapper
+ *   around the payload.
+ * - **No `expectedVersion` on `update`.** Every other write in this package carries one. It is
+ *   omitted here because an in-memory store has no version column, and requiring one would make the
+ *   smallest honest adapter impossible to write. An entity that wants optimistic concurrency
+ *   declares a `version` field of kind `"integer"` and enforces it inside its own `update`. This is
+ *   a real weakening relative to the other ports, stated rather than hidden, and worth revisiting
+ *   the first time a genuinely multi-writer entity appears.
+ * - **No publication lifecycle.** `AdminEntry`-style `draft`/`published` belongs to a CMS entry, not
+ *   to an arbitrary entity. An app that wants one declares a `status` field of kind `"text"`.
+ * - **No per-operation authorization seam** (no `canCreate`/`canDelete`). Consistent with every
+ *   other port here, and with `AdminPanel.permissions` being affordance-only — but worth naming,
+ *   because a generic CRUD surface over arbitrary application data is where that gap starts to
+ *   matter more than it does on a fixed screen.
+ *
+ * Types only, like every file in this directory. The runtime half — registration, descriptor
+ * validation, and the erasure a generic screen consumes — lives in `../entities/rules.ts`.
+ */
+export {};
+//# sourceMappingURL=entities.js.map

package/dist/core/ports/entities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.js","sourceRoot":"","sources":["../../../src/core/ports/entities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG"}

package/dist/core/ports/index.d.ts

@@ -18,4 +18,5 @@ export type { AdminSeoAnalysis, AdminSeoIssue, AdminSeoMeta, AdminSeoOpenGraph,
 export type { AdminRedirect, AdminRedirectCreateInput, AdminRedirectHitStats, AdminRedirectImportFailure, AdminRedirectImportResult, AdminRedirectListFilter, AdminRedirectsPort, AdminRedirectUpdatePatch, RedirectMatchType, RedirectSource, RedirectStatus, RedirectStatusCode, } from './redirects.js';
 export type { AdminAssignMenuLocationResult, AdminDeleteMenuResult, AdminMenu, AdminMenuBinding, AdminMenuCreateInput, AdminMenuCustomTarget, AdminMenuEntryTarget, AdminMenuItem, AdminMenuItemAttrs, AdminMenuRouteTarget, AdminMenusPort, AdminMenuTarget, AdminMenuTermTarget, AdminMenuUpdateTreeInput, AdminMenuUrlTarget, MenuStatus, NavTargetKind, } from './menus.js';
 export type { AdminFormCreateInput, AdminFormDefinition, AdminFormField, AdminFormNotifyConfig, AdminFormsPort, AdminFormSubmission, AdminFormSubmissionPage, AdminFormUpdatePatch, FormDefinitionStatus, FormFieldType, } from './forms.js';
+export type { AdminEntityDescriptor, AdminEntityField, AdminEntityFieldKind, AdminEntityFilter, AdminEntityJsonField, AdminEntityListQuery, AdminEntityPage, AdminEntityPort, AdminEntityRegistry, AdminEntityRelationField, AdminEntityRow, AdminEntityRowData, AdminEntityScalarField, AdminErasedEntityPort, } from './entities.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/ports/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/ports/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7D,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,EACZ,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,2BAA2B,EAC3B,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,wBAAwB,EACxB,+BAA+B,EAC/B,4BAA4B,EAC5B,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAClG,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzE,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,SAAS,GACV,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,YAAY,EACV,aAAa,EACb,wBAAwB,EACxB,qBAAqB,EACrB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,kBAAkB,EAClB,wBAAwB,EACxB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,6BAA6B,EAC7B,qBAAqB,EACrB,SAAS,EACT,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EAClB,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,GACd,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/ports/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7D,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,EACZ,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,2BAA2B,EAC3B,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,wBAAwB,EACxB,+BAA+B,EAC/B,4BAA4B,EAC5B,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAClG,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzE,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,SAAS,GACV,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,YAAY,EACV,aAAa,EACb,wBAAwB,EACxB,qBAAqB,EACrB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,kBAAkB,EAClB,wBAAwB,EACxB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,6BAA6B,EAC7B,qBAAqB,EACrB,SAAS,EACT,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EAClB,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,wBAAwB,EACxB,cAAc,EACd,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,eAAe,CAAC"}

package/dist/core/ports/menus.d.ts

@@ -25,6 +25,20 @@
  * `kind` values (with `AdminMenuCustomTarget` as the `default` arm) is the straightforward way to
  * stay correct.
  *
+ * **Migration hazard, measured 2026-09-05.** This is not merely a style preference — it means an
+ * exhaustive `switch` with NO `default` arm cannot compile against `AdminMenuTarget` at all, and
+ * that is exactly the shape a host arrives with. Both existing admin apps' `targetForKind`
+ * (`apps/admin/src/features/menus/MenuEditor.tsx`) switch over their own local CLOSED four-member
+ * union with no `default`, and rely on exhaustiveness for the return type. Compiling that function
+ * against this port's union emits `TS2366` (lacks ending return statement) plus a `TS2339` per
+ * field access. Confirmed by compiling the real function against this union directly.
+ *
+ * The hazard is pre-existing and belongs to `AdminMenuCustomTarget`, not to any later change: the
+ * identical probe run against the union with and without an extra member emits a character-for-
+ * character identical error set. Recorded here because it will surface the first time anyone wires
+ * a host onto this port, and the natural instinct will be to blame whatever change is in flight at
+ * that moment. The fix is a `default` arm in the host, not a change to this file.
+ *
  * **This is a deliberately deferred decision, not a settled one — record it as such.** `entryRef`/
  * `termRef` encode a host content model (an "entry" and a "taxonomy term" are the reference
  * implementation's own vocabulary for its content system, not a vendor-neutral abstraction this
@@ -39,6 +53,35 @@
  * instead of one, and a genuine vendor-neutral reference shape (rather than another bespoke
  * `kind`-per-host member) becomes the right call.
  *
+ * ### Status of that trigger, re-checked 2026-09-05 — NOT fired
+ *
+ * A second host now exists in this workspace, and that is NOT the trigger. The trigger is a second
+ * host needing a fifth KIND. Recording the difference here because a promotion was very nearly
+ * approved on the weaker reading. Four findings, all verified against source rather than assumed:
+ *
+ * 1. **Zero importers.** Nothing anywhere imports `AdminMenuTarget`, `NavTargetKind`, or any target
+ *    variant from this package. In this repo they are re-exported by `core/index.ts` and
+ *    `core/ports/index.ts` and consumed by nothing.
+ * 2. **Both admin apps declare their own.** Each ships a local, *closed*
+ *    `{ kind: "entryRef" | "termRef" | "url" | "route" }` in its own `src/lib/api.ts` — an HTTP
+ *    DTO, not this port. The two are byte-identical to each other: the second is a fork of the
+ *    first, so they are one data point, not two.
+ * 3. **The other `NavTargetKind` is a different type.** `@jini-ai/cms/navigation` exports its own
+ *    `NavTargetKind` (closed, plus a separate `ReservedNavTargetKind`). A host importing that one
+ *    is not exercising this port.
+ * 4. **The union is already open.** `AdminMenuCustomTarget`'s `kind: string & {}` already lets any
+ *    host express any kind today. Nothing is blocked while the decision stays deferred.
+ *
+ * So no fifth kind has been needed, and adding a named generic variant now would be designing from
+ * zero validating examples — the exact failure the paragraph above exists to prevent. Considered
+ * and rejected on 2026-09-05 for that reason. Re-check this section, not the prose above it,
+ * before concluding the trigger has fired.
+ *
+ * Note for whoever revisits: wiring `AdminMenusPort` into a host is the experiment that ANSWERS the
+ * type question, and it is not blocked by it. A host that wires the port and finds
+ * `entryRef`/`termRef` fit vindicates the deferral; one that needs a product/collection kind fires
+ * the trigger with a real second example to design from.
+ *
  * ## `deleteMenu` is a two-rung ladder driven by call count, not by `force` alone
  *
  * A single method models a two-step deletion flow: the FIRST call against a non-trashed menu

package/dist/core/ports/menus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"menus.d.ts","sourceRoot":"","sources":["../../../src/core/ports/menus.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"menus.d.ts","sourceRoot":"","sources":["../../../src/core/ports/menus.ts"],"names":[],"mappings":"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"}

package/dist/core/ports/menus.js

@@ -25,6 +25,20 @@
  * `kind` values (with `AdminMenuCustomTarget` as the `default` arm) is the straightforward way to
  * stay correct.
  *
+ * **Migration hazard, measured 2026-09-05.** This is not merely a style preference — it means an
+ * exhaustive `switch` with NO `default` arm cannot compile against `AdminMenuTarget` at all, and
+ * that is exactly the shape a host arrives with. Both existing admin apps' `targetForKind`
+ * (`apps/admin/src/features/menus/MenuEditor.tsx`) switch over their own local CLOSED four-member
+ * union with no `default`, and rely on exhaustiveness for the return type. Compiling that function
+ * against this port's union emits `TS2366` (lacks ending return statement) plus a `TS2339` per
+ * field access. Confirmed by compiling the real function against this union directly.
+ *
+ * The hazard is pre-existing and belongs to `AdminMenuCustomTarget`, not to any later change: the
+ * identical probe run against the union with and without an extra member emits a character-for-
+ * character identical error set. Recorded here because it will surface the first time anyone wires
+ * a host onto this port, and the natural instinct will be to blame whatever change is in flight at
+ * that moment. The fix is a `default` arm in the host, not a change to this file.
+ *
  * **This is a deliberately deferred decision, not a settled one — record it as such.** `entryRef`/
  * `termRef` encode a host content model (an "entry" and a "taxonomy term" are the reference
  * implementation's own vocabulary for its content system, not a vendor-neutral abstraction this
@@ -39,6 +53,35 @@
  * instead of one, and a genuine vendor-neutral reference shape (rather than another bespoke
  * `kind`-per-host member) becomes the right call.
  *
+ * ### Status of that trigger, re-checked 2026-09-05 — NOT fired
+ *
+ * A second host now exists in this workspace, and that is NOT the trigger. The trigger is a second
+ * host needing a fifth KIND. Recording the difference here because a promotion was very nearly
+ * approved on the weaker reading. Four findings, all verified against source rather than assumed:
+ *
+ * 1. **Zero importers.** Nothing anywhere imports `AdminMenuTarget`, `NavTargetKind`, or any target
+ *    variant from this package. In this repo they are re-exported by `core/index.ts` and
+ *    `core/ports/index.ts` and consumed by nothing.
+ * 2. **Both admin apps declare their own.** Each ships a local, *closed*
+ *    `{ kind: "entryRef" | "termRef" | "url" | "route" }` in its own `src/lib/api.ts` — an HTTP
+ *    DTO, not this port. The two are byte-identical to each other: the second is a fork of the
+ *    first, so they are one data point, not two.
+ * 3. **The other `NavTargetKind` is a different type.** `@jini-ai/cms/navigation` exports its own
+ *    `NavTargetKind` (closed, plus a separate `ReservedNavTargetKind`). A host importing that one
+ *    is not exercising this port.
+ * 4. **The union is already open.** `AdminMenuCustomTarget`'s `kind: string & {}` already lets any
+ *    host express any kind today. Nothing is blocked while the decision stays deferred.
+ *
+ * So no fifth kind has been needed, and adding a named generic variant now would be designing from
+ * zero validating examples — the exact failure the paragraph above exists to prevent. Considered
+ * and rejected on 2026-09-05 for that reason. Re-check this section, not the prose above it,
+ * before concluding the trigger has fired.
+ *
+ * Note for whoever revisits: wiring `AdminMenusPort` into a host is the experiment that ANSWERS the
+ * type question, and it is not blocked by it. A host that wires the port and finds
+ * `entryRef`/`termRef` fit vindicates the deferral; one that needs a product/collection kind fires
+ * the trigger with a real second example to design from.
+ *
  * ## `deleteMenu` is a two-rung ladder driven by call count, not by `force` alone
  *
  * A single method models a two-step deletion flow: the FIRST call against a non-trashed menu

package/dist/core/ports/menus.js.map

@@ -1 +1 @@
-{"version":3,"file":"menus.js","sourceRoot":"","sources":["../../../src/core/ports/menus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG"}
+{"version":3,"file":"menus.js","sourceRoot":"","sources":["../../../src/core/ports/menus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8GG"}