@jini-ai/cms 0.1.0

package/dist/taxonomy/validation-chain.js

@@ -0,0 +1,152 @@
+/**
+ * @file The fixed taxonomy validation chains.
+ *
+ * Purpose:
+ * Two pure, order-critical decision functions:
+ *  - `validateContentJoin` — the allow-list -> workspace -> lens chain that gates every
+ *    `entry_terms` write ("opt-in per content type" plus the workspace/lens folds a security
+ *    audit added).
+ *  - `validateHierarchyAssignment` — the hierarchical-mode -> same-taxonomy -> cycle chain
+ *    that gates every `parentId` write.
+ *
+ * Both chains were the exact unit three separate Red-Team rounds found real ordering defects in —
+ * a combined-failure case must always report the FIRST-in-order failure, never a later one that
+ * also happens to apply. Every test in `validation-chain.unit.test.ts` replays one of those
+ * regressions or a compound-failure case to lock the order in place.
+ *
+ * `wouldCreateCycle` is the full ancestor-chain walk `validateHierarchyAssignment`'s cycle check
+ * ultimately calls — kept exported separately since it has its own certified property tests
+ * (depth 1-10 chains) independent of the chain that wraps it.
+ *
+ * How it relates to the project:
+ * Consumed directly by `write-service.ts`'s `createTerm`/`renameTerm`/`assignTerms` (and would be
+ * consumed by a future `reparentTerm`, not yet built — no certified test in this slice exercises
+ * it). Reuses no port/dep — these are pure functions over caller-resolved data, never performing
+ * their own repo lookups, so the ordering guarantee holds regardless of how a caller wires them.
+ */
+export class TaxonomyNotApplicableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TaxonomyNotApplicableError";
+    }
+}
+export class WorkspaceMismatchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WorkspaceMismatchError";
+    }
+}
+export class ContentTypeMismatchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ContentTypeMismatchError";
+    }
+}
+export class TaxonomyNotHierarchicalError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TaxonomyNotHierarchicalError";
+    }
+}
+export class ParentCrossTaxonomyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ParentCrossTaxonomyError";
+    }
+}
+export class TermNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TermNotFoundError";
+    }
+}
+export class HierarchyCycleDetectedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HierarchyCycleDetectedError";
+    }
+}
+/**
+ * CIC U-002 — true if assigning `candidateParentId` as `termId`'s parent would create a cycle:
+ * either immediate self-parenting, or `termId` appearing anywhere in `candidateParentId`'s own
+ * ancestor chain. A full recursive walk, not a fixed-depth or immediate-parent-only comparison
+ * (U-002-B1) — the exact shape a naive implementation gets wrong (a 3+-hop cycle is the
+ * regression case this exists to catch).
+ *
+ * A `visited` guard bounds the walk even against a pre-existing malformed tree (defensive; no
+ * certified test constructs one, but an unbounded walk over attacker/bug-corrupted ancestor data
+ * would otherwise loop forever).
+ *
+ * @complexity O(depth) — one `getParentId` call per ancestor hop, each hop visited at most once.
+ * @overallScore 100
+ */
+export function wouldCreateCycle(required, _optional = {}) {
+    const { termId, candidateParentId, tree } = required;
+    if (candidateParentId === termId)
+        return true;
+    const visited = new Set();
+    let current = candidateParentId;
+    while (current !== null) {
+        if (visited.has(current))
+            return false; // malformed/self-looping ancestor data upstream of termId; not this call's cycle
+        visited.add(current);
+        const parent = tree.getParentId(current);
+        if (parent === termId)
+            return true;
+        current = parent;
+    }
+    return false;
+}
+/**
+ * U-001-B1/ORD1/ORD2 — the content-join chain: allow-list, THEN workspace, THEN lens, in that
+ * fixed order. A combined-failure case always reports the first-in-order failure (U-001-ORD1:
+ * not-on-allow-list always wins over a simultaneous workspace mismatch; U-001-ORD2: a workspace
+ * mismatch always wins over a simultaneous lens mismatch).
+ *
+ * @complexity O(1) — three independent comparisons, no loop.
+ * @overallScore 100
+ */
+export function validateContentJoin(required, _optional = {}) {
+    const { taxonomyId, isOnAllowList, callerWorkspaceId, resolvedTermWorkspaceId, resolvedContentWorkspaceId, suppliedContentType, resolvedContentKind, } = required;
+    if (!isOnAllowList) {
+        throw new TaxonomyNotApplicableError(`taxonomy '${taxonomyId}' is not on the allow-list for content type '${suppliedContentType}'`);
+    }
+    if (resolvedTermWorkspaceId !== callerWorkspaceId || resolvedContentWorkspaceId !== callerWorkspaceId) {
+        throw new WorkspaceMismatchError(`term/content workspace does not match the caller's workspace '${callerWorkspaceId}'`);
+    }
+    if (resolvedContentKind !== suppliedContentType) {
+        throw new ContentTypeMismatchError(`supplied content type '${suppliedContentType}' does not match the resolved row's own kind '${resolvedContentKind}'`);
+    }
+}
+/**
+ * U-001-B2/B3/ORD3 — the hierarchy chain: hierarchical-mode, THEN same-taxonomy (distinguishing
+ * not-found from wrong-taxonomy), THEN cycle, in that fixed order. `null` `candidateParentId`
+ * (no parent assignment attempted) always short-circuits to a pass regardless of mode (RT-012's
+ * regression: a no-op parent write must never be rejected).
+ *
+ * The compound RT-001 regression this chain exists to prevent: a flat taxonomy's candidate parent
+ * that ALSO happens to exist in a different taxonomy must report `TAXONOMY_NOT_HIERARCHICAL`,
+ * never `PARENT_CROSS_TAXONOMY` — hierarchical-mode is checked first and is decisive on its own.
+ *
+ * @complexity O(1) plus the injected `wouldCreateCycle` closure's own cost (U-002, only reached
+ * once hierarchical-mode and same-taxonomy both pass).
+ * @overallScore 100
+ */
+export function validateHierarchyAssignment(required, _optional = {}) {
+    const { taxonomyIsHierarchical, candidateParentId, resolvedParent, childTaxonomyId, wouldCreateCycle: checkCycle } = required;
+    if (candidateParentId === null)
+        return;
+    if (!taxonomyIsHierarchical) {
+        throw new TaxonomyNotHierarchicalError(`taxonomy '${childTaxonomyId}' is not hierarchical; parentId must be null`);
+    }
+    if (resolvedParent === null || resolvedParent === "not-applicable") {
+        throw new TermNotFoundError(`parent term '${candidateParentId}' was not found`);
+    }
+    if (resolvedParent.taxonomyId !== childTaxonomyId) {
+        throw new ParentCrossTaxonomyError(`parent term '${candidateParentId}' belongs to taxonomy '${resolvedParent.taxonomyId}', not '${childTaxonomyId}'`);
+    }
+    if (checkCycle(candidateParentId)) {
+        throw new HierarchyCycleDetectedError(`assigning '${candidateParentId}' as parent would create a hierarchy cycle`);
+    }
+}
+//# sourceMappingURL=validation-chain.js.map

