@jini-ai/cms 0.1.0

package/dist/navigation/contracts.js

@@ -0,0 +1,70 @@
+// ---------------------------------------------------------------------------
+// Permission catalog (flat dotted strings, code-side registered)
+// ---------------------------------------------------------------------------
+/**
+ * The `admin.menus.*` permission strings (renamed
+ * from the flat `navigation.manage` to the frozen `admin.<section>.<action>`
+ * convention, and split by action so force-purge no longer shares a
+ * permission with ordinary edits). `assign` is split from `update` because
+ * changing where a menu appears on the live site is higher-trust than
+ * editing an item label (mirrors the media library's `media.delete.force` /
+ * `media.upload_svg` splits); `delete.force` is split from `delete` for the
+ * same reason. The legacy `navigation.manage` string
+ * stays registered (deprecated, not deleted) in the host's identity permission
+ * registry until the Point of No Return — it
+ * is not part of this catalog. See `docs/decisions/permission-catalog-migration.md`
+ * for the migration's completion criteria.
+ */
+export const NAVIGATION_PERMISSIONS = [
+    "admin.menus.read",
+    "admin.menus.create",
+    "admin.menus.update",
+    "admin.menus.delete",
+    "admin.menus.delete.force",
+    "admin.menus.assign",
+    "admin.menus.manage",
+];
+// ---------------------------------------------------------------------------
+// Domain events (outbox, async, workspace-scoped)
+// ---------------------------------------------------------------------------
+/** Stable event names emitted on the outbox for async consumers. */
+export const NAVIGATION_EVENTS = [
+    "navigation.menu.created",
+    "navigation.menu.updated",
+    "navigation.menu.deleted",
+    "navigation.location.assigned",
+    "navigation.location.unassigned",
+];
+// ---------------------------------------------------------------------------
+// Hook points (synchronous, ordered, declared-before-attached)
+// ---------------------------------------------------------------------------
+/**
+ * Typed navigation hook points. Filters transform a value in-line (events
+ * cannot); the action lets extensions register locations. Declared here so the
+ * SDK/type system can enforce "declared points only" (the anti-hook-rot rule,
+ * the platform's v2 design doc §7).
+ */
+export const NAVIGATION_HOOKS = [
+    /** filter: transform a single resolved item (badge/count/dynamic label). */
+    "navigation.item.resolve",
+    /** filter: transform the whole resolved tree before render (visibility). */
+    "navigation.tree.filter",
+    /** action: register additional theme/plugin location keys. */
+    "navigation.locations.register",
+];
+// ---------------------------------------------------------------------------
+// AI tool surface (clients of the SAME gateway handlers — dogfooding the media library's pattern)
+// ---------------------------------------------------------------------------
+/**
+ * AI tools are thin clients of the same command/read handlers admins use (no
+ * back door). Agents are delegated principals (`grant ∩ delegator`);
+ * `update`/`assign`/`delete` are HITL through the change-set review layer.
+ */
+export const NAVIGATION_AI_TOOLS = [
+    "navigation.search",
+    "navigation.get",
+    "navigation.where_used",
+    "navigation.update", // HITL
+    "navigation.assign", // HITL
+];
+//# sourceMappingURL=contracts.js.map

package/dist/navigation/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/navigation/contracts.ts"],"names":[],"mappings":"AAmBA,8EAA8E;AAC9E,iEAAiE;AACjE,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,kBAAkB;IAClB,oBAAoB;IACpB,oBAAoB;IACpB,oBAAoB;IACpB,0BAA0B;IAC1B,oBAAoB;IACpB,oBAAoB;CACZ,CAAC;AAgDX,8EAA8E;AAC9E,kDAAkD;AAClD,8EAA8E;AAE9E,oEAAoE;AACpE,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,yBAAyB;IACzB,yBAAyB;IACzB,yBAAyB;IACzB,8BAA8B;IAC9B,gCAAgC;CACxB,CAAC;AAeX,8EAA8E;AAC9E,+DAA+D;AAC/D,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,4EAA4E;IAC5E,yBAAyB;IACzB,4EAA4E;IAC5E,wBAAwB;IACxB,8DAA8D;IAC9D,+BAA+B;CACvB,CAAC;AAIX,8EAA8E;AAC9E,kGAAkG;AAClG,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,mBAAmB;IACnB,gBAAgB;IAChB,uBAAuB;IACvB,mBAAmB,EAAE,OAAO;IAC5B,mBAAmB,EAAE,OAAO;CACpB,CAAC"}

