@jini-ai/admin 0.1.0

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

@@ -0,0 +1,179 @@
+/**
+ * @file `AdminMenusPort` — editable navigation trees (menus), and their assignment to named theme
+ * locations.
+ *
+ * ## `AdminMenuTarget` and the content-model leak
+ *
+ * The reference implementation's own link-target union ties two of its four kinds directly to its
+ * content model: `entryRef` points at a content-item id, `termRef` points at a taxonomy-term id plus its
+ * taxonomy name. Baking exactly those four kinds into this port as a CLOSED union would mean any
+ * host without an "entry"/"taxonomy term" concept (or with additional native reference kinds of
+ * its own — a product, a collection, ...) could never express its own link targets through this
+ * contract at all; it would have to fake them as `url` targets, defeating the point of a typed
+ * target. `AdminMenuTarget` therefore keeps the 4 reference-implementation kinds as their own typed
+ * variants (they are reasonably generic CMS concepts, not literally "post"/"page") but adds
+ * `AdminMenuCustomTarget` as a fifth, open-`kind` escape hatch for anything else a host needs.
+ *
+ * This has a real, deliberate type-safety cost worth knowing before you rely on it: because
+ * `AdminMenuCustomTarget.kind` is `string & {}`, it structurally overlaps every literal kind below
+ * it — narrowing `AdminMenuTarget` by `target.kind === "entryRef"` does not, on its own, fully
+ * exclude `AdminMenuCustomTarget` from the narrowed type the way it would exclude
+ * `AdminMenuTermTarget`/`AdminMenuUrlTarget`/`AdminMenuRouteTarget`. In practice this only shows up
+ * as a compile error if you then try to access a known-target-only field (e.g. `.entryId`) without
+ * having ruled out the custom-target case first, since `AdminMenuCustomTarget` carries no such
+ * field — TypeScript will refuse the access rather than silently mistype it. A `switch` over all 5
+ * `kind` values (with `AdminMenuCustomTarget` as the `default` arm) is the straightforward way to
+ * stay correct.
+ *
+ * **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
+ * package has designed). A host with no entries or taxonomies should emit only `url`/`route`
+ * targets and ignore those two variants entirely; it is not expected to reinterpret them. This was
+ * deliberately NOT generalized into a single vendor-neutral "content reference" shape, because
+ * there is exactly one host implementation in this corpus today — designing a generic content-reference abstraction from a single
+ * example is how a package acquires the wrong abstraction permanently, not how it becomes generic.
+ * Widening `kind` (this file) costs nothing and preserves the option without committing to a shape.
+ * **Trigger for revisiting:** a second host needs a link-target kind that is neither `entryRef`,
+ * `termRef`, `url`, nor `route` — at that point there are two real examples to generalize from
+ * instead of one, and a genuine vendor-neutral reference shape (rather than another bespoke
+ * `kind`-per-host member) becomes the right call.
+ *
+ * ## `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
+ * always soft-deletes it (status flips, resolves `{ purged: false }`) regardless of `force` or
+ * location bindings. Only a SECOND call — against a menu that is already trashed — attempts the
+ * real purge, which is rejected (conflict-class, with the still-bound location keys) if the menu is
+ * still assigned to any theme location, unless `options.force` is set. This is a third distinct
+ * deletion shape in this port set, different from both `AdminIntegrationsPort`'s permanent-soft-
+ * delete-only and `AdminMediaPort`'s two-separate-methods (`trashMedia`/`deleteMedia`) split: here
+ * it is the SAME method, and which rung it hits depends on the menu's current state, not on an
+ * argument you pass. A panel must track (or re-fetch) whether a menu is already trashed to know
+ * what calling `deleteMenu` again will actually do.
+ *
+ * ## `assignMenuLocation` can displace another menu (last-writer-wins)
+ *
+ * Assigning a menu to a location key that is already bound to a *different* menu unassigns that
+ * other menu from the location (dropping the key from its own `locations`) rather than rejecting
+ * the call. `AdminAssignMenuLocationResult.displacedMenu` carries that menu's post-displacement
+ * state so a panel can show what changed; it is `null` when the location was unbound or already
+ * held by the menu being assigned.
+ *
+ * ## Open vs. closed unions
+ *
+ * `NavTargetKind` and `MenuStatus` are reference-implementation-specific vocabularies (the former further discussed
+ * above) — OPEN, via the `T | (string & {})` idiom `seo.ts`'s file header introduces for this port
+ * set.
+ */
+/** The known target-kind discriminants — open, see file header. */
+export type NavTargetKind = "entryRef" | "termRef" | "url" | "route" | (string & {});
+/** A link to another content item, by opaque id. */
+export interface AdminMenuEntryTarget {
+    readonly kind: "entryRef";
+    readonly entryId: string;
+}
+/** A link to a taxonomy term (category/tag archive, or a host's closest equivalent grouping). */
+export interface AdminMenuTermTarget {
+    readonly kind: "termRef";
+    readonly termId: string;
+    /** Which taxonomy `termId` belongs to. */
+    readonly taxonomy: string;
+}
+/** An absolute or site-relative external URL. */
+export interface AdminMenuUrlTarget {
+    readonly kind: "url";
+    readonly href: string;
+}
+/** A named host route (e.g. `home`, `search`). */
+export interface AdminMenuRouteTarget {
+    readonly kind: "route";
+    readonly route: string;
+    readonly params?: Record<string, unknown>;
+}
+/** A host-specific target kind beyond the 4 above — see file header for the narrowing tradeoff
+ *  this member introduces. `data` is opaque to this port; the host defines its own shape. */
+export interface AdminMenuCustomTarget {
+    readonly kind: string & {};
+    readonly data?: Record<string, unknown>;
+}
+export type AdminMenuTarget = AdminMenuEntryTarget | AdminMenuTermTarget | AdminMenuUrlTarget | AdminMenuRouteTarget | AdminMenuCustomTarget;
+export interface AdminMenuItemAttrs {
+    readonly openInNewTab?: boolean;
+    /** `rel` tokens (e.g. `nofollow`). */
+    readonly rel?: string;
+    readonly cssClass?: string;
+    readonly description?: string;
+    readonly icon?: string;
+}
+/** One node in a menu's item tree. Ordering is array order among siblings; nesting is `children`.
+ *  `id` must be stable across edits (see `updateMenuTree`) — never regenerate it on reorder. */
+export interface AdminMenuItem {
+    readonly id: string;
+    /** As stored — this port does not fall back to the target's own title when absent. (The
+     *  reference implementation only applies that fallback in its separate, unexposed render-time
+     *  resolution model; the raw item this port returns leaves an absent label absent.) A panel
+     *  wanting a display fallback must compute one itself. */
+    readonly label?: string;
+    readonly target: AdminMenuTarget;
+    readonly attrs?: AdminMenuItemAttrs;
+    readonly children?: readonly AdminMenuItem[];
+}
+/** Lifecycle of a menu itself — open, see file header. */
+export type MenuStatus = "draft" | "published" | "trash" | (string & {});
+export interface AdminMenu {
+    readonly id: string;
+    readonly slug: string;
+    readonly title: string;
+    readonly status: MenuStatus;
+    readonly items: readonly AdminMenuItem[];
+    /** Theme-location keys this menu currently fills. */
+    readonly locations: readonly string[];
+    readonly updatedAt: string;
+    readonly version: number;
+}
+export interface AdminMenuCreateInput {
+    readonly title: string;
+    readonly slug: string;
+    /** Defaults to an empty menu when omitted. Every item needs a stable `id`. */
+    readonly items?: readonly AdminMenuItem[];
+}
+export interface AdminMenuUpdateTreeInput {
+    /** The `version` this edit was based on — optimistic-concurrency guard; expect a conflict-class
+     *  rejection if the menu was modified since. */
+    readonly expectedVersion: number;
+    readonly title?: string;
+    readonly slug?: string;
+    /** The FULL replacement tree — this is a whole-tree replace, not a per-item patch. */
+    readonly items: readonly AdminMenuItem[];
+}
+export interface AdminMenuBinding {
+    readonly locationKey: string;
+    readonly menuId: string;
+    readonly boundAt: string;
+}
+export interface AdminAssignMenuLocationResult {
+    readonly menu: AdminMenu;
+    readonly binding: AdminMenuBinding;
+    /** See file header (last-writer-wins displacement). */
+    readonly displacedMenu: AdminMenu | null;
+}
+export interface AdminDeleteMenuResult {
+    /** Null only after a successful purge (the second-rung outcome) — see file header. */
+    readonly menu: AdminMenu | null;
+    readonly purged: boolean;
+}
+export interface AdminMenusPort {
+    listMenus(): Promise<readonly AdminMenu[]>;
+    getMenu(id: string): Promise<AdminMenu>;
+    createMenu(input: AdminMenuCreateInput): Promise<AdminMenu>;
+    updateMenuTree(id: string, input: AdminMenuUpdateTreeInput): Promise<AdminMenu>;
+    /** Two-rung ladder driven by the menu's current trashed state, not solely by `options.force` —
+     *  see file header before assuming what a given call will do. */
+    deleteMenu(id: string, options?: {
+        force?: boolean;
+    }): Promise<AdminDeleteMenuResult>;
+    /** May displace another menu already bound to `locationKey` — see file header. */
+    assignMenuLocation(id: string, locationKey: string): Promise<AdminAssignMenuLocationResult>;
+}
+//# sourceMappingURL=menus.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,70 @@
+/**
+ * @file `AdminMenusPort` — editable navigation trees (menus), and their assignment to named theme
+ * locations.
+ *
+ * ## `AdminMenuTarget` and the content-model leak
+ *
+ * The reference implementation's own link-target union ties two of its four kinds directly to its
+ * content model: `entryRef` points at a content-item id, `termRef` points at a taxonomy-term id plus its
+ * taxonomy name. Baking exactly those four kinds into this port as a CLOSED union would mean any
+ * host without an "entry"/"taxonomy term" concept (or with additional native reference kinds of
+ * its own — a product, a collection, ...) could never express its own link targets through this
+ * contract at all; it would have to fake them as `url` targets, defeating the point of a typed
+ * target. `AdminMenuTarget` therefore keeps the 4 reference-implementation kinds as their own typed
+ * variants (they are reasonably generic CMS concepts, not literally "post"/"page") but adds
+ * `AdminMenuCustomTarget` as a fifth, open-`kind` escape hatch for anything else a host needs.
+ *
+ * This has a real, deliberate type-safety cost worth knowing before you rely on it: because
+ * `AdminMenuCustomTarget.kind` is `string & {}`, it structurally overlaps every literal kind below
+ * it — narrowing `AdminMenuTarget` by `target.kind === "entryRef"` does not, on its own, fully
+ * exclude `AdminMenuCustomTarget` from the narrowed type the way it would exclude
+ * `AdminMenuTermTarget`/`AdminMenuUrlTarget`/`AdminMenuRouteTarget`. In practice this only shows up
+ * as a compile error if you then try to access a known-target-only field (e.g. `.entryId`) without
+ * having ruled out the custom-target case first, since `AdminMenuCustomTarget` carries no such
+ * field — TypeScript will refuse the access rather than silently mistype it. A `switch` over all 5
+ * `kind` values (with `AdminMenuCustomTarget` as the `default` arm) is the straightforward way to
+ * stay correct.
+ *
+ * **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
+ * package has designed). A host with no entries or taxonomies should emit only `url`/`route`
+ * targets and ignore those two variants entirely; it is not expected to reinterpret them. This was
+ * deliberately NOT generalized into a single vendor-neutral "content reference" shape, because
+ * there is exactly one host implementation in this corpus today — designing a generic content-reference abstraction from a single
+ * example is how a package acquires the wrong abstraction permanently, not how it becomes generic.
+ * Widening `kind` (this file) costs nothing and preserves the option without committing to a shape.
+ * **Trigger for revisiting:** a second host needs a link-target kind that is neither `entryRef`,
+ * `termRef`, `url`, nor `route` — at that point there are two real examples to generalize from
+ * instead of one, and a genuine vendor-neutral reference shape (rather than another bespoke
+ * `kind`-per-host member) becomes the right call.
+ *
+ * ## `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
+ * always soft-deletes it (status flips, resolves `{ purged: false }`) regardless of `force` or
+ * location bindings. Only a SECOND call — against a menu that is already trashed — attempts the
+ * real purge, which is rejected (conflict-class, with the still-bound location keys) if the menu is
+ * still assigned to any theme location, unless `options.force` is set. This is a third distinct
+ * deletion shape in this port set, different from both `AdminIntegrationsPort`'s permanent-soft-
+ * delete-only and `AdminMediaPort`'s two-separate-methods (`trashMedia`/`deleteMedia`) split: here
+ * it is the SAME method, and which rung it hits depends on the menu's current state, not on an
+ * argument you pass. A panel must track (or re-fetch) whether a menu is already trashed to know
+ * what calling `deleteMenu` again will actually do.
+ *
+ * ## `assignMenuLocation` can displace another menu (last-writer-wins)
+ *
+ * Assigning a menu to a location key that is already bound to a *different* menu unassigns that
+ * other menu from the location (dropping the key from its own `locations`) rather than rejecting
+ * the call. `AdminAssignMenuLocationResult.displacedMenu` carries that menu's post-displacement
+ * state so a panel can show what changed; it is `null` when the location was unbound or already
+ * held by the menu being assigned.
+ *
+ * ## Open vs. closed unions
+ *
+ * `NavTargetKind` and `MenuStatus` are reference-implementation-specific vocabularies (the former further discussed
+ * above) — OPEN, via the `T | (string & {})` idiom `seo.ts`'s file header introduces for this port
+ * set.
+ */
+export {};
+//# sourceMappingURL=menus.js.map

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

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

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