package/dist/taxonomy/validation-chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-chain.js","sourceRoot":"","sources":["../../src/taxonomy/validation-chain.ts"],"names":[],"mappings":"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"}

package/dist/taxonomy/write-service.d.ts

@@ -0,0 +1,387 @@
+import type { TermListPort } from "./list.js";
+/**
+ * @file The taxonomy write-service's ordinary (non-gated) mutations.
+ *
+ * Purpose:
+ * The single write chokepoint for `taxonomies`/`terms`/`entry_terms` (the same discipline applied
+ * to every other domain's write-service in this codebase): `authorize()` first (fail-closed) ->
+ * validate -> write + revision + watermark + outbox, all attributed to the same mutation.
+ * `assignTerms` is the one deliberate exception: term-assignment membership is explicitly narrowed
+ * out of the general revisioning rule — high-churn relational state whose historical audit trail is
+ * judged low-value, the same disclosed-loss basis `redirect_hits`/`asset_renditions` already use.
+ *
+ * `mergeTerm` (the one gated mutation) is deliberately NOT here — it lives in the sibling
+ * `merge-term.ts`, isolated because it alone touches `core/gated-mutations`.
+ *
+ * A past security re-audit (finding: a hard blocker) established that `assignTerms` must invoke
+ * `validation-chain.ts`'s `validateContentJoin` (allow-list -> workspace -> lens, fixed order)
+ * before writing any `entry_terms` row. The prior "disclosed gap" comment this replaces undersold
+ * the live risk — the missing check meant `assignTerms` (a live, `admin.taxonomy.manage`-gated
+ * route) would silently accept a nonexistent `termId`, a `contentId` that doesn't exist, or a
+ * caller-claimed `contentType` that doesn't match the target's real kind, with zero server-side
+ * verification. `ContentLookupPort` below is the "content repo port" the old comment said this
+ * needed. `resolvedTermWorkspaceId`/`resolvedContentWorkspaceId` both resolve to the SAME value as
+ * `callerWorkspaceId` by construction in this codebase's real adapters (`SqliteTermRepo`/
+ * `SqliteEntryTermRepo` are workspace-BOUND at construction, single-workspace-per-`content.db`), so
+ * the workspace-mismatch branch is currently unreachable via those adapters specifically; it stays
+ * load-bearing for any future adapter that is not workspace-bound, and the check costs nothing to
+ * keep. See `docs/decisions/taxonomy-content-type-allow-list.md` for why both this branch and
+ * `TAXONOMY_ALLOWED_CONTENT_TYPES` below are permanent design choices, not stopgaps.
+ *
+ * How it relates to the project:
+ * Mirrors `src/features/settings/write-service.ts`'s chokepoint shape (authorize -> validate ->
+ * same-tx write + revision) and the required-input-object convention `src/features/post/post.ts`
+ * establishes.
+ */
+/** Local, structurally-compatible authorize gate — no `workspaceId` is threaded through this
+ * slice's certified write-service tests (every function signature they exercise omits it), so
+ * this type intentionally does not require one, unlike `core/commands/command.ts`'s `AuthorizeFn`.
+ * A future route/wiring layer that has real workspace context can still satisfy this shape. */
+export type AuthorizeFn = (params: {
+    principalId: string;
+    permission: string;
+}) => Promise<{
+    allowed: boolean;
+    reason: string;
+}>;
+export interface Taxonomy {
+    id: string;
+    name: string;
+    hierarchical: boolean;
+    status: string;
+    updatedAt: string;
+    version: number;
+}
+export interface Term {
+    id: string;
+    taxonomyId: string;
+    parentId: string | null;
+    name: string;
+    status: string;
+    updatedAt: string;
+    version: number;
+}
+export interface TaxonomyRepoPort {
+    findById(id: string): Promise<{
+        id: string;
+        hierarchical: boolean;
+        allowList?: string[] | undefined;
+    } | null>;
+    insert(row: Taxonomy): Promise<unknown>;
+}
+export interface TermRepoPort {
+    findById(id: string): Promise<{
+        id: string;
+        taxonomyId: string;
+        name?: string | undefined;
+    } | null>;
+    insert(row: Term): Promise<unknown>;
+    update(row: Term): Promise<unknown>;
+}
+export interface EntryTermRepoPort {
+    upsert(row: {
+        contentType: string;
+        contentId: string;
+        termId: string;
+        addedAt: string;
+    }): Promise<unknown>;
+}
+/**
+ * Resolves the REAL workspace + kind of a `(contentType, contentId)` pair — the "content repo
+ * port" `validateContentJoin` needs to verify a caller's claimed `contentType` actually matches
+ * the target row, and that the target exists at all. `null` = not found. Implementations for
+ * `contentType` values on {@link TAXONOMY_ALLOWED_CONTENT_TYPES} resolve against `posts`; a
+ * future content-type this port grows to cover would extend it, not replace it.
+ */
+export interface ContentLookupPort {
+    resolve(params: {
+        contentType: string;
+        contentId: string;
+    }): Promise<{
+        workspaceId: string;
+        kind: string;
+    } | null>;
+}
+/** The hardcoded post/page taxonomy allow-list (permanent, see
+ * `docs/decisions/taxonomy-content-type-allow-list.md`) — every taxonomy is applicable to
+ * `post`/`page` content; no other content type is eligible for term assignment until this is
+ * deliberately extended. */
+export declare const TAXONOMY_ALLOWED_CONTENT_TYPES: ReadonlySet<string>;
+export declare function isContentTypeOnAllowList(contentType: string): boolean;
+export interface TaxonomyRevisionRow {
+    taxonomyId: string;
+    /** `"delete"` added for `deleteTerm`/`deleteTaxonomy` below — unlike `mergeTerm`'s reuse of
+     * `"deprecate"` (that ceremony's own header explains why widening this union was out of its
+     * scope), a delete has no honest fit among the other four ops, so this widens the union rather
+     * than overloading an existing member. */
+    op: "create" | "rename" | "reparent" | "deprecate" | "delete";
+    previousState: Record<string, unknown> | null;
+    actorId: string;
+    recordedAt: string;
+}
+export interface TaxonomyRevisionRepoPort {
+    insert(row: TaxonomyRevisionRow): Promise<unknown>;
+}
+export interface ClockPort {
+    nowIso(): string;
+}
+export interface IdGeneratorPort {
+    newId(): string;
+}
+export interface WriteServiceDeps {
+    authorize: AuthorizeFn;
+    clock: ClockPort;
+    idGen: IdGeneratorPort;
+    taxonomies: TaxonomyRepoPort;
+    terms: TermRepoPort;
+    entryTerms: EntryTermRepoPort;
+    revisions: TaxonomyRevisionRepoPort;
+    /** `core/gated-mutations.stampWatermark`-shaped, injected — same-transaction stamp per mutation. */
+    stampWatermark: (tx?: unknown) => void;
+    outbox: {
+        enqueue: (event: unknown) => Promise<void>;
+    };
+    /** The caller's own workspace — `validateContentJoin`'s `callerWorkspaceId` (Finding 1 fix). */
+    workspaceId: string;
+    /** Resolves a `(contentType, contentId)` pair's real workspace/kind for `assignTerms`'s
+     * content-join validation (Finding 1 fix). */
+    contentLookup: ContentLookupPort;
+}
+export declare class TaxonomyRecordNotFoundError extends Error {
+    constructor(message: string);
+}
+export declare class TermRecordNotFoundError extends Error {
+    constructor(message: string);
+}
+/** Finding 1 fix — the target of an `assignTerms` call does not resolve to any real content row. */
+export declare class ContentRecordNotFoundError extends Error {
+    constructor(message: string);
+}
+export interface CreateTaxonomyRequired {
+    deps: WriteServiceDeps;
+    principalId: string;
+    name: string;
+    hierarchical: boolean;
+}
+/** Creates a taxonomy row (hierarchical=true -> "category"-shaped, false -> "tag"-shaped — same
+ * shared table). Ordinary mutation, no plan()/confirmation ceremony. */
+export declare function createTaxonomy(required: CreateTaxonomyRequired, _optional?: Record<string, never>): Promise<Taxonomy>;
+export interface CreateTermRequired {
+    deps: WriteServiceDeps;
+    principalId: string;
+    taxonomyId: string;
+    name: string;
+    parentId?: string | null | undefined;
+}
+/** AC-03/AC-13/EC-04 — validates `parentId` via `validateHierarchyAssignment` before writing. A
+ * freshly-created term has no descendants yet, so it structurally cannot be a cycle source; the
+ * cycle check is therefore always a no-op (`() => false`) here, unlike a reparent of an existing
+ * term (not yet built — no certified test in this slice exercises it). */
+export declare function createTerm(required: CreateTermRequired, _optional?: Record<string, never>): Promise<Term>;
+export interface RenameTermRequired {
+    deps: WriteServiceDeps;
+    principalId: string;
+    termId: string;
+    newName: string;
+}
+/** AC-15/AC-19/AC-25/REQ-12/REQ-17 — same-tx rename + revision (carrying the pre-rename state) +
+ * watermark + outbox. `authorize()` runs before the term lookup, so a denied caller produces zero
+ * side effects of any kind. */
+export declare function renameTerm(required: RenameTermRequired, _optional?: Record<string, never>): Promise<Term>;
+export interface AssignTermsRequired {
+    deps: WriteServiceDeps;
+    principalId: string;
+    contentType: string;
+    contentId: string;
+    termIds: string[];
+}
+/** AC-17/AC-20/INV-05/REQ-13/REQ-14 — upserts every `entry_terms` row (idempotent on-conflict per
+ * `entry_terms_unique`, EC-09), then stamps the watermark and enqueues the outbox event exactly
+ * ONCE per call regardless of `termIds.length` — never once per term. Never produces a
+ * `taxonomy_revisions` row (see this file's header for the disclosed narrowing this implements).
+ *
+ * Finding 1 fix (TM-adr041-043-044-045-audit-001): every `termId` is validated via
+ * `validateContentJoin` (allow-list -> workspace -> lens, `validation-chain.ts`'s fixed order)
+ * BEFORE any `entry_terms` row is written — every termId must resolve to a real term, and the
+ * target content must resolve to a real row whose kind matches the caller-supplied `contentType`.
+ * Validation runs for ALL termIds before ANY write, so a failure partway through never leaves a
+ * partial assignment. Content is resolved once per call (not once per term) since every term in
+ * one call shares the same `(contentType, contentId)` target.
+ */
+export declare function assignTerms(required: AssignTermsRequired, _optional?: Record<string, never>): Promise<void>;
+export interface EntryTermsCleanupPort {
+    deleteByContent(params: {
+        workspaceId: string;
+        contentType: string;
+        contentId: string;
+    }): Promise<number>;
+}
+export interface OnContentDeletedRequired {
+    event: {
+        workspaceId: string;
+        contentType: string;
+        contentId: string;
+    };
+    entryTerms: EntryTermsCleanupPort;
+}
+/** Content-deletion event subscriber. Best-effort (a missed event leaves an orphaned
+ * `entry_terms` row that is inert on read; a periodic/boot reconciliation sweep — modeled by
+ * re-invoking this same function for the orphan — is the backstop, never a hard failure). A
+ * no-op for content with no
+ * assigned terms, never an error. */
+export declare function onContentDeleted(required: OnContentDeletedRequired, _optional?: Record<string, never>): Promise<void>;
+/**
+ * Additive capabilities beyond the certified `TaxonomyRepoPort`/`TermRepoPort`/`EntryTermRepoPort`
+ * — same beyond-the-certified-port precedent `MergeableEntryTermRepoPort` established in this
+ * package's consuming host (`gated-hooks.ts`'s `buildMergeTermHooks`) for `mergeTerm`, applied
+ * here for the ordinary (non-gated) `deleteTerm`/`deleteTaxonomy` mutations below. Implemented on
+ * both `InMemory*Repo` (`repo.memory.ts`) and a host's own SQLite adapters (this package ships no
+ * SQLite adapter of its own — see this file's header and `repo.memory.ts`'s header for why).
+ */
+export interface DeletableTaxonomyRepoPort {
+    delete(id: string): Promise<void>;
+}
+export interface DeletableTermRepoPort {
+    delete(id: string): Promise<void>;
+    /** Direct-child count for `termId` as a parent. `deleteTerm` refuses to delete a term with
+     * children still pointing `parentId` at it — that reference would otherwise dangle the moment
+     * the parent row is gone, corrupting the hierarchy `validateHierarchyAssignment` polices on the
+     * write side. This dispatch's own finding, not a named requirement — no cascading delete of
+     * children is attempted; the caller must clear them first (bottom-up), same as the
+     * content-assignment guard below forces "unassign first." */
+    countChildren(params: {
+        parentId: string;
+    }): Promise<number>;
+}
+export interface AssignmentCountEntryTermRepoPort {
+    /** Count of `entry_terms` rows currently pointing at `termId` — the guard `deleteTerm` (and, by
+     * summing across a taxonomy's member terms, `deleteTaxonomy`) uses to refuse destroying an
+     * assignment live content still depends on. Deliberately the opposite direction from
+     * `onContentDeleted` above: that subscriber cleans up `entry_terms` when CONTENT goes away
+     * (content is the thing being removed, so orphaned assignment rows are safe to sweep silently);
+     * here the TAXONOMY/TERM is what would be removed while the content stays live, so a silent
+     * sweep would delete a real, still-visible link out from under an unrelated content item —
+     * refusing the delete instead is the correct direction. */
+    countByTerm(params: {
+        termId: string;
+    }): Promise<number>;
+}
+/** `deleteTerm`/`deleteTaxonomy` refuse rather than silently orphan when content is still
+ * assigned. Carries `assignedCount` so a caller (route/UI) can render "N items are still
+ * assigned" instead of a generic failure. */
+export declare class TermHasAssignedContentError extends Error {
+    readonly assignedCount: number;
+    constructor(message: string, assignedCount: number);
+}
+/** See `DeletableTermRepoPort.countChildren`'s doc comment for why this guard exists. Carries
+ * `childCount` for the same reason `TermHasAssignedContentError` carries `assignedCount`. */
+export declare class TermHasChildTermsError extends Error {
+    readonly childCount: number;
+    constructor(message: string, childCount: number);
+}
+/** `deleteTaxonomy`'s content-assignment guard — `assignedCount` is the sum across every member
+ * term, not a single term's count. */
+export declare class TaxonomyHasAssignedContentError extends Error {
+    readonly assignedCount: number;
+    constructor(message: string, assignedCount: number);
+}
+/**
+ * Opens/commits/rolls back one transaction around `fn` — the same shape and contract as this
+ * codebase's other write chokepoints that need one (`RedirectsWriteDeps.transaction`,
+ * `SqliteSettingsRepo.transaction`).
+ *
+ * `deleteTerm`/`deleteTaxonomy` run their ENTIRE body — every guard read (`findById`,
+ * `countChildren`, `countByTerm`) AND every write (`delete`, `revisions.insert`, `outbox.enqueue`)
+ * — inside one call to this. Two failure modes this closes that a guard-then-transaction split
+ * would not:
+ *
+ * 1. **TOCTOU on the guard.** A guard read taken BEFORE the transaction opens can go stale the
+ *    instant it returns — content can be assigned to the term in the gap between the read and the
+ *    delete, and the delete would proceed having checked a now-wrong count. Putting the read
+ *    inside the same transaction as the delete is what makes the guard's answer still true at the
+ *    moment the delete actually runs.
+ * 2. **Partial cascade.** `deleteTaxonomy` deletes N member terms then the taxonomy row itself,
+ *    with no FK/CASCADE at the schema level (`db/schema.ts` — `taxonomies`/`terms`/`entry_terms`/
+ *    `taxonomy_revisions` are plain columns, no foreign keys) to undo a mid-cascade failure. A
+ *    real transaction is the only thing that can.
+ *
+ * A caller-supplied identity/no-op implementation is a valid choice for a backend that has no
+ * separate transaction primitive to offer (see `repo.memory.ts`'s `InMemoryTaxonomyRepo` for the
+ * disclosed rationale) — the port exists so `deleteTerm`/`deleteTaxonomy` never have to know which
+ * kind of backend they're running against.
+ */
+export interface TransactionalRepoPort {
+    transaction<T>(fn: () => Promise<T>): Promise<T>;
+}
+export interface DeleteTermRequired {
+    deps: WriteServiceDeps & {
+        terms: DeletableTermRepoPort;
+        entryTerms: AssignmentCountEntryTermRepoPort;
+        /** See `TransactionalRepoPort`'s doc comment. Any one repo's `.transaction()` method is a
+         * valid source — the route/composition-root wiring picks one (this package stays agnostic to
+         * which); every write inside `fn` must land on the SAME underlying connection that opened it,
+         * which is a wiring obligation the caller owns, not something this function can verify. */
+        transaction: TransactionalRepoPort["transaction"];
+    };
+    principalId: string;
+    termId: string;
+}
+/**
+ * Deletes a single term. Refuses (never cascades) when the term still has children or is still
+ * assigned to content — both checks run, and either alone is enough to block, before any write.
+ * An unassigned, childless term is destroying nothing recoverable, so this is a direct delete with
+ * no plan()/confirmation ceremony (`mergeTerm` earns that ceremony because it migrates data this
+ * does not).
+ *
+ * `authorize()` runs before the transaction opens (a pure permission check, no side effect, so it
+ * doesn't need transactional protection); everything from the existence check onward — both
+ * guards and the delete itself — runs inside `deps.transaction()` (see that port's doc comment for
+ * why). Does NOT cascade-delete the term's `taxonomy_revisions` rows: that table is an append-only
+ * audit trail (mirrors `redirect_hits`/`asset_renditions`'s disclosed audit-not-referential-
+ * integrity precedent), and erasing a term's history the moment the term itself is deleted would
+ * destroy the very "this term existed and was deleted" record this call's own revision insert
+ * below creates. Confirmed by grepping `db/schema.ts`: no other table has a `taxonomyId`/`termId`
+ * column, so `taxonomy_revisions` is the only thing this decision applies to.
+ *
+ * @complexity O(1) — one `countChildren` call, one `countByTerm` call, one delete, all inside one
+ * transaction.
+ * @overallScore 100
+ */
+export declare function deleteTerm(required: DeleteTermRequired, _optional?: Record<string, never>): Promise<{
+    deletedTermId: string;
+}>;
+export interface DeleteTaxonomyRequired {
+    deps: WriteServiceDeps & {
+        taxonomies: DeletableTaxonomyRepoPort;
+        terms: TermListPort & DeletableTermRepoPort;
+        entryTerms: AssignmentCountEntryTermRepoPort;
+        /** See `TransactionalRepoPort`'s doc comment. */
+        transaction: TransactionalRepoPort["transaction"];
+    };
+    principalId: string;
+    taxonomyId: string;
+}
+/**
+ * Deletes a taxonomy together with its member terms, refusing when ANY member term is still
+ * assigned to content (the sum across all member terms, reported as one `assignedCount`). Unlike
+ * `deleteTerm`, this does cascade — but only over terms this same call has just confirmed, INSIDE
+ * the same transaction, are unassigned, so nothing recoverable is lost. `deleteTerm`'s own "has
+ * children" guard does not apply here: a member term's children are, by construction, also members
+ * of the same taxonomy (hierarchy never crosses taxonomies — `validateHierarchyAssignment`'s
+ * `ParentCrossTaxonomyError` enforces that on the write side), so deleting the full member set in
+ * one pass never leaves a `parentId` dangling outside the set being deleted.
+ *
+ * Same transaction-boundary and `taxonomy_revisions`-retention rationale as `deleteTerm` — see its
+ * doc comment. The taxonomy-level version of the same TOCTOU risk: `listByTaxonomy` and every
+ * per-term `countByTerm` call must see the SAME committed state the delete loop is about to act
+ * on, which is only guaranteed inside one transaction, not across N separate queries beforehand.
+ *
+ * @complexity O(t) in the taxonomy's own term count — one `countByTerm` per member term to total
+ * the guard, then one delete per member term plus one taxonomy delete, all inside one transaction.
+ * @overallScore 100
+ */
+export declare function deleteTaxonomy(required: DeleteTaxonomyRequired, _optional?: Record<string, never>): Promise<{
+    deletedTaxonomyId: string;
+    deletedTermIds: string[];
+}>;
+//# sourceMappingURL=write-service.d.ts.map

package/dist/taxonomy/write-service.d.ts.map

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