@jini-ai/admin 0.1.0

package/dist/core/ports/analytics.js

@@ -0,0 +1,14 @@
+/**
+ * @file `AdminAnalyticsPort` — a rolling window of recent traffic hits, for a live-ish activity
+ * view rather than aggregate reporting.
+ *
+ * Deliberately the thinnest port in the set (one method, no mutation, no pagination cursor). The
+ * reference implementation's route returns a bounded recent-hits list, not a queryable analytics store — there is no
+ * date-range filter, no aggregation, and no historical query on the contract because the reference
+ * implementation has none of those either. A host that needs real analytics reporting (rollups,
+ * date ranges, funnels, ...) needs a different, dedicated port; stretching this one to cover that
+ * by adding options over time would blur "recent activity feed" into "analytics platform", which
+ * is a materially different feature with different performance and retention expectations.
+ */
+export {};
+//# sourceMappingURL=analytics.js.map

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

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

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

@@ -0,0 +1,49 @@
+/**
+ * @file `AdminAuthPort` — the operator session lifecycle: sign in, sign out, and "who am I".
+ *
+ * Deliberately the smallest port in the set (3 methods) and deliberately separate from
+ * `AdminIdentityPort`. The reference implementation's own API client keeps two different "user" shapes for exactly this
+ * split: a minimal `{ id, username }` returned by `login`/`me`, and a much richer
+ * `AdminIdentityUser` (principal id, status, role/policy ids, ...) returned by the identity CRUD
+ * routes. That is not an oversight to unify — a session only ever needs to answer "who is this and
+ * what can they see", while identity administration needs the full principal record. Collapsing
+ * them would force every `me()` caller to depend on identity-administration fields it doesn't use.
+ *
+ * ## No error-code enum
+ *
+ * Expect a rejection from `login` for invalid credentials, and treat any other 4xx as an opaque
+ * authentication failure — the exact `code` vocabulary belongs to the host. See
+ * `../transport/errors.ts`'s header for why a shared code->message table is a regression.
+ */
+/** The minimal principal shape a session carries — see the file header for why this is not
+ *  `AdminIdentityUser`. */
+export interface AdminAuthUser {
+    readonly id: string;
+    readonly username: string;
+}
+export interface AdminAuthPort {
+    /** Expect an authentication-class rejection (invalid credentials, disabled account) rather than
+     *  a specific code — see the file header. */
+    login(input: {
+        username: string;
+        password: string;
+    }): Promise<{
+        user: AdminAuthUser;
+    }>;
+    logout(): Promise<{
+        ok: boolean;
+    }>;
+    /**
+     * The current session's principal, plus (when the host computes it) the permission strings
+     * effective for that principal right now. `effectivePermissions` is an affordance list for
+     * driving UI visibility — see `../permissions/rules.ts`'s `hasPermission`, which is intentionally
+     * not an authorization boundary. A host that has not computed this yet may omit the field
+     * entirely rather than send an empty array; callers should not treat "absent" and "empty" as the
+     * same thing.
+     */
+    me(): Promise<{
+        user: AdminAuthUser;
+        effectivePermissions?: readonly string[];
+    }>;
+}
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/core/ports/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;2BAC2B;AAC3B,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B;iDAC6C;IAC7C,KAAK,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,aAAa,CAAA;KAAE,CAAC,CAAC;IACvF,MAAM,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACnC;;;;;;;OAOG;IACH,EAAE,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CAClF"}

package/dist/core/ports/auth.js

@@ -0,0 +1,19 @@
+/**
+ * @file `AdminAuthPort` — the operator session lifecycle: sign in, sign out, and "who am I".
+ *
+ * Deliberately the smallest port in the set (3 methods) and deliberately separate from
+ * `AdminIdentityPort`. The reference implementation's own API client keeps two different "user" shapes for exactly this
+ * split: a minimal `{ id, username }` returned by `login`/`me`, and a much richer
+ * `AdminIdentityUser` (principal id, status, role/policy ids, ...) returned by the identity CRUD
+ * routes. That is not an oversight to unify — a session only ever needs to answer "who is this and
+ * what can they see", while identity administration needs the full principal record. Collapsing
+ * them would force every `me()` caller to depend on identity-administration fields it doesn't use.
+ *
+ * ## No error-code enum
+ *
+ * Expect a rejection from `login` for invalid credentials, and treat any other 4xx as an opaque
+ * authentication failure — the exact `code` vocabulary belongs to the host. See
+ * `../transport/errors.ts`'s header for why a shared code->message table is a regression.
+ */
+export {};
+//# sourceMappingURL=auth.js.map

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

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

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