package/dist/navigation/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @file Public surface (barrel) for the `navigation` library.
+ *
+ * A module's public contract is its `index.ts` — deep imports
+ * from outside this directory should go through here.
+ */
+export type { NavTargetKind, ReservedNavTargetKind, NavTarget, NavEntryTarget, NavTermTarget, NavUrlTarget, NavRouteTarget, NavItemAttrs, NavItemNode, NavMenuDoc, NavMenuEntry, MenuStatus, NavLocationKey, NavLocationBindingRow, NavLocationDescriptor, ResolvedNavItem, ResolvedNav, } from "./types.js";
+export { NAV_MENU_CONTENT_TYPE, NAV_FIELD_NAMESPACE, NAV_DOC_TYPE } from "./types.js";
+export type { NavLocationBindingRepoPort, NavResolveContext, NavTargetResolver, NavMenuReadModel, NavLocationRegistry, } from "./ports.js";
+export type { NavigationPermission, CreateMenuInput, UpdateMenuInput, AssignLocationInput, UnassignLocationInput, DeleteMenuInput, NavigationEventName, NavMenuChangedPayload, NavLocationChangedPayload, NavigationHookName, NavigationAiTool, NavWhereUsedResult, } from "./contracts.js";
+export { NAVIGATION_PERMISSIONS, NAVIGATION_EVENTS, NAVIGATION_HOOKS, NAVIGATION_AI_TOOLS, } from "./contracts.js";
+export { createNavMenuReadModel, type NavMenuReadModelDeps } from "./read-model.js";
+/**
+ * `MenuRepoPort` is navigation-owned (not part of the frozen `ports.ts` ADR surface — see
+ * `repo.memory.ts`'s file header for why) but is a real public contract: a host's own SQLite
+ * adapter implements it directly, the same way it implements `NavLocationBindingRepoPort`.
+ */
+export { InMemoryMenuRepo, InMemoryNavLocationBindingRepo, type MenuRepoPort, } from "./repo.memory.js";
+export { createMenu, updateMenuTree, assignLocation, deleteMenu, validateAndCloneTree, MenuNotFoundError, MenuValidationError, MenuConflictError, MenuLocationBoundError, DEFAULT_MAX_TREE_DEPTH, DEFAULT_MAX_ITEM_COUNT, type TreeValidationLimits, type CreateMenuDeps, type CreateMenuServiceInput, type CreateMenuRequired, type CreateMenuOptional, type UpdateMenuTreeDeps, type UpdateMenuTreeServiceInput, type UpdateMenuTreeRequired, type UpdateMenuTreeOptional, type AssignLocationDeps, type AssignLocationServiceInput, type AssignLocationRequired, type AssignLocationOptional, type DeleteMenuDeps, type DeleteMenuServiceInput, type DeleteMenuRequired, type DeleteMenuOptional, } from "./menu-service.js";
+export { resolveForLocation, resolveMenuDoc, type ResolveTargetHrefFn, type ResolvedTargetHref, type ResolveForLocationDeps, type ResolveForLocationServiceInput, type ResolveForLocationRequired, type ResolveForLocationOptional, } from "./resolver.js";
+export { rebuildNavLocationBindings, type RebuildNavLocationBindingsDeps, type RebuildNavLocationBindingsResult, } from "./reconcile.js";
+/** The agent-tool surface for this domain (see `agent-tools.ts` for what is deliberately omitted). */
+export { menusAgentToolCatalog, type AgentToolDefinition as NavigationAgentToolDefinition, type AgentToolSideEffect as NavigationAgentToolSideEffect, type AgentToolActorClassRule as NavigationAgentToolActorClassRule, } from "./agent-tools.js";
+/**
+ * The agent-tool wiring for this domain.
+ *
+ * `MenusToolDeps` is declared structurally rather than derived from any host's request-scoped
+ * dependency bag, which is what lets a host satisfy it by passing whatever object it already has —
+ * the shape is the contract, so no host type needs to be named here.
+ */
+export { buildMenusRegistrations, menusDerivedRisk, type MenusToolDeps, } from "./tool-registrations.js";
+/**
+ * There is no wiring/composition export here, deliberately. Assembling a concrete `MenuRepoPort`/
+ * `NavLocationBindingRepoPort` pair over a specific database handle would put one host's persistence
+ * choice on this library's public contract and drag that host's schema into every consumer's
+ * dependency closure. Hosts compose their own; this entry point exports the ports they compose
+ * against.
+ */
+//# sourceMappingURL=index.d.ts.map