@@ -0,0 +1,68 @@
+/**
+ * @file `AdminExtensionsPort` — installed extensions (the reference implementation calls them
+ * "plugins") and their
+ * enabled/disabled state.
+ *
+ * ## Why the port is "Extensions" but the DTO and methods say "Plugin"
+ *
+ * The port interface is named generically because not every host will call this mechanism
+ * "plugins" — some call the same concept "add-ons" or "extensions" in their own product copy.
+ * The DTO (`AdminPlugin`) and method names (`listPlugins`/`setPluginEnabled`) keep the reference
+ * implementation's own vocabulary rather than being renamed to match, because "plugin" is itself
+ * already a generic, industry-standard term (not product-specific jargon the way `workspace-local`
+ * or `/api/admin/v1` are) and because the calling code this port replaces already uses these exact
+ * names — renaming
+ * both the port and its members would be a bigger, noisier diff for no behavioral gain. A host
+ * that genuinely prefers "extension" throughout is free to alias at the call site.
+ *
+ * ## `changeSetId` is an opaque audit handle, not a claim every host has "change sets"
+ *
+ * `setExtensionEnabled`'s response carries a `changeSetId` because the reference implementation
+ * versions every mutating admin action through a change-set/revert subsystem. This port keeps the
+ * field — real callers may want to link to an audit trail — but treats it as an opaque string a
+ * host can use however its own audit mechanism works, not a promise that "change set" is a concept
+ * every implementation shares.
+ */
+/** An installed extension and its trust/validity state. */
+export interface AdminPlugin {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    /** `"built-in"` ships with the host itself; `"site"` was installed for this particular
+     *  installation/tenant. */
+    readonly source: "built-in" | "site";
+    /** Trust tier driving how much a panel should warn before enabling this extension — lower
+     *  numbers are more trusted. Not ordered numerically on the wire on purpose (host-defined
+     *  labels), see `../transport/errors.ts`'s header for the same "vocabulary belongs to the host"
+     *  reasoning applied to error codes. */
+    readonly tier: "tier-1" | "tier-2" | "tier-3";
+    /** Whether the extension currently passes the host's own structural/compatibility checks —
+     *  independent of `enabled`. An extension can be `"valid"` and still `enabled: false`, or
+     *  `"invalid"`/`"incompatible"` while still `enabled: true` from a prior state the host has not
+     *  auto-disabled. */
+    readonly status: "valid" | "invalid" | "incompatible";
+    readonly enabled: boolean;
+    readonly errors: readonly {
+        code: string;
+        file: string | null;
+        message: string;
+    }[];
+}
+/** `setExtensionEnabled`'s response — a trimmed extension summary plus an audit handle, not the
+ *  full `AdminPlugin`. See the file header on `changeSetId`. */
+export interface AdminExtensionEnabledResult {
+    readonly extension: {
+        id: string;
+        version: string;
+        enabled: boolean;
+        updatedAt: string;
+    };
+    readonly changeSetId: string;
+}
+export interface AdminExtensionsPort {
+    listPlugins(): Promise<readonly AdminPlugin[]>;
+    setPluginEnabled(id: string, input: {
+        enabled: boolean;
+    }): Promise<AdminExtensionEnabledResult>;
+}
+//# sourceMappingURL=plugins.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../../src/core/ports/plugins.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;+BAC2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC;IACrC;;;4CAGwC;IACxC,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC9C;;;yBAGqB;IACrB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,cAAc,CAAC;IACtD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACpF;AAED;gEACgE;AAChE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACzF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,IAAI,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;CACjG"}