@@ -0,0 +1,90 @@
+/**
+ * @file `AdminCommentsPort` — the moderation queue for visitor-submitted comments, plus the
+ * site-wide comments configuration.
+ *
+ * ## `moderateComment`/`purgeComment` resolve to `void`
+ *
+ * The reference implementation's moderation routes answer `204 No Content` on success — there is no updated
+ * comment in the response body to return. A panel must re-fetch (or optimistically patch its own
+ * local copy of) `listCommentsQueue` to see the new state; do not assume this port hands back the
+ * post-moderation row. On a version conflict, expect a conflict-class rejection whose error body
+ * carries `currentVersion` (see `../transport/errors.ts`'s "`body` is kept raw" decision) so a
+ * panel can refresh and retry without a second round-trip just to learn the current value.
+ *
+ * ## `purgeComment` has no `expectedVersion` and a different permission than moderation actions
+ *
+ * The four moderation actions (`approve`/`spam`/`trash`/`restore`, expressed here as
+ * `CommentModerationAction`) are all optimistic-concurrency-guarded and share one moderation
+ * permission. `purge` is a separate, narrower-permissioned, ungated hard delete — mirroring the
+ * same "ordinary action vs `.force`-suffixed destructive action" split documented on
+ * `AdminMediaPort.deleteMedia`. Do not fold `purge` into `CommentModerationAction`; it is
+ * deliberately not one of the four.
+ */
+export type CommentStatus = "pending" | "approved" | "spam" | "trash";
+/** A comment as it appears in the moderation queue. */
+export interface AdminComment {
+    readonly id: string;
+    readonly entryId: string;
+    /** Null for a top-level comment. */
+    readonly parentId: string | null;
+    /** The top-level ancestor of this comment's thread — same value as `id` for a top-level
+     *  comment itself. */
+    readonly threadRootId: string;
+    readonly depth: number;
+    readonly status: CommentStatus;
+    /** Set when the author was a signed-in member; null for an anonymous/guest comment. */
+    readonly authorPrincipalId: string | null;
+    readonly authorName: string;
+    readonly authorEmail: string | null;
+    readonly authorUrl: string | null;
+    /** A hash, never the raw IP — this port never carries an operator-identifiable raw address. */
+    readonly authorIpHash: string | null;
+    readonly bodyText: string;
+    /** Null when no spam classifier ran (e.g. moderation was manual-only for this comment). */
+    readonly spamScore: number | null;
+    readonly spamProvider: string | null;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    /** Optimistic-concurrency version — required as `expectedVersion` on every moderation action;
+     *  not required by `purgeComment` (see the file header). */
+    readonly version: number;
+}
+/** A keyset-paginated page of the moderation queue. */
+export interface AdminCommentsQueuePage {
+    readonly items: readonly AdminComment[];
+    readonly nextCursor: string | null;
+}
+export interface CommentsSettings {
+    readonly enabled: boolean;
+    readonly requireModeration: boolean;
+    readonly maxDepth: number;
+    /** `null` means comments never auto-close by age. A host's own "never" sentinel, if it has one
+     *  internally, should never be sent to or expected from this port directly — always `null`. */
+    readonly closeAfterDays: number | null;
+    readonly spamAutoRejectScore: number;
+    readonly maxPerIpPerHour: number;
+}
+/** The four real per-comment moderation actions — see the file header for why `purge` is not a
+ *  fifth member of this union. */
+export type CommentModerationAction = "approve" | "spam" | "trash" | "restore";
+export interface AdminCommentsPort {
+    listCommentsQueue(options?: {
+        status?: CommentStatus;
+        cursor?: string;
+        limit?: number;
+    }): Promise<AdminCommentsQueuePage>;
+    /** See the file header: resolves to `void` even on success. */
+    moderateComment(commentId: string, input: {
+        action: CommentModerationAction;
+        expectedVersion: number;
+    }, options?: {
+        note?: string;
+    }): Promise<void>;
+    /** Hard delete, no version guard, separate permission — see the file header. */
+    purgeComment(commentId: string, options?: {
+        note?: string;
+    }): Promise<void>;
+    getCommentsSettings(): Promise<CommentsSettings>;
+    putCommentsSettings(patch?: Partial<CommentsSettings>): Promise<CommentsSettings>;
+}
+//# sourceMappingURL=comments.d.ts.map

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

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