package/dist/navigation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/navigation/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,YAAY,EACV,aAAa,EACb,qBAAqB,EACrB,SAAS,EACT,cAAc,EACd,aAAa,EACb,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,WAAW,EACX,UAAU,EACV,YAAY,EACZ,UAAU,EACV,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtF,YAAY,EACV,0BAA0B,EAC1B,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,sBAAsB,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEpF;;;;GAIG;AACH,OAAO,EACL,gBAAgB,EAChB,8BAA8B,EAC9B,KAAK,YAAY,GAClB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,UAAU,EACV,cAAc,EACd,cAAc,EACd,UAAU,EACV,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,8BAA8B,EACnC,KAAK,0BAA0B,EAC/B,KAAK,0BAA0B,GAChC,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,0BAA0B,EAC1B,KAAK,8BAA8B,EACnC,KAAK,gCAAgC,GACtC,MAAM,gBAAgB,CAAC;AAExB,sGAAsG;AACtG,OAAO,EACL,qBAAqB,EACrB,KAAK,mBAAmB,IAAI,6BAA6B,EACzD,KAAK,mBAAmB,IAAI,6BAA6B,EACzD,KAAK,uBAAuB,IAAI,iCAAiC,GAClE,MAAM,kBAAkB,CAAC;AAE1B;;;;;;GAMG;AACH,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,KAAK,aAAa,GACnB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;GAMG"}

package/dist/navigation/index.js

@@ -0,0 +1,30 @@
+export { NAV_MENU_CONTENT_TYPE, NAV_FIELD_NAMESPACE, NAV_DOC_TYPE } from "./types.js";
+export { NAVIGATION_PERMISSIONS, NAVIGATION_EVENTS, NAVIGATION_HOOKS, NAVIGATION_AI_TOOLS, } from "./contracts.js";
+export { createNavMenuReadModel } from "./read-model.js";
+/**
+ * `MenuRepoPort` is navigation-owned (not part of the frozen `ports.ts` ADR surface — see
+ * `repo.memory.ts`'s file header for why) but is a real public contract: a host's own SQLite
+ * adapter implements it directly, the same way it implements `NavLocationBindingRepoPort`.
+ */
+export { InMemoryMenuRepo, InMemoryNavLocationBindingRepo, } from "./repo.memory.js";
+export { createMenu, updateMenuTree, assignLocation, deleteMenu, validateAndCloneTree, MenuNotFoundError, MenuValidationError, MenuConflictError, MenuLocationBoundError, DEFAULT_MAX_TREE_DEPTH, DEFAULT_MAX_ITEM_COUNT, } from "./menu-service.js";
+export { resolveForLocation, resolveMenuDoc, } from "./resolver.js";
+export { rebuildNavLocationBindings, } from "./reconcile.js";
+/** The agent-tool surface for this domain (see `agent-tools.ts` for what is deliberately omitted). */
+export { menusAgentToolCatalog, } from "./agent-tools.js";
+/**
+ * The agent-tool wiring for this domain.
+ *
+ * `MenusToolDeps` is declared structurally rather than derived from any host's request-scoped
+ * dependency bag, which is what lets a host satisfy it by passing whatever object it already has —
+ * the shape is the contract, so no host type needs to be named here.
+ */
+export { buildMenusRegistrations, menusDerivedRisk, } from "./tool-registrations.js";
+/**
+ * There is no wiring/composition export here, deliberately. Assembling a concrete `MenuRepoPort`/
+ * `NavLocationBindingRepoPort` pair over a specific database handle would put one host's persistence
+ * choice on this library's public contract and drag that host's schema into every consumer's
+ * dependency closure. Hosts compose their own; this entry point exports the ports they compose
+ * against.
+ */
+//# sourceMappingURL=index.js.map

