@happyvertical/smrt-core 0.44.0 → 0.45.0

package/dist/revision-guard.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Revision compare-and-swap predicate construction (#2620).
+ *
+ * `SmrtObject.save()` and {@link SmrtObject.claimRevision} guard every write to
+ * a persisted row with a predicate on the revision the caller loaded. On
+ * PostgreSQL that predicate cannot be a plain equality against
+ * `Date.prototype.toISOString()`, because the JavaScript `Date` that carries the
+ * revision is two lossy conversions away from the stored value:
+ *
+ * 1. **Precision.** `updated_at` is a microsecond column — `timestamptz(6)` on
+ *    schemas this version materializes, `timestamp(6)` on older ones — so any
+ *    row last written by raw SQL (`updated_at = CURRENT_TIMESTAMP` / `now()`)
+ *    stores microseconds, for example `2026-09-02 08:11:28.939980`. A `Date`
+ *    holds milliseconds, so the exact-equality predicate matched no row and
+ *    every later `save()` on that row raised `RUNTIME_REVISION_CONFLICT`
+ *    forever — a permanent failure, not a lost race.
+ * 2. **Process timezone.** Schemas created before the `TIMESTAMPTZ` mapping
+ *    still hold `updated_at` as `timestamp WITHOUT time zone`, and `pg`
+ *    hydrates that type by reading the stored wall clock in the *process* zone.
+ *    On a non-UTC host the resulting `Date` is offset from the instant the
+ *    writer meant, so `toISOString()` produced a wall clock the row never held
+ *    and every guarded save conflicted. The same columns are also written under
+ *    three different conventions — `pg` serializes a `Date` in the process
+ *    zone, `claimRevision()` writes a UTC ISO string, and raw
+ *    `CURRENT_TIMESTAMP` writes in the *server* zone — so no single rendering
+ *    can match every row.
+ *
+ * Both are fixed here without asking callers to compensate:
+ *
+ * - the column is truncated to milliseconds in SQL, the finest precision a
+ *   `Date` can represent, so a microsecond tail can no longer hide the row; and
+ * - the revision is offered in **both** wall-clock renderings — the process-zone
+ *   one (the inverse of `pg`'s local hydration of `timestamp`) and the UTC one
+ *   (what `timestamptz` hydration and SMRT's own ISO writes produce). Each is
+ *   tagged `+00`, which a `timestamptz` comparison honours and a `timestamp`
+ *   comparison discards, so the predicate never depends on the *session*
+ *   TimeZone either. Accepting either candidate keeps the guard correct
+ *   whatever convention the column and driver use, so a future UTC-hydration
+ *   fix in `@happyvertical/sql` cannot silently break it. That driver-layer
+ *   half is tracked as happyvertical/sdk#1223; this guard deliberately does not
+ *   wait for it.
+ *
+ * Lost-race semantics are preserved. A concurrent writer advances `updated_at`
+ * to roughly "now" (see `nextRevisionTimestamp`), which would have to land on
+ * the loaded revision — or, on a non-UTC process only, on exactly that revision
+ * shifted by the process's whole-hour-scale UTC offset — to the millisecond
+ * before it could slip past. Any ordinary concurrent write differs by at least
+ * one millisecond and still conflicts. On a UTC process the two renderings
+ * coincide and the predicate is single-valued, so it is strictly no weaker than
+ * the exact equality it replaces. Making it single-valued on a non-UTC process
+ * too — by resolving the column's actual type, or by deleting the process-zone
+ * rendering once happyvertical/sdk#1223 hydrates `timestamp` as UTC — is
+ * tracked as #2623.
+ *
+ * The predicate is PostgreSQL-only. Embedded engines take the compare/upsert
+ * fallback in `usesEmbeddedRevisionFallback`, and remote LibSQL stores ISO text
+ * whose exact equality already round-trips losslessly.
+ */
+/** The SQL expression the PostgreSQL revision predicate compares against. */
+export declare const POSTGRES_REVISION_GUARD_EXPRESSION = "date_trunc('milliseconds', updated_at)";
+/**
+ * Render a revision as every `timestamp without time zone` wall clock it could
+ * legitimately correspond to, at millisecond precision.
+ *
+ * The process-zone rendering comes first because it is the inverse of `pg`'s
+ * current hydration; the UTC rendering is what SMRT's own writes persist. On a
+ * UTC process the two coincide and a single candidate is returned.
+ *
+ * @param revision - Revision loaded from the row, or supplied by the caller as
+ *   `save({ expectedUpdatedAt })` / `claimRevision()`. Strings are parsed with
+ *   `Date` semantics, so an ISO instant and a bare SQL wall clock both work.
+ * @returns One or two `YYYY-MM-DD HH:MM:SS.mmm+00` strings
+ * @throws {RangeError} If `revision` does not parse to a valid date
+ */
+export declare function postgresRevisionCandidates(revision: Date | string): string[];
+/**
+ * Build the PostgreSQL revision condition for a generic `db.update()` WHERE
+ * clause.
+ *
+ * @param revision - The revision the writer loaded
+ * @returns A single-entry condition object to spread into the update predicate
+ */
+export declare function postgresRevisionCondition(revision: Date | string): Record<string, string[]>;
+//# sourceMappingURL=revision-guard.d.ts.map

package/dist/revision-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revision-guard.d.ts","sourceRoot":"","sources":["../src/revision-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAIH,6EAA6E;AAC7E,eAAO,MAAM,kCAAkC,2CACL,CAAC;AAgB3C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,CA0B5E;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,IAAI,GAAG,MAAM,GACtB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAK1B"}

package/dist/revision-guard.js

@@ -0,0 +1,120 @@
+import { raw } from "@happyvertical/sql";
+//#region src/revision-guard.ts
+/**
+* Revision compare-and-swap predicate construction (#2620).
+*
+* `SmrtObject.save()` and {@link SmrtObject.claimRevision} guard every write to
+* a persisted row with a predicate on the revision the caller loaded. On
+* PostgreSQL that predicate cannot be a plain equality against
+* `Date.prototype.toISOString()`, because the JavaScript `Date` that carries the
+* revision is two lossy conversions away from the stored value:
+*
+* 1. **Precision.** `updated_at` is a microsecond column — `timestamptz(6)` on
+*    schemas this version materializes, `timestamp(6)` on older ones — so any
+*    row last written by raw SQL (`updated_at = CURRENT_TIMESTAMP` / `now()`)
+*    stores microseconds, for example `2026-09-02 08:11:28.939980`. A `Date`
+*    holds milliseconds, so the exact-equality predicate matched no row and
+*    every later `save()` on that row raised `RUNTIME_REVISION_CONFLICT`
+*    forever — a permanent failure, not a lost race.
+* 2. **Process timezone.** Schemas created before the `TIMESTAMPTZ` mapping
+*    still hold `updated_at` as `timestamp WITHOUT time zone`, and `pg`
+*    hydrates that type by reading the stored wall clock in the *process* zone.
+*    On a non-UTC host the resulting `Date` is offset from the instant the
+*    writer meant, so `toISOString()` produced a wall clock the row never held
+*    and every guarded save conflicted. The same columns are also written under
+*    three different conventions — `pg` serializes a `Date` in the process
+*    zone, `claimRevision()` writes a UTC ISO string, and raw
+*    `CURRENT_TIMESTAMP` writes in the *server* zone — so no single rendering
+*    can match every row.
+*
+* Both are fixed here without asking callers to compensate:
+*
+* - the column is truncated to milliseconds in SQL, the finest precision a
+*   `Date` can represent, so a microsecond tail can no longer hide the row; and
+* - the revision is offered in **both** wall-clock renderings — the process-zone
+*   one (the inverse of `pg`'s local hydration of `timestamp`) and the UTC one
+*   (what `timestamptz` hydration and SMRT's own ISO writes produce). Each is
+*   tagged `+00`, which a `timestamptz` comparison honours and a `timestamp`
+*   comparison discards, so the predicate never depends on the *session*
+*   TimeZone either. Accepting either candidate keeps the guard correct
+*   whatever convention the column and driver use, so a future UTC-hydration
+*   fix in `@happyvertical/sql` cannot silently break it. That driver-layer
+*   half is tracked as happyvertical/sdk#1223; this guard deliberately does not
+*   wait for it.
+*
+* Lost-race semantics are preserved. A concurrent writer advances `updated_at`
+* to roughly "now" (see `nextRevisionTimestamp`), which would have to land on
+* the loaded revision — or, on a non-UTC process only, on exactly that revision
+* shifted by the process's whole-hour-scale UTC offset — to the millisecond
+* before it could slip past. Any ordinary concurrent write differs by at least
+* one millisecond and still conflicts. On a UTC process the two renderings
+* coincide and the predicate is single-valued, so it is strictly no weaker than
+* the exact equality it replaces. Making it single-valued on a non-UTC process
+* too — by resolving the column's actual type, or by deleting the process-zone
+* rendering once happyvertical/sdk#1223 hydrates `timestamp` as UTC — is
+* tracked as #2623.
+*
+* The predicate is PostgreSQL-only. Embedded engines take the compare/upsert
+* fallback in `usesEmbeddedRevisionFallback`, and remote LibSQL stores ISO text
+* whose exact equality already round-trips losslessly.
+*/
+/** The SQL expression the PostgreSQL revision predicate compares against. */
+var POSTGRES_REVISION_GUARD_EXPRESSION = "date_trunc('milliseconds', updated_at)";
+function pad(value, width = 2) {
+	return String(value).padStart(width, "0");
+}
+function formatWallClock(parts) {
+	const [year, month, day, hours, minutes, seconds, milliseconds] = parts;
+	return `${pad(year, 4)}-${pad(month)}-${pad(day)} ${pad(hours)}:${pad(minutes)}:${pad(seconds)}.${pad(milliseconds, 3)}+00`;
+}
+/**
+* Render a revision as every `timestamp without time zone` wall clock it could
+* legitimately correspond to, at millisecond precision.
+*
+* The process-zone rendering comes first because it is the inverse of `pg`'s
+* current hydration; the UTC rendering is what SMRT's own writes persist. On a
+* UTC process the two coincide and a single candidate is returned.
+*
+* @param revision - Revision loaded from the row, or supplied by the caller as
+*   `save({ expectedUpdatedAt })` / `claimRevision()`. Strings are parsed with
+*   `Date` semantics, so an ISO instant and a bare SQL wall clock both work.
+* @returns One or two `YYYY-MM-DD HH:MM:SS.mmm+00` strings
+* @throws {RangeError} If `revision` does not parse to a valid date
+*/
+function postgresRevisionCandidates(revision) {
+	const date = revision instanceof Date ? revision : new Date(revision);
+	if (Number.isNaN(date.getTime())) throw new RangeError(`Revision guard requires a valid timestamp, received: ${String(revision)}`);
+	const local = formatWallClock([
+		date.getFullYear(),
+		date.getMonth() + 1,
+		date.getDate(),
+		date.getHours(),
+		date.getMinutes(),
+		date.getSeconds(),
+		date.getMilliseconds()
+	]);
+	const utc = formatWallClock([
+		date.getUTCFullYear(),
+		date.getUTCMonth() + 1,
+		date.getUTCDate(),
+		date.getUTCHours(),
+		date.getUTCMinutes(),
+		date.getUTCSeconds(),
+		date.getUTCMilliseconds()
+	]);
+	return local === utc ? [local] : [local, utc];
+}
+/**
+* Build the PostgreSQL revision condition for a generic `db.update()` WHERE
+* clause.
+*
+* @param revision - The revision the writer loaded
+* @returns A single-entry condition object to spread into the update predicate
+*/
+function postgresRevisionCondition(revision) {
+	return { [raw(`${POSTGRES_REVISION_GUARD_EXPRESSION} in`)]: postgresRevisionCandidates(revision) };
+}
+//#endregion
+export { POSTGRES_REVISION_GUARD_EXPRESSION, postgresRevisionCandidates, postgresRevisionCondition };
+
+//# sourceMappingURL=revision-guard.js.map

package/dist/revision-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revision-guard.js","names":[],"sources":["../src/revision-guard.ts"],"sourcesContent":["/**\n * Revision compare-and-swap predicate construction (#2620).\n *\n * `SmrtObject.save()` and {@link SmrtObject.claimRevision} guard every write to\n * a persisted row with a predicate on the revision the caller loaded. On\n * PostgreSQL that predicate cannot be a plain equality against\n * `Date.prototype.toISOString()`, because the JavaScript `Date` that carries the\n * revision is two lossy conversions away from the stored value:\n *\n * 1. **Precision.** `updated_at` is a microsecond column — `timestamptz(6)` on\n *    schemas this version materializes, `timestamp(6)` on older ones — so any\n *    row last written by raw SQL (`updated_at = CURRENT_TIMESTAMP` / `now()`)\n *    stores microseconds, for example `2026-09-02 08:11:28.939980`. A `Date`\n *    holds milliseconds, so the exact-equality predicate matched no row and\n *    every later `save()` on that row raised `RUNTIME_REVISION_CONFLICT`\n *    forever — a permanent failure, not a lost race.\n * 2. **Process timezone.** Schemas created before the `TIMESTAMPTZ` mapping\n *    still hold `updated_at` as `timestamp WITHOUT time zone`, and `pg`\n *    hydrates that type by reading the stored wall clock in the *process* zone.\n *    On a non-UTC host the resulting `Date` is offset from the instant the\n *    writer meant, so `toISOString()` produced a wall clock the row never held\n *    and every guarded save conflicted. The same columns are also written under\n *    three different conventions — `pg` serializes a `Date` in the process\n *    zone, `claimRevision()` writes a UTC ISO string, and raw\n *    `CURRENT_TIMESTAMP` writes in the *server* zone — so no single rendering\n *    can match every row.\n *\n * Both are fixed here without asking callers to compensate:\n *\n * - the column is truncated to milliseconds in SQL, the finest precision a\n *   `Date` can represent, so a microsecond tail can no longer hide the row; and\n * - the revision is offered in **both** wall-clock renderings — the process-zone\n *   one (the inverse of `pg`'s local hydration of `timestamp`) and the UTC one\n *   (what `timestamptz` hydration and SMRT's own ISO writes produce). Each is\n *   tagged `+00`, which a `timestamptz` comparison honours and a `timestamp`\n *   comparison discards, so the predicate never depends on the *session*\n *   TimeZone either. Accepting either candidate keeps the guard correct\n *   whatever convention the column and driver use, so a future UTC-hydration\n *   fix in `@happyvertical/sql` cannot silently break it. That driver-layer\n *   half is tracked as happyvertical/sdk#1223; this guard deliberately does not\n *   wait for it.\n *\n * Lost-race semantics are preserved. A concurrent writer advances `updated_at`\n * to roughly \"now\" (see `nextRevisionTimestamp`), which would have to land on\n * the loaded revision — or, on a non-UTC process only, on exactly that revision\n * shifted by the process's whole-hour-scale UTC offset — to the millisecond\n * before it could slip past. Any ordinary concurrent write differs by at least\n * one millisecond and still conflicts. On a UTC process the two renderings\n * coincide and the predicate is single-valued, so it is strictly no weaker than\n * the exact equality it replaces. Making it single-valued on a non-UTC process\n * too — by resolving the column's actual type, or by deleting the process-zone\n * rendering once happyvertical/sdk#1223 hydrates `timestamp` as UTC — is\n * tracked as #2623.\n *\n * The predicate is PostgreSQL-only. Embedded engines take the compare/upsert\n * fallback in `usesEmbeddedRevisionFallback`, and remote LibSQL stores ISO text\n * whose exact equality already round-trips losslessly.\n */\n\nimport { raw } from '@happyvertical/sql';\n\n/** The SQL expression the PostgreSQL revision predicate compares against. */\nexport const POSTGRES_REVISION_GUARD_EXPRESSION =\n  \"date_trunc('milliseconds', updated_at)\";\n\nfunction pad(value: number, width = 2): string {\n  return String(value).padStart(width, '0');\n}\n\nfunction formatWallClock(\n  parts: [number, number, number, number, number, number, number],\n): string {\n  const [year, month, day, hours, minutes, seconds, milliseconds] = parts;\n  return (\n    `${pad(year, 4)}-${pad(month)}-${pad(day)} ` +\n    `${pad(hours)}:${pad(minutes)}:${pad(seconds)}.${pad(milliseconds, 3)}+00`\n  );\n}\n\n/**\n * Render a revision as every `timestamp without time zone` wall clock it could\n * legitimately correspond to, at millisecond precision.\n *\n * The process-zone rendering comes first because it is the inverse of `pg`'s\n * current hydration; the UTC rendering is what SMRT's own writes persist. On a\n * UTC process the two coincide and a single candidate is returned.\n *\n * @param revision - Revision loaded from the row, or supplied by the caller as\n *   `save({ expectedUpdatedAt })` / `claimRevision()`. Strings are parsed with\n *   `Date` semantics, so an ISO instant and a bare SQL wall clock both work.\n * @returns One or two `YYYY-MM-DD HH:MM:SS.mmm+00` strings\n * @throws {RangeError} If `revision` does not parse to a valid date\n */\nexport function postgresRevisionCandidates(revision: Date | string): string[] {\n  const date = revision instanceof Date ? revision : new Date(revision);\n  if (Number.isNaN(date.getTime())) {\n    throw new RangeError(\n      `Revision guard requires a valid timestamp, received: ${String(revision)}`,\n    );\n  }\n  const local = formatWallClock([\n    date.getFullYear(),\n    date.getMonth() + 1,\n    date.getDate(),\n    date.getHours(),\n    date.getMinutes(),\n    date.getSeconds(),\n    date.getMilliseconds(),\n  ]);\n  const utc = formatWallClock([\n    date.getUTCFullYear(),\n    date.getUTCMonth() + 1,\n    date.getUTCDate(),\n    date.getUTCHours(),\n    date.getUTCMinutes(),\n    date.getUTCSeconds(),\n    date.getUTCMilliseconds(),\n  ]);\n  return local === utc ? [local] : [local, utc];\n}\n\n/**\n * Build the PostgreSQL revision condition for a generic `db.update()` WHERE\n * clause.\n *\n * @param revision - The revision the writer loaded\n * @returns A single-entry condition object to spread into the update predicate\n */\nexport function postgresRevisionCondition(\n  revision: Date | string,\n): Record<string, string[]> {\n  return {\n    [raw(`${POSTGRES_REVISION_GUARD_EXPRESSION} in`)]:\n      postgresRevisionCandidates(revision),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8DA,IAAa,qCACX;AAEF,SAAS,IAAI,OAAe,QAAQ,GAAW;CAC7C,OAAO,OAAO,KAAK,CAAC,CAAC,SAAS,OAAO,GAAG;AAC1C;AAEA,SAAS,gBACP,OACQ;CACR,MAAM,CAAC,MAAM,OAAO,KAAK,OAAO,SAAS,SAAS,gBAAgB;CAClE,OACE,GAAG,IAAI,MAAM,CAAC,EAAE,GAAG,IAAI,KAAK,EAAE,GAAG,IAAI,GAAG,EAAE,GACvC,IAAI,KAAK,EAAE,GAAG,IAAI,OAAO,EAAE,GAAG,IAAI,OAAO,EAAE,GAAG,IAAI,cAAc,CAAC,EAAE;AAE1E;;;;;;;;;;;;;;;AAgBA,SAAgB,2BAA2B,UAAmC;CAC5E,MAAM,OAAO,oBAAoB,OAAO,WAAW,IAAI,KAAK,QAAQ;CACpE,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,GAC7B,MAAM,IAAI,WACR,wDAAwD,OAAO,QAAQ,GACzE;CAEF,MAAM,QAAQ,gBAAgB;EAC5B,KAAK,YAAY;EACjB,KAAK,SAAS,IAAI;EAClB,KAAK,QAAQ;EACb,KAAK,SAAS;EACd,KAAK,WAAW;EAChB,KAAK,WAAW;EAChB,KAAK,gBAAgB;CACvB,CAAC;CACD,MAAM,MAAM,gBAAgB;EAC1B,KAAK,eAAe;EACpB,KAAK,YAAY,IAAI;EACrB,KAAK,WAAW;EAChB,KAAK,YAAY;EACjB,KAAK,cAAc;EACnB,KAAK,cAAc;EACnB,KAAK,mBAAmB;CAC1B,CAAC;CACD,OAAO,UAAU,MAAM,CAAC,KAAK,IAAI,CAAC,OAAO,GAAG;AAC9C;;;;;;;;AASA,SAAgB,0BACd,UAC0B;CAC1B,OAAO,GACJ,IAAI,GAAG,mCAAmC,IAAI,IAC7C,2BAA2B,QAAQ,EACvC;AACF"}

package/dist/scanner/manifest-generator.d.ts

@@ -131,22 +131,6 @@ export declare class ManifestGenerator {
      * Also checks external SMRT packages for parent class definitions.
      */
     private isSTIChildClass;
-    /**
-     * Check whether `obj` extends a framework abstract base class anywhere
-     * in its chain.
-     *
-     * Framework abstract bases (`SmrtHierarchical`, `SmrtJunction`, …) have
-     * no table of their own — fields they declare must be merged into every
-     * subclass's manifest, even when the subclass uses CTI. Without this,
-     * a class like `Account extends SmrtHierarchical` would silently lose
-     * `parentId` from its `fields` map and downstream WHERE-clause
-     * validation would reject queries on the inherited column.
-     *
-     * Identified by name against the same hardcoded set the scanner's
-     * `FRAMEWORK_BASE_CLASSES` recognizes (`packages/scanner/src/
-     * inheritance-resolver.ts`). Keep the two lists in sync.
-     */
-    private extendsFrameworkAbstractBase;
     /**
      * Resolve a class name (simple `Content` or qualified `@pkg:Content`) to
      * the key it is stored under in `manifest.objects`, or `undefined` when the
@@ -290,6 +274,52 @@ export declare class ManifestGenerator {
      * Generate simple MCP tool names for testing/documentation
      */
     generateMCPTools(manifest: SmartObjectManifest): string;
+    /**
+     * Choose exactly one canonical MCP owner per `collection`.
+     *
+     * MCP tool names are keyed on `collection`, but the framework's normal shape
+     * puts a model class and its `FooCollection` access class in the manifest
+     * under the SAME collection. Emitting both produces duplicate tool names with
+     * differing create/update schemas, and an MCP client that indexes tools by
+     * name then resolves an arbitrary one (#2631 review).
+     *
+     * Owners are ranked, in order:
+     *
+     * 1. The model class beats the collection-access class. `create`/`update`
+     *    input schemas derive from `obj.fields`, and the row shape lives on the
+     *    model, not on the access class.
+     * 2. The shallowest class in the collection's own inheritance tree wins. An
+     *    STI family shares one `collection`, and the base defines the shared row
+     *    contract; a leaf subclass would narrow the emitted schema to one variant
+     *    of a table the tool addresses as a whole.
+     * 3. Remaining ties break lexically on the qualified name, so the emitted
+     *    surface is deterministic across generation passes.
+     */
+    private selectMCPToolOwners;
+    /** Stable identity for an MCP owner candidate. */
+    private mcpOwnerKey;
+    /**
+     * Depth of each candidate inside the candidate set's OWN inheritance tree,
+     * keyed by {@link mcpOwnerKey}. A candidate with no candidate ancestor is a
+     * root at depth 0. Ancestors outside the set (framework bases, classes in
+     * other collections) do not add depth: only the shared-collection family
+     * decides which member is canonical.
+     *
+     * Parents resolve on `extendsQualified` first. Two packages may legally
+     * contribute same-simple-name classes to one collection, so a simple-name
+     * match is used only when it is unambiguous within the candidate set —
+     * otherwise the walk stops rather than linking unrelated classes.
+     */
+    private inheritanceDepthsWithin;
+    /** True when `candidate` is the better canonical MCP owner than `current`. */
+    private preferMCPToolOwner;
+    /**
+     * Collection-access class detection, matching the convention already used by
+     * `generateRestRoutes` (direct base / generic type argument) plus the
+     * `FooCollection` naming fallback this generator uses elsewhere, so a deeper
+     * subclass that carries no type argument of its own is still recognised.
+     */
+    private isCollectionAccessClass;
     /**
      * Generate MCP tool JSON definitions
      */

package/dist/scanner/manifest-generator.d.ts.map

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

package/dist/scanner/manifest-generator.js

@@ -47,6 +47,57 @@ var FRAMEWORK_ABSTRACT_BASE_NAMES = /* @__PURE__ */ new Set([
 	"SmrtReportCollection"
 ]);
 /**
+* Framework base classes to exclude from the ancestor **method** merge
+* below (#2624). Unlike fields, methods are never columns, so they never
+* needed the STI-vs-CTI field-merge rule above — they inherited it only by
+* sharing the same loop.
+*
+* Deliberately NARROWER than `FRAMEWORK_ABSTRACT_BASE_NAMES`: only the
+* three universal object/collection primitives (`SmrtObject`, `SmrtClass`,
+* `SmrtCollection`) are internal-only. These are the same three the
+* runtime resolver's `getAllMethods()`
+* (`packages/core/src/registry/inheritance-resolver.ts`) explicitly skips
+* by name, and the same three the field-merge doc comment above excludes
+* from `FRAMEWORK_ABSTRACT_BASE_NAMES` for the identical reason: their
+* surface (`save`, `destroy`, `toJSON`, `withTransaction`, ...) is generic
+* object-lifecycle plumbing, never a subclass-specific action.
+*
+* `FRAMEWORK_ABSTRACT_BASE_NAMES` (`SmrtJunction`, `SmrtHierarchical`,
+* `SmrtPolymorphicAssociation`, `SmrtReport`, `SmrtReportCollection`) is
+* intentionally NOT folded in here, unlike an earlier version of this fix.
+* Those classes are mixin-style bases whose declared methods ARE the
+* subclass's real, intended public API — the same way `SmrtHierarchical.
+* parentId` is a real, intended field, which is exactly why
+* `FRAMEWORK_ABSTRACT_BASE_NAMES` fields already merge into every subclass
+* regardless of STI/CTI (see above). Directly confirmed for two of the
+* five: `SmrtJunction.attach`/`detach`/`byLeft`/`byRight`/`setLinks`
+* (`packages/core/src/junction.ts`) — a `packages/template-sveltekit/
+* __tests__/runtimeProfileParity.test.ts` snapshot broke when an earlier
+* revision of this fix folded all 8 `FRAMEWORK_BASE_CLASSES` in here,
+* which is how this got caught — and `SmrtHierarchical.getParent`/
+* `getChildren`/`getAncestors`/`getDescendants`/`getHierarchy`/`moveTo`
+* (`packages/core/src/hierarchical.ts`). `SmrtPolymorphicAssociation`
+* follows the identical pattern by inspection but has no dedicated
+* regression test yet. `SmrtReport`/`SmrtReportCollection` are the
+* least-audited of the five: `SmrtReportCollection` overrides `list`/`get`
+* (`packages/reports/src/report.ts`), which are also the universal CRUD
+* operation names — a downstream `class X extends SmrtReportCollection`
+* with default (non-strict) MCP config would have seen a generated
+* custom-action tool collide with the standard `list`/`get` tool name.
+* #2646 closed that separately and independently of this exclusion set: the
+* MCP generator now refuses to expose a CRUD-named method as a custom action,
+* matching case-folded because its tool ids are lowercased whole. Each emitter
+* reserves on its own terms, and not all of them read the shared
+* `CRUD_OPERATIONS` list yet — see its docblock in
+* `generators/custom-action.ts` for the per-emitter rules. Keep in sync with the field-merge set's own doc comment; this one
+* governs method merging only.
+*/
+var FRAMEWORK_METHOD_BASE_NAMES = /* @__PURE__ */ new Set([
+	"SmrtObject",
+	"SmrtClass",
+	"SmrtCollection"
+]);
+/**
 * Infer visibility from file path and explicit config
 *
 * Priority:
@@ -605,36 +656,6 @@ var ManifestGenerator = class {
 		return false;
 	}
 	/**
-	* Check whether `obj` extends a framework abstract base class anywhere
-	* in its chain.
-	*
-	* Framework abstract bases (`SmrtHierarchical`, `SmrtJunction`, …) have
-	* no table of their own — fields they declare must be merged into every
-	* subclass's manifest, even when the subclass uses CTI. Without this,
-	* a class like `Account extends SmrtHierarchical` would silently lose
-	* `parentId` from its `fields` map and downstream WHERE-clause
-	* validation would reject queries on the inherited column.
-	*
-	* Identified by name against the same hardcoded set the scanner's
-	* `FRAMEWORK_BASE_CLASSES` recognizes (`packages/scanner/src/
-	* inheritance-resolver.ts`). Keep the two lists in sync.
-	*/
-	extendsFrameworkAbstractBase(obj, objectsByName, manifest) {
-		if (!obj.extends) return false;
-		let currentClass = obj.extends;
-		const visited = /* @__PURE__ */ new Set();
-		while (currentClass) {
-			if (visited.has(currentClass)) break;
-			visited.add(currentClass);
-			if (FRAMEWORK_ABSTRACT_BASE_NAMES.has(currentClass)) return true;
-			let parentObj = objectsByName.get(currentClass);
-			if (!parentObj && manifest.smrtDependencies && manifest.smrtDependencies.length > 0) parentObj = this.loadParentFromExternalPackage(currentClass, manifest.smrtDependencies, objectsByName);
-			if (!parentObj) break;
-			currentClass = parentObj.extends;
-		}
-		return false;
-	}
-	/**
 	* Resolve a class name (simple `Content` or qualified `@pkg:Content`) to
 	* the key it is stored under in `manifest.objects`, or `undefined` when the
 	* manifest does not carry it. Manifest keys are qualified names; `extends`
@@ -728,8 +749,6 @@ var ManifestGenerator = class {
 		for (const obj of Object.values(manifest.objects)) {
 			if (!obj.extends) continue;
 			const usesSTI = this.isSTIClass(obj, objectsByName, manifest);
-			const extendsFrameworkBase = this.extendsFrameworkAbstractBase(obj, objectsByName, manifest);
-			if (!usesSTI && !extendsFrameworkBase) continue;
 			logger.info(`[manifest-generator] Merging inherited fields for ${obj.className} from ${obj.extends}`);
 			const inheritanceChain = [];
 			let currentClass = obj.extends;
@@ -755,8 +774,7 @@ var ManifestGenerator = class {
 				const ancestor = objectsByName.get(ancestorName);
 				if (!ancestor) continue;
 				const ancestorIsFrameworkBase = FRAMEWORK_ABSTRACT_BASE_NAMES.has(ancestorName);
-				if (!usesSTI && !ancestorIsFrameworkBase) continue;
-				for (const [fieldName, fieldDef] of Object.entries(ancestor.fields)) {
+				if (usesSTI || ancestorIsFrameworkBase) for (const [fieldName, fieldDef] of Object.entries(ancestor.fields)) {
 					const existingOwner = mergedFieldOwners.get(fieldName);
 					const replacesFrameworkDefault = existingOwner !== void 0 && FRAMEWORK_ABSTRACT_BASE_NAMES.has(this.simpleClassName(existingOwner)) && !FRAMEWORK_ABSTRACT_BASE_NAMES.has(this.simpleClassName(ancestorName));
 					if (!existingOwner || replacesFrameworkDefault) {
@@ -764,7 +782,7 @@ var ManifestGenerator = class {
 						mergedFieldOwners.set(fieldName, ancestorName);
 					}
 				}
-				for (const [methodName, methodDef] of Object.entries(ancestor.methods || {})) if (!mergedMethods[methodName]) mergedMethods[methodName] = methodDef;
+				if (!FRAMEWORK_METHOD_BASE_NAMES.has(ancestorName)) for (const [methodName, methodDef] of Object.entries(ancestor.methods || {})) mergedMethods[methodName] = methodDef;
 			}
 			for (const [fieldName, fieldDef] of Object.entries(obj.fields)) mergedFields[fieldName] = fieldDef;
 			for (const [methodName, methodDef] of Object.entries(obj.methods || {})) mergedMethods[methodName] = methodDef;
@@ -1159,16 +1177,123 @@ ${fields}
 	*/
 	generateMCPTools(manifest) {
 		const tools = [];
-		for (const [_name, obj] of Object.entries(manifest.objects)) if (obj.decoratorConfig.mcp !== false) tools.push(...this.getSimpleMCPToolNames(obj));
+		for (const obj of this.selectMCPToolOwners(manifest)) tools.push(...this.getSimpleMCPToolNames(obj));
 		return tools.join("\n");
 	}
 	/**
+	* Choose exactly one canonical MCP owner per `collection`.
+	*
+	* MCP tool names are keyed on `collection`, but the framework's normal shape
+	* puts a model class and its `FooCollection` access class in the manifest
+	* under the SAME collection. Emitting both produces duplicate tool names with
+	* differing create/update schemas, and an MCP client that indexes tools by
+	* name then resolves an arbitrary one (#2631 review).
+	*
+	* Owners are ranked, in order:
+	*
+	* 1. The model class beats the collection-access class. `create`/`update`
+	*    input schemas derive from `obj.fields`, and the row shape lives on the
+	*    model, not on the access class.
+	* 2. The shallowest class in the collection's own inheritance tree wins. An
+	*    STI family shares one `collection`, and the base defines the shared row
+	*    contract; a leaf subclass would narrow the emitted schema to one variant
+	*    of a table the tool addresses as a whole.
+	* 3. Remaining ties break lexically on the qualified name, so the emitted
+	*    surface is deterministic across generation passes.
+	*/
+	selectMCPToolOwners(manifest) {
+		const candidatesByCollection = /* @__PURE__ */ new Map();
+		for (const obj of Object.values(manifest.objects)) {
+			if (obj.decoratorConfig.mcp === false) continue;
+			const bucket = candidatesByCollection.get(obj.collection);
+			if (bucket) bucket.push(obj);
+			else candidatesByCollection.set(obj.collection, [obj]);
+		}
+		return [...candidatesByCollection.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([, candidates]) => {
+			const depths = this.inheritanceDepthsWithin(candidates);
+			let owner = candidates[0];
+			for (const candidate of candidates.slice(1)) if (this.preferMCPToolOwner(candidate, owner, depths)) owner = candidate;
+			return owner;
+		});
+	}
+	/** Stable identity for an MCP owner candidate. */
+	mcpOwnerKey(obj) {
+		return obj.qualifiedName || obj.className;
+	}
+	/**
+	* Depth of each candidate inside the candidate set's OWN inheritance tree,
+	* keyed by {@link mcpOwnerKey}. A candidate with no candidate ancestor is a
+	* root at depth 0. Ancestors outside the set (framework bases, classes in
+	* other collections) do not add depth: only the shared-collection family
+	* decides which member is canonical.
+	*
+	* Parents resolve on `extendsQualified` first. Two packages may legally
+	* contribute same-simple-name classes to one collection, so a simple-name
+	* match is used only when it is unambiguous within the candidate set —
+	* otherwise the walk stops rather than linking unrelated classes.
+	*/
+	inheritanceDepthsWithin(candidates) {
+		const byQualified = /* @__PURE__ */ new Map();
+		const bySimpleName = /* @__PURE__ */ new Map();
+		for (const candidate of candidates) {
+			byQualified.set(this.mcpOwnerKey(candidate), candidate);
+			const simple = this.simpleClassName(candidate.className);
+			bySimpleName.set(simple, bySimpleName.has(simple) ? null : candidate);
+		}
+		const resolveParent = (obj) => {
+			if (obj.extendsQualified) return byQualified.get(obj.extendsQualified);
+			if (!obj.extends) return void 0;
+			return bySimpleName.get(this.simpleClassName(obj.extends)) ?? void 0;
+		};
+		const depths = /* @__PURE__ */ new Map();
+		for (const candidate of candidates) {
+			const key = this.mcpOwnerKey(candidate);
+			let depth = 0;
+			let current = candidate;
+			const visited = /* @__PURE__ */ new Set([key]);
+			while (current) {
+				const parent = resolveParent(current);
+				if (!parent) break;
+				const parentKey = this.mcpOwnerKey(parent);
+				if (visited.has(parentKey)) break;
+				visited.add(parentKey);
+				depth += 1;
+				current = parent;
+			}
+			depths.set(key, depth);
+		}
+		return depths;
+	}
+	/** True when `candidate` is the better canonical MCP owner than `current`. */
+	preferMCPToolOwner(candidate, current, depths) {
+		const candidateIsCollection = this.isCollectionAccessClass(candidate);
+		if (candidateIsCollection !== this.isCollectionAccessClass(current)) return !candidateIsCollection;
+		const candidateKey = this.mcpOwnerKey(candidate);
+		const currentKey = this.mcpOwnerKey(current);
+		const candidateDepth = depths.get(candidateKey) ?? 0;
+		const currentDepth = depths.get(currentKey) ?? 0;
+		if (candidateDepth !== currentDepth) return candidateDepth < currentDepth;
+		return candidateKey < currentKey;
+	}
+	/**
+	* Collection-access class detection, matching the convention already used by
+	* `generateRestRoutes` (direct base / generic type argument) plus the
+	* `FooCollection` naming fallback this generator uses elsewhere, so a deeper
+	* subclass that carries no type argument of its own is still recognised.
+	*/
+	isCollectionAccessClass(obj) {
+		return obj.extends === "SmrtCollection" || !!obj.extendsTypeArg || obj.className.endsWith("Collection");
+	}
+	/**
 	* Generate MCP tool JSON definitions
 	*/
 	generateMCPToolsCode(manifest) {
 		const tools = [];
-		for (const [_name, obj] of Object.entries(manifest.objects)) if (obj.decoratorConfig.mcp !== false) tools.push(this.generateMCPTool(obj));
-		return `[\n${tools.join(",\n")}\n]`;
+		for (const obj of this.selectMCPToolOwners(manifest)) {
+			const code = this.generateMCPTool(obj);
+			if (code) tools.push(code);
+		}
+		return tools.length > 0 ? `[\n${tools.join(",\n")}\n]` : "[]";
 	}
 	/**
 	* Get simple MCP tool names for an object
@@ -1195,7 +1320,7 @@ ${fields}
 	* Generate a single MCP tool
 	*/
 	generateMCPTool(obj) {
-		const { collection, className, name } = obj;
+		const { collection } = obj;
 		const config = obj.decoratorConfig.mcp;
 		const exclude = typeof config === "object" && config?.exclude || [];
 		const include = typeof config === "object" && config?.include || void 0;
@@ -1218,28 +1343,56 @@ ${fields}
     }
   }`);
 		if (shouldInclude("get")) tools.push(`  {
-    name: "get_${name}",
-    description: "Get a ${name} by ID",
+    name: "get_${collection}",
+    description: "Get a ${collection} entry by ID",
     inputSchema: {
       type: "object",
       properties: {
-        id: { type: "string", description: "The ${name} ID" }
+        id: { type: "string", description: "The ${collection} entry ID" }
       },
       required: ["id"]
     }
   }`);
+		const schemaProperties = JSON.stringify(this.generateSchemaProperties(obj.fields), null, 6);
 		if (shouldInclude("create")) {
 			const requiredFields = Object.entries(obj.fields).filter(([_, field]) => field.required).map(([fieldName]) => fieldName);
 			tools.push(`  {
-    name: "create_${name}",
-    description: "Create a new ${name}",
+    name: "create_${collection}",
+    description: "Create a new ${collection} entry",
     inputSchema: {
       type: "object",
-      properties: ${JSON.stringify(this.generateSchemaProperties(obj.fields), null, 6)},
+      properties: ${schemaProperties},
       required: ${JSON.stringify(requiredFields)}
     }
   }`);
 		}
+		if (shouldInclude("update")) tools.push(`  {
+    name: "update_${collection}",
+    description: "Update an existing ${collection} entry",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The ${collection} entry ID" },
+        data: {
+          type: "object",
+          description: "Fields to update on the ${collection} entry",
+          properties: ${schemaProperties}
+        }
+      },
+      required: ["id", "data"]
+    }
+  }`);
+		if (shouldInclude("delete")) tools.push(`  {
+    name: "delete_${collection}",
+    description: "Delete a ${collection} entry by ID",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The ${collection} entry ID" }
+      },
+      required: ["id"]
+    }
+  }`);
 		return tools.join(",\n");
 	}
 	/**