package/dist/core/ports/comments.js

@@ -0,0 +1,24 @@
+/**
+ * @file `AdminCommentsPort` — the moderation queue for visitor-submitted comments, plus the
+ * site-wide comments configuration.
+ *
+ * ## `moderateComment`/`purgeComment` resolve to `void`
+ *
+ * The reference implementation's moderation routes answer `204 No Content` on success — there is no updated
+ * comment in the response body to return. A panel must re-fetch (or optimistically patch its own
+ * local copy of) `listCommentsQueue` to see the new state; do not assume this port hands back the
+ * post-moderation row. On a version conflict, expect a conflict-class rejection whose error body
+ * carries `currentVersion` (see `../transport/errors.ts`'s "`body` is kept raw" decision) so a
+ * panel can refresh and retry without a second round-trip just to learn the current value.
+ *
+ * ## `purgeComment` has no `expectedVersion` and a different permission than moderation actions
+ *
+ * The four moderation actions (`approve`/`spam`/`trash`/`restore`, expressed here as
+ * `CommentModerationAction`) are all optimistic-concurrency-guarded and share one moderation
+ * permission. `purge` is a separate, narrower-permissioned, ungated hard delete — mirroring the
+ * same "ordinary action vs `.force`-suffixed destructive action" split documented on
+ * `AdminMediaPort.deleteMedia`. Do not fold `purge` into `CommentModerationAction`; it is
+ * deliberately not one of the four.
+ */
+export {};
+//# sourceMappingURL=comments.js.map

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

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

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