package/dist/core/ports/plugins.js

@@ -0,0 +1,27 @@
+/**
+ * @file `AdminExtensionsPort` — installed extensions (the reference implementation calls them
+ * "plugins") and their
+ * enabled/disabled state.
+ *
+ * ## Why the port is "Extensions" but the DTO and methods say "Plugin"
+ *
+ * The port interface is named generically because not every host will call this mechanism
+ * "plugins" — some call the same concept "add-ons" or "extensions" in their own product copy.
+ * The DTO (`AdminPlugin`) and method names (`listPlugins`/`setPluginEnabled`) keep the reference
+ * implementation's own vocabulary rather than being renamed to match, because "plugin" is itself
+ * already a generic, industry-standard term (not product-specific jargon the way `workspace-local`
+ * or `/api/admin/v1` are) and because the calling code this port replaces already uses these exact
+ * names — renaming
+ * both the port and its members would be a bigger, noisier diff for no behavioral gain. A host
+ * that genuinely prefers "extension" throughout is free to alias at the call site.
+ *
+ * ## `changeSetId` is an opaque audit handle, not a claim every host has "change sets"
+ *
+ * `setExtensionEnabled`'s response carries a `changeSetId` because the reference implementation
+ * versions every mutating admin action through a change-set/revert subsystem. This port keeps the
+ * field — real callers may want to link to an audit trail — but treats it as an opaque string a
+ * host can use however its own audit mechanism works, not a promise that "change set" is a concept
+ * every implementation shares.
+ */
+export {};
+//# sourceMappingURL=plugins.js.map

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

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

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