package/dist/navigation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/navigation/index.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAyBtF,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,sBAAsB,EAA6B,MAAM,iBAAiB,CAAC;AAEpF;;;;GAIG;AACH,OAAO,EACL,gBAAgB,EAChB,8BAA8B,GAE/B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,UAAU,EACV,cAAc,EACd,cAAc,EACd,UAAU,EACV,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,GAkBvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,kBAAkB,EAClB,cAAc,GAOf,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,0BAA0B,GAG3B,MAAM,gBAAgB,CAAC;AAExB,sGAAsG;AACtG,OAAO,EACL,qBAAqB,GAItB,MAAM,kBAAkB,CAAC;AAE1B;;;;;;GAMG;AACH,OAAO,EACL,uBAAuB,EACvB,gBAAgB,GAEjB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;GAMG"}

package/dist/navigation/menu-service.d.ts

@@ -0,0 +1,256 @@
+/**
+ * @file Write-service for the `navigation` library.
+ *
+ * Purpose:
+ * Implements the menu mutation slice: create, whole-tree update (OCC), soft
+ * delete → hard purge, and location assignment. Mirrors the host's `post`
+ * feature style (required/optional param objects, typed errors, OCC via
+ * `version`).
+ *
+ * How it relates to the project:
+ * - Storage is `MenuRepoPort` (`repo.memory.ts`) — a self-contained repo, not
+ *   the generic entries repo (see `repo.memory.ts`'s file header for why).
+ * - Location assignment additionally writes `NavLocationBindingRepoPort`
+ *   (`ports.ts`), the one real port this library declares.
+ * - In production this whole module runs inside the command
+ *   gateway/write chokepoint (same-transaction revision, attribution,
+ *   `entry_refs` extraction). That gateway is not implemented as running code
+ *   yet, so these functions are the chokepoint's future *contents*, called
+ *   directly for now.
+ *
+ * Architectural role:
+ * Feature logic only. No Express/route code, no direct SQL — everything goes
+ * through the injected repo ports (`deps`).
+ */
+import type { ClockPort, IdGeneratorPort, OutboxPort, UUID } from "../core/ports.js";
+import type { MenuRepoPort } from "./repo.memory.js";
+import type { NavLocationBindingRepoPort } from "./ports.js";
+import { type NavItemNode, type NavLocationBindingRow, type NavLocationKey, type NavMenuEntry } from "./types.js";
+export declare class MenuNotFoundError extends Error {
+}
+export declare class MenuValidationError extends Error {
+}
+export declare class MenuConflictError extends Error {
+}
+/**
+ * The 409-style purge rejection: hard delete is blocked while the menu is
+ * still bound to at least one theme location (deletion ladder).
+ * Carries the offending location keys so a caller can render "unassign these
+ * first" without a second lookup.
+ */
+export declare class MenuLocationBoundError extends MenuConflictError {
+    readonly boundLocations: readonly NavLocationKey[];
+    constructor(message: string, boundLocations: readonly NavLocationKey[]);
+}
+/** Default max nesting depth (root = depth 1). Configurable. */
+export declare const DEFAULT_MAX_TREE_DEPTH = 5;
+/** Default max total item count across the whole tree. */
+export declare const DEFAULT_MAX_ITEM_COUNT = 500;
+export interface TreeValidationLimits {
+    maxDepth?: number | undefined;
+    maxItemCount?: number | undefined;
+}
+/**
+ * Validates a candidate item tree and returns a defensively-cloned copy.
+ *
+ * Checks (total/bounded validation + target integrity):
+ * - every node has a non-empty `id`, unique across the whole tree (id
+ *   stability is a caller responsibility — see `updateMenuTree` doc for the
+ *   simplification this build accepts);
+ * - nesting depth stays within `maxDepth`;
+ * - total item count stays within `maxItemCount`;
+ * - every target's `kind` is one of the four v1 kinds — reserved kinds
+ *   (`dynamicQuery`, `content`) are rejected with a clear "not yet" error
+ *   rather than silently accepted;
+ * - `url` targets reject a scheme denylist (`javascript:`, `data:`, `vbscript:`).
+ *
+ * @complexity O(n) over total node count for one full walk; no per-node
+ * backtracking. Space is O(n) for the cloned tree plus O(n) for the id set.
+ * @overallScore 100
+ */
+export declare function validateAndCloneTree(items: readonly NavItemNode[], limits?: TreeValidationLimits): NavItemNode[];
+export interface CreateMenuDeps {
+    repo: MenuRepoPort;
+    clock: ClockPort;
+    idGen: IdGeneratorPort;
+    /** Enqueues `navigation.menu.created` after a successful save. */
+    outbox: OutboxPort;
+}
+export interface CreateMenuServiceInput {
+    workspaceId: UUID;
+    title: string;
+    slug: string;
+    /** Optional initial tree; defaults to an empty menu. Items must carry ids. */
+    items?: readonly NavItemNode[] | undefined;
+}
+export interface CreateMenuRequired {
+    deps: CreateMenuDeps;
+    input: CreateMenuServiceInput;
+}
+export interface CreateMenuOptional {
+    limits?: TreeValidationLimits | undefined;
+}
+/**
+ * Creates a new `menu` entry in `published` status with no location
+ * assignments. Rejects a duplicate slug within the workspace.
+ *
+ * Was `draft` originally (mirroring `posts`), changed 2026-08-09 on explicit product direction: a
+ * menu has no separate review/approval workflow the way a post does, and `resolveForLocation`
+ * (`resolver.ts`) never actually branched on `status` — the field only ever gated the trash/purge
+ * lifecycle. Landing a new menu in `draft` produced a status label at odds with its real behavior
+ * (already fully live wherever it gets bound to a location) rather than gating anything real, so
+ * the default now matches the actual behavior instead of implying a workflow that doesn't exist.
+ *
+ * @complexity O(n) in the initial tree size for validation; O(m) in existing
+ * menu count for the slug-uniqueness scan (repo-dependent).
+ * @overallScore 100
+ */
+export declare function createMenu(required: CreateMenuRequired, optional?: CreateMenuOptional): Promise<{
+    menu: NavMenuEntry;
+}>;
+export interface UpdateMenuTreeDeps {
+    repo: MenuRepoPort;
+    clock: ClockPort;
+    /** Not previously present on this deps bag — needed to mint the outbox event's id. */
+    idGen: IdGeneratorPort;
+    /** Enqueues `navigation.menu.updated` after a successful save. */
+    outbox: OutboxPort;
+}
+export interface UpdateMenuTreeServiceInput {
+    workspaceId: UUID;
+    id: UUID;
+    /** The entry `version` this edit was based on — OCC guard. */
+    expectedVersion: number;
+    title?: string | undefined;
+    slug?: string | undefined;
+    /** The full replacement tree (whole-tree edit). */
+    items: readonly NavItemNode[];
+}
+export interface UpdateMenuTreeRequired {
+    deps: UpdateMenuTreeDeps;
+    input: UpdateMenuTreeServiceInput;
+}
+export interface UpdateMenuTreeOptional {
+    limits?: TreeValidationLimits | undefined;
+}
+/**
+ * Replaces a menu's whole item tree, guarded by optimistic concurrency on the
+ * entry `version` (matches the host's `updatePost` pattern).
+ *
+ * Id-stability note ("an update may not renumber surviving items"):
+ * this build enforces only that ids are present and unique within the
+ * submitted tree (`validateAndCloneTree`). Detecting whether a *specific*
+ * surviving node kept its original id would require diffing against the
+ * previous tree and is deferred — a caller-discipline requirement for now,
+ * not a runtime-enforced invariant.
+ *
+ * @complexity O(n) in the new tree size for validation; O(1) additional repo
+ * calls (one read, at most one slug-uniqueness read, one write).
+ * @overallScore 90
+ * @findings Medium: id-stability across edits (ids not renumbered on survive)
+ * is documented but not runtime-enforced — see doc comment above. Deferred
+ * pending a tree-diff mechanism; would need the previous tree's id set passed
+ * in to check "no id vanished and reappeared elsewhere," which is more than
+ * this slice's scope calls for.
+ */
+export declare function updateMenuTree(required: UpdateMenuTreeRequired, optional?: UpdateMenuTreeOptional): Promise<{
+    menu: NavMenuEntry;
+}>;
+export interface AssignLocationDeps {
+    repo: MenuRepoPort;
+    bindingRepo: NavLocationBindingRepoPort;
+    clock: ClockPort;
+    /** Not previously present on this deps bag — needed to mint outbox event ids. */
+    idGen: IdGeneratorPort;
+    /** Enqueues `navigation.location.assigned` (+ `.unassigned` on reassignment). */
+    outbox: OutboxPort;
+}
+export interface AssignLocationServiceInput {
+    workspaceId: UUID;
+    menuId: UUID;
+    locationKey: NavLocationKey;
+}
+export interface AssignLocationRequired {
+    deps: AssignLocationDeps;
+    input: AssignLocationServiceInput;
+}
+export interface AssignLocationOptional {
+}
+/**
+ * Assigns a menu to a theme location. This writes two
+ * representations that must stay in lockstep:
+ * 1. the menu's own `locations` field (source of truth, revisioned), and
+ * 2. the derived `nav_location_bindings` row (uniqueness index).
+ *
+ * If the location was already bound to a *different* menu, that menu is
+ * **reassigned away** (last-writer-wins, the chosen
+ * default) and its `locations` field is updated to drop the key — recorded as
+ * its own revision-worthy write.
+ *
+ * Atomicity note: these writes are
+ * logically ONE transaction — the binding-index write is a second in-tx
+ * participant alongside a slug-change-capture slot in the host's routing
+ * layer. Neither real cross-write transactions nor that routing layer exist
+ * as running code yet anywhere this library has shipped, so this function
+ * performs the writes sequentially with no rollback if a later step throws.
+ * This is an accepted, documented gap pending the command gateway's
+ * transaction machinery — do not copy this sequencing pattern into code that
+ * has real transactions available.
+ *
+ * @complexity O(1) repo calls (bounded: at most two menu reads/writes plus one
+ * binding upsert), independent of workspace size.
+ * @overallScore 90
+ * @findings Medium: no rollback across the two writes (menu save, then
+ * binding upsert) if the second fails, leaving the derived index stale until
+ * a rebuild. Acceptable because the index is declared rebuildable-by-definition;
+ * flagged as tech debt for when transactions
+ * exist.
+ */
+export declare function assignLocation(required: AssignLocationRequired, _optional?: AssignLocationOptional): Promise<{
+    menu: NavMenuEntry;
+    binding: NavLocationBindingRow;
+    displacedMenu: NavMenuEntry | null;
+}>;
+export interface DeleteMenuDeps {
+    repo: MenuRepoPort;
+    bindingRepo: NavLocationBindingRepoPort;
+    clock: ClockPort;
+    /** Not previously present on this deps bag — needed to mint outbox event ids. */
+    idGen: IdGeneratorPort;
+    /** Enqueues `navigation.menu.updated` (trash) or `navigation.menu.deleted` (purge); nothing on a blocked purge. */
+    outbox: OutboxPort;
+}
+export interface DeleteMenuServiceInput {
+    workspaceId: UUID;
+    id: UUID;
+    /** Force past the 409 dangling-location guard (needs `navigation.delete.force`). */
+    force?: boolean | undefined;
+}
+export interface DeleteMenuRequired {
+    deps: DeleteMenuDeps;
+    input: DeleteMenuServiceInput;
+}
+export interface DeleteMenuOptional {
+}
+/**
+ * Deletion ladder (mirrors the media library's):
+ * 1. First call on a non-trashed menu **soft-deletes** it (`status: 'trash'`,
+ *    revisioned) and returns — no purge yet.
+ * 2. A second call on an already-trashed menu attempts the **hard purge**. If
+ *    the menu is still bound to any location, purge is rejected with
+ *    `MenuLocationBoundError` (409-style) listing the bound keys, unless
+ *    `force` is set — permission-gating that error behind
+ *    `navigation.delete.force` is the caller's (gateway's) job, not this
+ *    function's; this function only enforces the *shape* of the guard.
+ * 3. On a successful purge, the menu row and all of its location bindings are
+ *    removed.
+ *
+ * @complexity O(1) repo calls; O(k) bindings scanned where k = locations this
+ * menu holds (small, bounded by registered locations).
+ * @overallScore 100
+ */
+export declare function deleteMenu(required: DeleteMenuRequired, _optional?: DeleteMenuOptional): Promise<{
+    menu: NavMenuEntry | null;
+    purged: boolean;
+}>;
+//# sourceMappingURL=menu-service.d.ts.map

package/dist/navigation/menu-service.d.ts.map

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