@@ -0,0 +1,101 @@
+/**
+ * @file `AdminDatabasePort` — the append-only operations ledger, on-demand restore points, and the
+ * forward-migration ceremony.
+ *
+ * ## Restore points are shared with `AdminRecoveryPort`; the ledger and migration are not
+ *
+ * `AdminRestorePoint` is the same entity `AdminRecoveryPort.listRecoveryRestorePoints` lists —
+ * Database and Recovery are two different *views* onto one persisted set (Database lets an
+ * operator create one on demand and see it in the timeline; Recovery lets them restore to one).
+ * This port owns the type since `createDatabaseRestorePoint` is where a restore point actually
+ * comes into being; `recovery.ts` imports it rather than redeclaring it.
+ *
+ * ## `migrateForward` satisfies `GatedOperation`; see `recovery.ts` for the triad that doesn't
+ *
+ * The reference implementation's `planMigrateForward` takes no input and `executeMigrateForward` takes only the
+ * confirmation token — no operation-specific extra fields on any of the three calls. That means
+ * this triad is a clean, direct instance of `../gated/types.js`'s `GatedOperation`, unlike
+ * Recovery's restore ceremony (see that file's header for why restore is different). A
+ * compile-time assertion of that fact lives in `../__tests__/database-gated.test.ts`.
+ */
+import type { GatedConfirmResult, GatedOperation, GatedPlanResult } from '../gated/types.js';
+/** One row in the operations ledger — an append-only record of what happened and when, not an
+ *  editable entity. */
+export interface AdminLedgerRow {
+    readonly id: string;
+    /** Host-defined event kind (e.g. `"migration"`, `"restore"`, `"restore-point-created"`) — not
+     *  enumerated here; see `../transport/errors.ts`'s header for the same reasoning applied to error
+     *  codes instead of ledger kinds. */
+    readonly kind: string;
+    readonly createdAt: string;
+    /** The restore point this event produced or consumed, if any. */
+    readonly restorePointId: string | null;
+    /** Host-defined outcome string (e.g. `"success"`, `"failed"`, `"interrupted"`). */
+    readonly outcome: string;
+}
+/**
+ * Whether capturing or restoring to a given point is cheap, expensive, or currently impossible.
+ * A host surfaces this so a panel can warn an operator before they trigger a costly capture
+ * rather than after.
+ */
+export type RestorePointCostClass = "cheap" | "expensive" | "unavailable";
+/** A persisted restore point — the entity `AdminDatabasePort` and `AdminRecoveryPort` share. */
+export interface AdminRestorePoint {
+    readonly id: string;
+    /** What caused this point to be captured (e.g. `"manual"`, `"pre-migration"`) — host-defined. */
+    readonly trigger: string;
+    readonly costClass: string;
+    readonly kind: string;
+    /** Null when the host has no watermark concept or none was available at capture time. */
+    readonly watermarkAtCapture: number | null;
+    readonly createdAt: string;
+}
+/** The trimmed shape `createDatabaseRestorePoint` returns — a summary, not the full row, since the
+ *  caller just created it and mainly needs to know it succeeded and how expensive it was. */
+export interface AdminRestorePointSummary {
+    readonly id: string;
+    readonly costClass: RestorePointCostClass;
+    readonly kind: string;
+}
+/** `migrateForward`'s terminal success shape. Literal `true` rather than `boolean`: there is no
+ *  "migrated: false" response — a non-migration outcome is a rejection, not a `false` payload. */
+export interface MigrateForwardResult {
+    readonly migrated: true;
+}
+export interface AdminDatabasePort {
+    /**
+     * A page of the operations ledger, newest-relevant-first, optionally filtered by `kind` and
+     * `outcome` and bounded by `fromDate`/`toDate`. Keyset-paginated via `cursor`/`nextCursor`, not
+     * offset-paginated — do not compute a page number from `limit`.
+     */
+    getDatabaseTimeline(options?: {
+        kind?: string;
+        outcome?: string;
+        fromDate?: string;
+        toDate?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        items: readonly AdminLedgerRow[];
+        nextCursor: string | null;
+    }>;
+    listDatabaseRestorePoints(): Promise<readonly AdminRestorePoint[]>;
+    /**
+     * Captures a new restore point on demand. `costAck` should be `true` once the operator has
+     * acknowledged a shown cost warning for a `RestorePointCostClass` of `"expensive"` — a host may
+     * reject the call without it rather than silently proceeding.
+     */
+    createDatabaseRestorePoint(options?: {
+        trigger?: string;
+        costAck?: boolean;
+    }): Promise<AdminRestorePointSummary>;
+    /**
+     * The forward-migration ceremony (schema/data migration to the host's current expected state),
+     * as a `GatedOperation` — see the file header for why this triad, unlike Recovery's restore, fits
+     * the generic shape directly. `plan` takes no meaningful input beyond the ceremony trigger; the
+     * plan is computed entirely from the site's current migration state server-side.
+     */
+    readonly migrateForward: GatedOperation<void, unknown, MigrateForwardResult>;
+}
+export type { GatedConfirmResult, GatedOperation, GatedPlanResult };
+//# sourceMappingURL=database.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../src/core/ports/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE7F;uBACuB;AACvB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;yCAEqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,WAAW,GAAG,aAAa,CAAC;AAE1E,gGAAgG;AAChG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yFAAyF;IACzF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;6FAC6F;AAC7F,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;kGACkG;AAClG,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,mBAAmB,CAAC,OAAO,CAAC,EAAE;QAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IAC7E,yBAAyB,IAAI,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAAC;IACnE;;;;OAIG;IACH,0BAA0B,CAAC,OAAO,CAAC,EAAE;QACnC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,oBAAoB,CAAC,CAAC;CAC9E;AAID,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC"}

package/dist/core/ports/database.js

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

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

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

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

@@ -0,0 +1,130 @@
+/**
+ * @file `AdminFormsPort` — form definitions (the schema an operator builds) and their submissions
+ * (the data visitors send in).
+ *
+ * ## Form DEFINITIONS have no delete, structurally — only `status`
+ *
+ * Mirrors `AdminIdentityPort.disableUser`'s reasoning exactly (see that file's header): the
+ * reference implementation's `FormDefinitionRepoPort` has no delete method AT ALL — not gated behind a permission, not a
+ * two-rung ladder, structurally absent — because a definition is meant to stay resolvable for
+ * historical submissions. The only lifecycle move is `active` ⇄ `disabled` via
+ * `updateFormDefinition`'s `status` field. There is deliberately no `deleteFormDefinition` on this
+ * port; a reference implementation has nothing to call.
+ *
+ * ## `updateFormDefinition`'s `fields` patch can add or edit, never remove
+ *
+ * When `patch.fields` is supplied it replaces the whole array, but the reference implementation's write chokepoint rejects
+ * (validation-class) any replacement that omits a field `id` present in the current definition —
+ * existing fields can be reordered or edited in place, and new ones appended, but never dropped
+ * through this call. There is no separate "remove a field" operation on the reference
+ * implementation.
+ *
+ * ## No `slug` in the update patch — and the rule this follows
+ *
+ * A definition's `slug` is immutable after creation. The reference implementation's write-service silently ignores a
+ * `slug` sent in an update patch rather than rejecting it (a documented, deliberate choice on their
+ * side) — sent, accepted, and dropped with no error and no effect.
+ *
+ * This port set applies one rule to that entire family of cases, wherever a reference
+ * implementation treats a well-formed, in-contract input specially:
+ *
+ * - **A silently-ignored input is removed from the contract.** If sending it produces no error and
+ *   no effect, keeping it as a field would make the type lie about having an effect it doesn't
+ *   have — which is the exact failure mode these ports exist to prevent. `AdminFormUpdatePatch` has
+ *   no `slug` for this reason; there is nothing to silently drop because there is nothing to send.
+ * - **A loudly-rejected input stays in the contract and gets documented.** If sending it produces a
+ *   real, typed rejection, the caller learns the truth at runtime — and because the surrounding
+ *   union is OPEN, a different host may legitimately accept what the reference implementation
+ *   refuses. That is a host-capability limit, not a contract lie, so removing the value would
+ *   throw away real information. See `redirects.ts`'s file header for the concrete case
+ *   (`matchType: "regex"`, kept and documented, never silently dropped).
+ *
+ * Applied elsewhere in this file: `updateFormDefinition`'s field-removal constraint (below) is a
+ * loud rejection (`FormFieldValidationError`), so `fields` stays on `AdminFormUpdatePatch` with the
+ * constraint documented, rather than being narrowed to a shape that can't express a removal
+ * attempt at all.
+ *
+ * ## Submissions are the one place with a real hard delete
+ *
+ * Unlike definitions, `FormSubmissionRepoPort` does expose a permanent delete — the reference repo
+ * port's own doc comment calls this out as "the one asymmetry." `deleteFormSubmission` is
+ * genuinely irreversible; do not offer it with "undo" affordances.
+ *
+ * ## Open vs. closed unions
+ *
+ * `FormFieldType` and `FormDefinitionStatus` are reference-implementation-specific vocabularies — OPEN, via the
+ * `T | (string & {})` idiom `seo.ts`'s file header introduces for this port set. `FormFieldType` in
+ * particular is a small, deliberately-not-yet-exhaustive set on the reference implementation (four
+ * field kinds today); a host offering a richer form builder needs room to add its own without this
+ * contract standing in the way.
+ */
+/** A form field's input kind — open, see file header. */
+export type FormFieldType = "text" | "email" | "textarea" | "checkbox" | (string & {});
+/** Lifecycle of a form definition — open, see file header. There is no "deleted" state; see the
+ *  file header on why this port has no delete for definitions at all. */
+export type FormDefinitionStatus = "active" | "disabled" | (string & {});
+export interface AdminFormField {
+    readonly id: string;
+    readonly label: string;
+    readonly type: FormFieldType;
+    readonly required: boolean;
+    readonly maxLength?: number | null;
+}
+export interface AdminFormNotifyConfig {
+    readonly enabled: boolean;
+    readonly recipients: readonly string[];
+}
+export interface AdminFormDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string;
+    readonly fields: readonly AdminFormField[];
+    readonly notify: AdminFormNotifyConfig;
+    readonly status: FormDefinitionStatus;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface AdminFormSubmission {
+    readonly id: string;
+    readonly formDefinitionId: string;
+    /** Keyed by the definition's field ids at submission time. */
+    readonly data: Readonly<Record<string, string | boolean>>;
+    readonly sourceIp: string;
+    readonly submittedAt: string;
+}
+/** A keyset-paginated page of submissions, newest-first. */
+export interface AdminFormSubmissionPage {
+    readonly items: readonly AdminFormSubmission[];
+    readonly nextCursor: string | null;
+}
+export interface AdminFormCreateInput {
+    readonly name: string;
+    readonly slug: string;
+    readonly fields: readonly AdminFormField[];
+    readonly notify?: AdminFormNotifyConfig;
+}
+/** No `slug` — see file header. */
+export interface AdminFormUpdatePatch {
+    readonly name?: string;
+    /** Whole-array replace with an add/edit-only constraint — see file header. */
+    readonly fields?: readonly AdminFormField[];
+    readonly notify?: AdminFormNotifyConfig;
+    readonly status?: FormDefinitionStatus;
+}
+export interface AdminFormsPort {
+    listFormDefinitions(): Promise<readonly AdminFormDefinition[]>;
+    getFormDefinition(id: string): Promise<AdminFormDefinition>;
+    createFormDefinition(input: AdminFormCreateInput): Promise<AdminFormDefinition>;
+    /** See file header: `patch.fields`, when supplied, may add or edit but never omit an existing
+     *  field id. */
+    updateFormDefinition(id: string, patch: AdminFormUpdatePatch): Promise<AdminFormDefinition>;
+    listFormSubmissions(formId: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<AdminFormSubmissionPage>;
+    getFormSubmission(formId: string, submissionId: string): Promise<AdminFormSubmission>;
+    /** Permanent delete — the one hard delete in this port. See file header on why form
+     *  DEFINITIONS have no equivalent. */
+    deleteFormSubmission(formId: string, submissionId: string): Promise<void>;
+}
+//# sourceMappingURL=forms.d.ts.map

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

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

package/dist/core/ports/forms.js

@@ -0,0 +1,62 @@
+/**
+ * @file `AdminFormsPort` — form definitions (the schema an operator builds) and their submissions
+ * (the data visitors send in).
+ *
+ * ## Form DEFINITIONS have no delete, structurally — only `status`
+ *
+ * Mirrors `AdminIdentityPort.disableUser`'s reasoning exactly (see that file's header): the
+ * reference implementation's `FormDefinitionRepoPort` has no delete method AT ALL — not gated behind a permission, not a
+ * two-rung ladder, structurally absent — because a definition is meant to stay resolvable for
+ * historical submissions. The only lifecycle move is `active` ⇄ `disabled` via
+ * `updateFormDefinition`'s `status` field. There is deliberately no `deleteFormDefinition` on this
+ * port; a reference implementation has nothing to call.
+ *
+ * ## `updateFormDefinition`'s `fields` patch can add or edit, never remove
+ *
+ * When `patch.fields` is supplied it replaces the whole array, but the reference implementation's write chokepoint rejects
+ * (validation-class) any replacement that omits a field `id` present in the current definition —
+ * existing fields can be reordered or edited in place, and new ones appended, but never dropped
+ * through this call. There is no separate "remove a field" operation on the reference
+ * implementation.
+ *
+ * ## No `slug` in the update patch — and the rule this follows
+ *
+ * A definition's `slug` is immutable after creation. The reference implementation's write-service silently ignores a
+ * `slug` sent in an update patch rather than rejecting it (a documented, deliberate choice on their
+ * side) — sent, accepted, and dropped with no error and no effect.
+ *
+ * This port set applies one rule to that entire family of cases, wherever a reference
+ * implementation treats a well-formed, in-contract input specially:
+ *
+ * - **A silently-ignored input is removed from the contract.** If sending it produces no error and
+ *   no effect, keeping it as a field would make the type lie about having an effect it doesn't
+ *   have — which is the exact failure mode these ports exist to prevent. `AdminFormUpdatePatch` has
+ *   no `slug` for this reason; there is nothing to silently drop because there is nothing to send.
+ * - **A loudly-rejected input stays in the contract and gets documented.** If sending it produces a
+ *   real, typed rejection, the caller learns the truth at runtime — and because the surrounding
+ *   union is OPEN, a different host may legitimately accept what the reference implementation
+ *   refuses. That is a host-capability limit, not a contract lie, so removing the value would
+ *   throw away real information. See `redirects.ts`'s file header for the concrete case
+ *   (`matchType: "regex"`, kept and documented, never silently dropped).
+ *
+ * Applied elsewhere in this file: `updateFormDefinition`'s field-removal constraint (below) is a
+ * loud rejection (`FormFieldValidationError`), so `fields` stays on `AdminFormUpdatePatch` with the
+ * constraint documented, rather than being narrowed to a shape that can't express a removal
+ * attempt at all.
+ *
+ * ## Submissions are the one place with a real hard delete
+ *
+ * Unlike definitions, `FormSubmissionRepoPort` does expose a permanent delete — the reference repo
+ * port's own doc comment calls this out as "the one asymmetry." `deleteFormSubmission` is
+ * genuinely irreversible; do not offer it with "undo" affordances.
+ *
+ * ## Open vs. closed unions
+ *
+ * `FormFieldType` and `FormDefinitionStatus` are reference-implementation-specific vocabularies — OPEN, via the
+ * `T | (string & {})` idiom `seo.ts`'s file header introduces for this port set. `FormFieldType` in
+ * particular is a small, deliberately-not-yet-exhaustive set on the reference implementation (four
+ * field kinds today); a host offering a richer form builder needs room to add its own without this
+ * contract standing in the way.
+ */
+export {};
+//# sourceMappingURL=forms.js.map

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

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