@jini-ai/cms 0.3.10 → 0.4.0

package/dist/taxonomy/validation-chain.js

@@ -25,52 +25,59 @@
  * their own repo lookups, so the ordering guarantee holds regardless of how a caller wires them.
  */
 export class TaxonomyNotApplicableError extends Error {
-    constructor(message) {
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message } = requiredArgs;
         super(message);
         this.name = "TaxonomyNotApplicableError";
     }
 }
 export class WorkspaceMismatchError extends Error {
-    constructor(message) {
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message } = requiredArgs;
         super(message);
         this.name = "WorkspaceMismatchError";
     }
 }
 export class ContentTypeMismatchError extends Error {
-    constructor(message) {
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message } = requiredArgs;
         super(message);
         this.name = "ContentTypeMismatchError";
     }
 }
 export class TaxonomyNotHierarchicalError extends Error {
-    constructor(message) {
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message } = requiredArgs;
         super(message);
         this.name = "TaxonomyNotHierarchicalError";
     }
 }
 export class ParentCrossTaxonomyError extends Error {
-    constructor(message) {
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message } = requiredArgs;
         super(message);
         this.name = "ParentCrossTaxonomyError";
     }
 }
 export class TermNotFoundError extends Error {
-    constructor(message) {
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message } = requiredArgs;
         super(message);
         this.name = "TermNotFoundError";
     }
 }
 export class HierarchyCycleDetectedError extends Error {
-    constructor(message) {
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message } = requiredArgs;
         super(message);
         this.name = "HierarchyCycleDetectedError";
     }
 }
 /**
- * CIC U-002 — true if assigning `candidateParentId` as `termId`'s parent would create a cycle:
+ * — 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
+ * — 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
@@ -79,6 +86,7 @@ export class HierarchyCycleDetectedError extends Error {
  *
  * @complexity O(depth) — one `getParentId` call per ancestor hop, each hop visited at most once.
  * @overallScore 100
+ * See docs/decisions/DR-005-ordered-taxonomy-validation.md.
  */
 export function wouldCreateCycle(required, _optional = {}) {
     const { termId, candidateParentId, tree } = required;
@@ -90,7 +98,7 @@ export function wouldCreateCycle(required, _optional = {}) {
         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);
+        const parent = tree.getParentId({ termId: current });
         if (parent === termId)
             return true;
         current = parent;
@@ -98,55 +106,57 @@ export function wouldCreateCycle(required, _optional = {}) {
     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
+ * /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 (:
+ * not-on-allow-list always wins over a simultaneous workspace mismatch; : a workspace
  * mismatch always wins over a simultaneous lens mismatch).
  *
  * @complexity O(1) — three independent comparisons, no loop.
  * @overallScore 100
+ * See docs/decisions/DR-005-ordered-taxonomy-validation.md.
  */
 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}'`);
+        throw new TaxonomyNotApplicableError({ message: `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}'`);
+        throw new WorkspaceMismatchError({ message: `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}'`);
+        throw new ContentTypeMismatchError({ message: `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
+ * /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
+ * (no parent assignment attempted) always short-circuits to a pass regardless of mode (
  * 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
+ * The compound 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
+ * @complexity O(1) plus the injected `wouldCreateCycle` closure's own cost (only reached
  * once hierarchical-mode and same-taxonomy both pass).
  * @overallScore 100
+ * See docs/decisions/DR-005-ordered-taxonomy-validation.md.
  */
 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`);
+        throw new TaxonomyNotHierarchicalError({ message: `taxonomy '${childTaxonomyId}' is not hierarchical; parentId must be null` });
     }
     if (resolvedParent === null || resolvedParent === "not-applicable") {
-        throw new TermNotFoundError(`parent term '${candidateParentId}' was not found`);
+        throw new TermNotFoundError({ message: `parent term '${candidateParentId}' was not found` });
     }
     if (resolvedParent.taxonomyId !== childTaxonomyId) {
-        throw new ParentCrossTaxonomyError(`parent term '${candidateParentId}' belongs to taxonomy '${resolvedParent.taxonomyId}', not '${childTaxonomyId}'`);
+        throw new ParentCrossTaxonomyError({ message: `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`);
+    if (checkCycle({ candidateParentId })) {
+        throw new HierarchyCycleDetectedError({ message: `assigning '${candidateParentId}' as parent would create a hierarchy cycle` });
     }
 }
 //# sourceMappingURL=validation-chain.js.map

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

@@ -1,3 +1,4 @@
+import type { Clock, IdGenerator } from "@jini-ai/core/primitives";
 import type { TermListPort } from "./list.js";
 /**
  * @file The taxonomy write-service's ordinary (non-gated) mutations.
@@ -62,7 +63,9 @@ export interface Term {
     version: number;
 }
 export interface TaxonomyRepoPort {
-    findById(id: string): Promise<{
+    findById({ id }: {
+        id: string;
+    }): Promise<{
         id: string;
         hierarchical: boolean;
         allowList?: string[] | undefined;
@@ -70,7 +73,9 @@ export interface TaxonomyRepoPort {
     insert(row: Taxonomy): Promise<unknown>;
 }
 export interface TermRepoPort {
-    findById(id: string): Promise<{
+    findById({ id }: {
+        id: string;
+    }): Promise<{
         id: string;
         taxonomyId: string;
         name?: string | undefined;
@@ -102,9 +107,11 @@ export interface ContentLookupPort {
         kind: string;
     } | null>;
 }
-/** ADR-044: the content_types registry's per-type taxonomy allow-list for Collections entries
- *  (parallel to, never folded into, TAXONOMY_ALLOWED_CONTENT_TYPES — see the decision note).
- *  `null` = not a live registry type (not applicable). */
+/** : the content_types registry's per-type taxonomy allow-list for Collections entries
+ * (parallel to, never folded into, TAXONOMY_ALLOWED_CONTENT_TYPES — see the decision note).
+ * `null` = not a live registry type (not applicable).
+ * See docs/decisions/DR-005-ordered-taxonomy-validation.md.
+ */
 export interface ContentTypeTaxonomyPolicyPort {
     taxonomiesFor(params: {
         contentType: string;
@@ -117,7 +124,9 @@ export interface ContentTypeTaxonomyPolicyPort {
  * an intentionally parallel (not layered) per-content-type policy carried by a host's own
  * `content_types` registry. */
 export declare const TAXONOMY_ALLOWED_CONTENT_TYPES: ReadonlySet<string>;
-export declare function isContentTypeOnAllowList(contentType: string): boolean;
+export declare function isContentTypeOnAllowList(requiredArgs: {
+    contentType: string;
+}, optionalArgs?: Record<string, never>): boolean;
 export interface TaxonomyRevisionRow {
     taxonomyId: string;
     /** `"delete"` added for `deleteTerm`/`deleteTaxonomy` below — unlike `mergeTerm`'s reuse of
@@ -132,24 +141,24 @@ export interface TaxonomyRevisionRow {
 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;
+    clock: Clock;
+    idGen: IdGenerator;
     taxonomies: TaxonomyRepoPort;
     terms: TermRepoPort;
     entryTerms: EntryTermRepoPort;
     revisions: TaxonomyRevisionRepoPort;
-    /** `core/gated-mutations.stampWatermark`-shaped, injected — same-transaction stamp per mutation. */
-    stampWatermark: (tx?: unknown) => void;
+    /** `core/gated-mutations.stampWatermark`-shaped, injected — same-transaction stamp per mutation.
+     * May be sync (SQLite) or async (PGlite/Postgres); every call site awaits it, so an async stamp
+     * finishes, and its failure fails the write, before the mutation returns. */
+    stampWatermark: (required: Record<string, never>, optional?: {
+        tx?: unknown;
+    }) => Promise<void> | void;
     outbox: {
-        enqueue: (event: unknown) => Promise<void>;
+        enqueue: ({ event }: {
+            event: unknown;
+        }) => Promise<void>;
     };
     /** The caller's own workspace — `validateContentJoin`'s `callerWorkspaceId` (Finding 1 fix). */
     workspaceId: string;
@@ -162,14 +171,20 @@ export interface WriteServiceDeps {
     contentTypeTaxonomyPolicy?: ContentTypeTaxonomyPolicyPort;
 }
 export declare class TaxonomyRecordNotFoundError extends Error {
-    constructor(message: string);
+    constructor(requiredArgs: {
+        message: string;
+    }, optionalArgs?: Record<string, never>);
 }
 export declare class TermRecordNotFoundError extends Error {
-    constructor(message: string);
+    constructor(requiredArgs: {
+        message: string;
+    }, optionalArgs?: Record<string, never>);
 }
 /** 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);
+    constructor(requiredArgs: {
+        message: string;
+    }, optionalArgs?: Record<string, never>);
 }
 /**
  * J1 (plan-publish-all-types-2026-09-25.md) — `importTaxonomy`/`importTerm`'s optimistic-concurrency
@@ -180,7 +195,9 @@ export declare class ContentRecordNotFoundError extends Error {
  * "catch the one it actually called into" rule.
  */
 export declare class TaxonomyVersionConflictError extends Error {
-    constructor(message: string);
+    constructor(requiredArgs: {
+        message: string;
+    }, optionalArgs?: Record<string, never>);
 }
 export interface CreateTaxonomyRequired {
     deps: WriteServiceDeps;
@@ -196,13 +213,17 @@ export interface CreateTermRequired {
     principalId: string;
     taxonomyId: string;
     name: string;
+}
+export interface CreateTermOptional {
     parentId?: string | null | undefined;
 }
-/** AC-03/AC-13/EC-04 — validates `parentId` via `validateHierarchyAssignment` before writing. A
+/** — 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>;
+ * 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).
+ * See docs/decisions/DR-005-ordered-taxonomy-validation.md.
+ */
+export declare function createTerm(required: CreateTermRequired, optional?: CreateTermOptional): Promise<Term>;
 /**
  * Additive capability beyond the certified `TaxonomyRepoPort` — `findById`'s narrow return
  * (`{id, hierarchical, allowList?}`) doesn't carry `version`/`name`/`status`/`updatedAt`, which
@@ -210,7 +231,9 @@ export declare function createTerm(required: CreateTermRequired, _optional?: Rec
  * write an existing row back. Same beyond-the-certified-port precedent as `DeletableTaxonomyRepoPort`.
  */
 export interface ImportableTaxonomyRepoPort {
-    findByIdFull(id: string): Promise<Taxonomy | null>;
+    findByIdFull({ id }: {
+        id: string;
+    }): Promise<Taxonomy | null>;
     update(row: Taxonomy): Promise<unknown>;
 }
 export interface ImportTaxonomyRequired {
@@ -247,7 +270,9 @@ export declare function importTaxonomy(required: ImportTaxonomyRequired, _option
  * `TermRepoPort` already has `update`, unlike taxonomies, so no additive `update` is needed here.
  */
 export interface ImportableTermRepoPort {
-    findByIdFull(id: string): Promise<Term | null>;
+    findByIdFull({ id }: {
+        id: string;
+    }): Promise<Term | null>;
 }
 export interface ImportTermRequired {
     deps: WriteServiceDeps & {
@@ -258,10 +283,12 @@ export interface ImportTermRequired {
     id: string;
     taxonomyId: string;
     name: string;
-    parentId?: string | null | undefined;
     /** Same three-way CAS contract as `importTaxonomy.expectedVersion`. */
     expectedVersion: number | undefined;
 }
+export interface ImportTermOptional {
+    parentId?: string | null | undefined;
+}
 /**
  * Slice J1 — the publish-content import chokepoint for `terms`. Address (name within
  * `(taxonomyId, parentId)`) uniqueness is the publish factory's own precheck, not this function's
@@ -275,16 +302,23 @@ export interface ImportTermRequired {
  * @complexity O(d) — one taxonomy lookup, one id lookup, one optional parent lookup, `d` ancestor
  * lookups (the candidate parent's depth), one insert-or-update, one revision append.
  */
-export declare function importTerm(required: ImportTermRequired, _optional?: Record<string, never>): Promise<Term>;
+export declare function importTerm(required: ImportTermRequired, optional?: ImportTermOptional): Promise<Term>;
 export interface RenameTermRequired {
-    deps: WriteServiceDeps;
+    deps: WriteServiceDeps & {
+        /** Required shared transaction. All repos, the watermark and outbox
+         * must share the store/connection opened by this port. */
+        transaction: TransactionalRepoPort["transaction"];
+    };
     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. */
+/** — 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. A missing transaction capability fails closed before any lookup
+ * or write; a caller must supply a real shared transaction for durable atomicity.
+ * See docs/decisions/DR-005-ordered-taxonomy-validation.md.
+ */
 export declare function renameTerm(required: RenameTermRequired, _optional?: Record<string, never>): Promise<Term>;
 export interface AssignTermsRequired {
     deps: WriteServiceDeps;
@@ -313,14 +347,16 @@ export interface UnassignTermsRequired {
     contentId: string;
     termIds: string[];
 }
-/** SPEC-018 REQ-07/REQ-13/REQ-14/REQ-17/REQ-22 — spec debt this codebase never built (the spec
+/** — spec debt this codebase never built (the spec
  * always named "assign/unassign tools"; only `assignTerms` shipped). Same
  * authorize -> validateAssignmentTarget -> write -> stamp -> outbox chokepoint as `assignTerms`,
- * and — like `assignTerms` — never produces a `taxonomy_revisions` row (REQ-13/INV-05's disclosed
+ * and — like `assignTerms` — never produces a `taxonomy_revisions` row ( disclosed
  * narrowing applies equally to removal). Idempotent: unassigning a row that isn't there is a no-op,
- * not an error (`remove()`'s 0-vs-1 return is intentionally not surfaced to the caller). Chosen over
+ * not an error (`remove`'s 0-vs-1 return is intentionally not surfaced to the caller). Chosen over
  * a "set terms" replace call — see the taxonomy plan's "What the docs settle" #3 for why replace
- * risks silently erasing a concurrent assignment. */
+ * risks silently erasing a concurrent assignment.
+ * See docs/decisions/DR-005-ordered-taxonomy-validation.md.
+ */
 export declare function unassignTerms(required: UnassignTermsRequired, _optional?: Record<string, never>): Promise<void>;
 export interface EntryTermsCleanupPort {
     deleteByContent(params: {
@@ -341,8 +377,18 @@ export interface OnContentDeletedRequired {
  * `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>;
+ * assigned terms, never an error. Repository failures are warnings through the optional
+ * logger port; logger failure also cannot turn cleanup into a hard failure. Hosts should
+ * wire the logger for diagnostics; legacy callers without it remain silent. */
+export declare function onContentDeleted(required: OnContentDeletedRequired, optional?: {
+    logger?: {
+        warn(required: {
+            message: string;
+            error: unknown;
+            event: OnContentDeletedRequired["event"];
+        }): void | Promise<void>;
+    };
+}): Promise<void>;
 /**
  * Additive capabilities beyond the certified `TaxonomyRepoPort`/`TermRepoPort`/`EntryTermRepoPort`
  * — same beyond-the-certified-port precedent `MergeableEntryTermRepoPort` established in this
@@ -352,10 +398,14 @@ export declare function onContentDeleted(required: OnContentDeletedRequired, _op
  * 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>;
+    delete({ id }: {
+        id: string;
+    }): Promise<void>;
 }
 export interface DeletableTermRepoPort {
-    delete(id: string): Promise<void>;
+    delete({ id }: {
+        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
@@ -384,19 +434,28 @@ export interface AssignmentCountEntryTermRepoPort {
  * assigned" instead of a generic failure. */
 export declare class TermHasAssignedContentError extends Error {
     readonly assignedCount: number;
-    constructor(message: string, assignedCount: number);
+    constructor(requiredArgs: {
+        message: string;
+        assignedCount: number;
+    }, _optionalArgs?: Record<string, never>);
 }
 /** 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);
+    constructor(requiredArgs: {
+        message: string;
+        childCount: number;
+    }, _optionalArgs?: Record<string, never>);
 }
 /** `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);
+    constructor(requiredArgs: {
+        message: string;
+        assignedCount: number;
+    }, _optionalArgs?: Record<string, never>);
 }
 /**
  * Opens/commits/rolls back one transaction around `fn` — the same shape and contract as this
@@ -424,7 +483,9 @@ export declare class TaxonomyHasAssignedContentError extends Error {
  * kind of backend they're running against.
  */
 export interface TransactionalRepoPort {
-    transaction<T>(fn: () => Promise<T>): Promise<T>;
+    transaction<T>({ fn }: {
+        fn: () => Promise<T>;
+    }): Promise<T>;
 }
 export interface DeleteTermRequired {
     deps: WriteServiceDeps & {