@@ -0,0 +1,171 @@
+/**
+ * @file `AdminRecoveryPort` — point-in-time restore: what can be restored to, what would be lost,
+ * and the restore ceremony itself.
+ *
+ * `AdminRestorePoint` is imported from `./database.js` rather than redeclared — see that file's
+ * header for why Database and Recovery are two views onto one persisted set.
+ *
+ * ## The restore triad IS a `GatedOperation` — with operation-specific confirm/execute input
+ *
+ * `./database.js`'s `migrateForward` is the simple case: none of its three calls needs input
+ * beyond the token the previous step produced. Restore needs two more fields —
+ *
+ * - `confirm` also carries `disclosureAcknowledged`: the operator must affirmatively accept the
+ *   data-loss disclosure `computeRecoveryDisclosure` computed, not merely echo back a token; and
+ * - `execute` also carries `restorePointId`: belt-and-suspenders against a confirmation token
+ *   being replayed against a different target than the one it was confirmed for.
+ *
+ * `GatedOperation` carries `TConfirmInput`/`TExecuteInput` type parameters (defaulting to `string`)
+ * for exactly this, so restore is declared as a real `GatedOperation` rather than three loose
+ * methods. See `../gated/types.js` for the full rationale — in short, `disclosureAcknowledged`
+ * shows the protocol is *recorded informed consent* rather than a two-step token handshake, and
+ * restore is the most destructive operation a host exposes, so it is the last thing that should sit
+ * outside the abstraction built for that ceremony.
+ *
+ * A first draft of this file argued the opposite, against an earlier `confirm(token: string)`
+ * signature, and predicted the widening that has since happened. Kept as a note because the
+ * inference was right: if a fourth ceremony needs something this shape still cannot express, that
+ * is a signal about `GatedOperation`, not a reason for the caller to opt out of it.
+ *
+ * ## The deep-link envelope carries display continuity only, never authority
+ *
+ * `DatabaseContextEnvelope` (used by `resolveRecoveryDeepLink`) is how a panel preserves "which
+ * restore point was I just looking at" across a navigation — e.g. a link from the database timeline
+ * into recovery. A host must always re-verify `restorePointId` server-side rather than trusting the
+ * envelope's contents as authorization; the envelope existing does not mean the operation it
+ * references is still valid or still permitted for the caller presenting it.
+ */
+import type { AdminRestorePoint, RestorePointCostClass } from './database.js';
+import type { GatedOperation } from '../gated/types.js';
+/** A count that may be unknown rather than a real number — used where computing an exact count
+ *  would be prohibitively expensive for at least one category. */
+export type CategoryCount = number | "unknown";
+/**
+ * What would be lost or affected by restoring to a given point, broken down by category. `partial`
+ * is always `true`: this is a best-effort disclosure, not a guarantee that no other consequence
+ * exists — see `watermarkBaselineAvailable` for one specific case where the disclosure itself is
+ * degraded.
+ */
+export interface AdminDisclosureResult {
+    readonly partial: true;
+    /** `false` means the disclosure could not establish a watermark baseline to diff against — the
+     *  `counts` below may be less trustworthy than usual, and a panel should say so rather than
+     *  present them with the same confidence as a normal disclosure. */
+    readonly watermarkBaselineAvailable: boolean;
+    readonly counts: Readonly<Record<string, CategoryCount>>;
+}
+/** Reasons the recovery feature itself may be degraded right now, independent of any one restore
+ *  point — surfaced by `getRecoveryStatus` so a panel can explain *why* recovery is unavailable
+ *  rather than just failing silently. */
+export type DegradedBannerKind = "migration-interrupted" | "pending-migration" | "operation-in-flight" | "cost-unavailable" | "watermark-baseline-unavailable";
+export type DegradedBannerActionKind = "deep-link-to-database-migration" | "unblock-interrupted-migration" | "none";
+export interface AdminDegradedBanner {
+    readonly kind: DegradedBannerKind;
+    /** Pre-composed, host-owned copy — render as-is rather than deriving text from `kind`, for the
+     *  same reason `GatedPlanResult.warnings` is rendered as-is (see `../gated/types.ts`). */
+    readonly accessibleText: string;
+    readonly actionKind: DegradedBannerActionKind;
+}
+export interface AdminRecoveryStatus {
+    readonly costClass: RestorePointCostClass;
+    readonly banner: AdminDegradedBanner | null;
+}
+/**
+ * An opaque envelope a panel round-trips through a deep link to preserve display continuity across
+ * navigation. Treat every field as informational — see the file header on why `restorePointId`
+ * here is never authoritative.
+ */
+export interface DatabaseContextEnvelope {
+    readonly v: number;
+    readonly correlationId: string;
+    readonly siteId: string;
+    readonly ledgerEventId: string | null;
+    readonly restorePointId: string | null;
+    /** Host-defined description of how far the envelope's view of the world has drifted from
+     *  current reality by the time it is resolved (e.g. `"none"`, `"stale"`). */
+    readonly drift: string;
+    /** What the envelope was created to let the operator do (e.g. `"view"`, `"restore"`). */
+    readonly intent: string;
+    readonly issuedAt: string;
+}
+export interface AdminRecoveryDeepLinkResult {
+    readonly found: boolean;
+    readonly restorePoint: {
+        restorePointId: string;
+        capturedAt: string;
+    } | null;
+}
+/**
+ * What `restore.confirm` takes. The `token` comes from `restore.plan`'s `GatedPlanResult`.
+ *
+ * ## Adapter obligation: `token` is opaque, and a host may have to compose it
+ *
+ * Deliberately one opaque `token`, not the reference host's raw field pair. Its wire protocol
+ * confirms a restore with `{planId, planHash}` — two fields — and its plan step returns them
+ * separately. Exposing that pair here would contradict `GatedPlanResult.token`'s own contract
+ * ("opaque; panels must not parse or construct these"): a panel assembling `planId` + `planHash`
+ * into a confirm call *is* reconstructing the token, which is the thing that contract forbids.
+ *
+ * So the composition is the **route-factory adapter's** job, not the panel's: encode the host's
+ * plan identity into one string on the way out of `plan`, decode it on the way into `confirm`. A
+ * host whose protocol already uses a single token does nothing. This is the same division of labour
+ * as `settings.ts`'s `value`, where the adapter owns any JSON encoding the wire format needs.
+ *
+ * Whoever writes the reference implementation's adapter: this is a real responsibility with no compiler support. Getting it
+ * wrong surfaces as a confirm that is rejected server-side for a plan the operator can see on
+ * screen — so encode both halves, and fail loudly on a token you cannot decode rather than sending
+ * a partial one.
+ */
+export interface RestoreConfirmInput {
+    readonly token: string;
+    /**
+     * Must be `true` — the operator has seen `computeRecoveryDisclosure`'s result and accepted it.
+     *
+     * A host must **reject** the confirm outright when this is `false`, not merely warn. This field
+     * is the recorded-consent half of the ceremony; treating it as advisory turns the whole gated
+     * protocol back into a confirmation dialog.
+     */
+    readonly disclosureAcknowledged: boolean;
+}
+/** What `restore.execute` takes. `confirmToken` comes from `restore.confirm`'s result. */
+export interface RestoreExecuteInput {
+    readonly confirmToken: string;
+    /** Re-stated so the server can verify the token was confirmed for *this* target. A host must
+     *  re-verify server-side rather than trusting the caller-supplied id. */
+    readonly restorePointId: string;
+}
+/** `restore.execute`'s terminal result. */
+export interface RestoreExecuteResult {
+    readonly restoreRunId: string;
+    /** Host-defined run state (e.g. `"completed"`, `"failed"`). */
+    readonly state: string;
+    readonly databaseTimelineDeepLink?: {
+        v: 1;
+        siteId: string;
+        intent: "view";
+    };
+    /**
+     * `true` when the restore physically swapped the underlying database and the server process
+     * needs an operator-triggered restart to pick it up. Until restarted, the running process may
+     * keep serving pre-restore data from an already-open file handle — a panel should surface this
+     * as a required follow-up action, not a background detail.
+     */
+    readonly restartRequired?: boolean;
+}
+export interface AdminRecoveryPort {
+    /** Same underlying set as `AdminDatabasePort.listDatabaseRestorePoints` — see the file header. */
+    listRecoveryRestorePoints(): Promise<readonly AdminRestorePoint[]>;
+    computeRecoveryDisclosure(restorePointId: string): Promise<AdminDisclosureResult>;
+    /** Resolves a deep-link envelope back into a restore point reference. `found: false` means the
+     *  envelope no longer resolves to anything (e.g. the restore point it named was since purged) —
+     *  not an error, a valid negative result a panel should render distinctly from a thrown error. */
+    resolveRecoveryDeepLink(envelope: DatabaseContextEnvelope): Promise<AdminRecoveryDeepLinkResult>;
+    getRecoveryStatus(): Promise<AdminRecoveryStatus>;
+    /**
+     * The restore ceremony: `restore.plan(restorePointId)` -> `restore.confirm(...)` ->
+     * `restore.execute(...)`. A real `GatedOperation`, so a shared confirmation component can drive
+     * it without knowing it is a restore — see the file header.
+     */
+    readonly restore: GatedOperation<string, unknown, RestoreExecuteResult, RestoreConfirmInput, RestoreExecuteInput>;
+}
+//# sourceMappingURL=recovery.d.ts.map

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

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

package/dist/core/ports/recovery.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=recovery.js.map

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

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