@happyvertical/smrt-content 0.40.69 → 0.41.0

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-content",
-  "packageVersion": "0.40.69",
+  "packageVersion": "0.41.0",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "0f3b52a712950836c3bc3d63407f68ebf2268df39287bb0aab9e54df75b13e19",
-    "packageJson": "7562e5c914c8f173b4e796ec9d484753561ed0b00f0647118d4eb05c5c7fc569",
+    "manifest": "4d489ab29e3ad464edf97963af9de5a42f464df36542888d78a0a0cdedc3fcff",
+    "packageJson": "1e308235bda68ab1be521d4f0cd13ce9ccdcb4f0dc936be0e648bf1814dd2f8a",
     "agents": "a75d356eadcd57611bbe3ba544254fd9a374aecb64a5ce13de2205ea2f7f48bb"
   },
   "exports": [
@@ -2041,6 +2041,11 @@
         "mode": "optional",
         "field": "tenantId"
       },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -3544,6 +3549,11 @@
         "mode": "optional",
         "field": "tenantId"
       },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -8068,6 +8078,12 @@
         "field": "tenantId"
       },
       "tableStrategy": "sti",
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context",
+        "_meta_type"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -10009,7 +10025,7 @@
     "junctionCollections": 2,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 77
+    "uuidColumns": 79
   },
   "agentDoc": "# @happyvertical/smrt-content\n\nSTI content management with governance workflows, contribution intake, AI reviews, fact-checking, corrections, versioning, transparency reports, and thumbnail generation.\n\n## Models\n\n- **Content** (STI base): `type`, `variant` (generator:domain:specific format), `status` (published/draft/review/archived/deleted), `state`, `category` (hierarchical path with `/` separator), `metadata` JSON, `tags` array, `thumbnailAssetId`\n- **Article**, **ContentDocument**, **Mirror**: STI subclasses — all share `contents` table via `_meta_type`\n- **ContentReview**: AI review result tied to a governance policy. Fields: `contentId`, `policyKey`, `kind`, `status` (accepted/flagged/rejected), `findings`, `fingerprint`, `metadata`\n- **ContentCorrection**: Post-publication change record. Fields: `contentId`, `type` (correction/retraction/update/clarification), `summary`, `note`, `status`, `metadata`\n- **ContentVersion**: Content snapshot. Fields: `contentId`, `kind` (manual/draft/review/publication/correction/auto-generated), `versionNumber`, `summary`, `metadata` (includes `transparency` for publication versions)\n- **ContentReference**: Junction model for content-to-content links (`content_references` table). Nullable `targetVersion` pins a citation to a specific `ContentVersion.version` for drift detection.\n- **ContentGovernancePolicy**: Persisted review policy (key, label, kind, instructions)\n- **ContentGovernanceProfile**: Persisted review profile (key, label, requirements array)\n- **ContentGovernanceAssignment**: Governs content type/variant → profile mapping, feature flags\n- **ContentContribution**: Held inbound submission with status lifecycle (submitted → approved/rejected/withdrawn → promoted)\n- **ContentContributor**: Contributor profile resolved by email, with trust level (standard/trusted/blocked)\n- **ContentContributionType**: Configures intake channels, rules, and promotion mapping\n- **ContentContributionRevision**: Revision history for held submissions\n- **ContentContributionAttachment**: Held file metadata; becomes an `Asset` on promotion\n\n## Contents Collection\n\n| Method | Purpose |\n|--------|---------| \n| `mirror({ url })` | Downloads URL content, extracts text, creates `type: 'mirror'`. Idempotent. |\n| `syncContentDir({ contentDir })` | Batch exports articles as markdown with YAML frontmatter |\n| `generateMissingThumbnails(options)` | Bulk thumbnail generation for content missing `thumbnailAssetId` |\n| `findWithGlobals(tenantId)` | Returns tenant-specific + global (tenantId=null) content |\n| `getOrUpsert({ slug, context })` | Upsert by slug+context combination |\n| `browseFacts()` | Browse fact catalog linked to content |\n| `getGovernanceDefinitionsAction()` | Get all governance policy/profile/assignment definitions |\n| `resolveGovernanceAction({ type, variant })` | Resolve effective governance for a content type |\n\n## Content Instance Methods\n\n| Method | Purpose |\n|--------|---------|\n| `resolveGovernance()` | Resolve effective governance config for this content |\n| `runReviewAction(options)` | Run AI review against a policy; returns `ContentReview` |\n| `listReviews()` | List all reviews for this content |\n| `listReviewProfilesAction()` | Get readiness for all profiles |\n| `evaluateReviewProfile(key)` | Evaluate one profile's requirements |\n| `issueCorrectionAction(options)` | Issue a post-publication correction |\n| `listCorrections()` | List corrections for this content |\n| `listVersions()` | List version history |\n| `mutateVersionAction(options)` | Create a version snapshot |\n| `getPublishedTransparencyAction()` | Get frozen transparency from latest publication version |\n| `previewTransparencyAction()` | Preview live transparency state |\n| `addFact(factId, relationship)` | Link a fact (supports/contradicts/referenced_in) |\n| `getFacts(options)` | Get linked facts |\n| `getFactLinks()` | Get fact-content link records |\n| `getFactsState()` / `syncFactsState(options)` | API-level facts get/sync |\n| `addAsset(asset, relationship, sortOrder)` | Add asset association |\n| `setThumbnail(image)` | Convenience: adds asset + updates `thumbnailAssetId` |\n| `addReference(content, options?)` | Link to another content; `options.targetVersion` pins citation-time `ContentVersion.version` |\n| `getReferences()` | Get content references |\n| `getReferenceDrift()` | Per-edge `{ citedVersion, currentVersion, isDrifted }` for drift detection |\n\n## Governance Workflow\n\n1. `configureContentGovernance({ policies, profiles, assignments })` — static config\n2. Or persist `ContentGovernancePolicy/Profile/Assignment` objects — DB overrides static\n3. Effective config: DB layer merges over static defaults\n4. `content.resolveGovernance()` → `ResolvedContentGovernance` with `isGoverned`, `reviewPolicies`, profile keys, feature flags\n5. `content.runReviewAction()` creates a `ContentReview` with fingerprint for staleness detection\n6. `content.evaluateReviewProfile(key)` checks all requirements\n7. `content.save()` auto-validates publish readiness when `enforcePublishReadiness` is true\n8. Publication auto-creates a `ContentVersion` with frozen transparency data\n\n## Thumbnail Generation\n\nThree strategies via ThumbnailGenerator:\n- **headline-card**: title on branded background (via `@happyvertical/images`)\n- **static-map**: requires `metadata.latitude`/`longitude` (via `@happyvertical/geo`)\n- **ai-generate**: AI image generation (dynamic import of `@happyvertical/ai`)\n\n## Svelte Components\n\n### Content Management\n`ContentList`, `ContentEditor`, `GovernedContentEditor`, `ContentAgentChat`, `ContentTitleField`, `ContentStatusFields`, `ContentMetadataFields`, `ContentReferencesPanel`, `ContentImageBrowser`, `ContentReviewStatusTray`, `ArticleCard`, `ArticleList`, `ImageThumbnail`, `Markdown`\n\n### Governance\n`ContentGovernanceManager`, `ContentGovernancePanel`, `ContentGovernancePolicyEditor`, `ContentGovernanceProfileEditor`, `ContentGovernanceAssignmentEditor`, `ContentTransparencyReport`\n\n### Contributions\n`ContentContributionForm`, `ContentContributionInbox`, `ContentContributionPortal`, `ContentContributionTypeManager`, `ContentContributorManager`\n\n## Dev Server\n\n`npm run dev` starts SvelteKit at `localhost:5173` with 4 pages:\n\n- `/` — Content catalog (CRUD, search, filters, card/list views)\n- `/governance` — Policy/profile/assignment management\n- `/contributions` — Inbox, submit form, contributor/type management\n- `/api-explorer` — Browse 69 endpoints with try-it-live for GET\n\nOn startup, `hooks.server.ts` bootstraps schemas for all 13 local classes,\nloads cross-package manifests, and seeds 3 sample content items.\n\n## Chat Integration\n\nContent `GET/POST /api/v1/contents/{id}/chat` endpoint creates\nchat sessions via `@happyvertical/smrt-chat`. Gracefully handles\nmissing chat tables (returns `session: null` with notice).\n`ContentAgentChat` Svelte component provides the UI.\n\nFor global assistant shells, `ContentEditor` and `GovernedContentEditor`\nsupport `onAssistantContextChange`. The callback receives a serializable\n`ContentEditorAssistantContext` plus local editor actions, and still fires when\n`hideChat={true}`. `ContentAgentChat` can be mounted outside the editor with an\n`assistantContext` prop. Server-side consumers can reuse the exported\n`getOrCreateContentEditorChatSession`, `createContentEditorChatThread`,\n`listContentEditorChatThreadMessages`, and\n`sendContentEditorChatThreadMessage` helpers for app-specific tenancy/auth/AI\nroute wiring.\n\nThese handlers go exclusively through the tenant-bound `ChatService` facade\n(S5 #1392) — `getAgentSession`/`findActiveAgentSessions`/`getThread`/\n`listRoomThreads`/`getThreadMessages` for reads and `startThread`/`sendMessage`/\n`sendAgentReply` (internal agent-runtime subpath) for writes. They never reach\ninto the now-`#private` chat collections, so cross-tenant chat state can no\nlonger be selected by raw id before authorization.\n\nThe content-editor session is created with a content-scoped `sessionKey`\n(`contentChatSessionKey(contentId)` → `content:<id>`, S5 #1392). Without it,\n`createAgentSession` reuses ANY active `content_editor` session for the same\nprofile/tenant, so a request about a new content id would reuse — and the\nhandler would rewrite — a session created for a different content and return the\nother content's room/threads. Keying on the content id makes each content get a\ndistinct session/room.\n\n## Relationship Models\n\n- **ContentReference**: SMRT junction model backing `content_references` for content-to-content links\n- **ContentAsset**: dedicated SMRT junction model backing `content_assets` for content-owned asset links\n\n```typescript\nawait content.addAsset(image, 'thumbnail', 0);  // relationship, sortOrder\nawait content.getAssets('attachment');\nawait content.setThumbnail(image);  // convenience: adds asset + updates thumbnailAssetId\nawait content.addReference(otherContent);                            // unpinned\nawait content.addReference(otherContent, { targetVersion: 2 });      // pinned to v2\nawait content.getReferences();\nawait content.getReferenceDrift();  // → [{ targetId, citedVersion, currentVersion, isDrifted }, ...]\n```\n\n## API Contracts\n\n`Content` implements `AssetAssociable` and `MetadataAccessor` (issue #1162). Consumers can type their parameters as `Content` (or the interfaces directly) and rely on the methods existing without `typeof === 'function'` defensive checks:\n\n```typescript\nimport type { AssetAssociable, MetadataAccessor } from '@happyvertical/smrt-content';\n\nasync function attachThumbnail(doc: AssetAssociable, asset: Asset) {\n  await doc.addAsset(asset, 'thumbnail', 0); // contract guaranteed\n}\n\nfunction bumpRevision(doc: MetadataAccessor) {\n  const meta = doc.getMetadata();\n  doc.updateMetadata({ revision: (meta.revision ?? 0) + 1 });\n}\n```\n\n## Category Navigation\n\n`getCategorySegments()`, `getParentCategory()`, `getRootCategory()`, `getAncestorPaths()`, `isInCategory(path, includeChildren?)`\n\n## Prompt Registry\n\nContent prompts are registered with `@happyvertical/smrt-prompts` so tenants can override template/profile/model/params at runtime:\n\n```typescript\nimport {\n  smrtContentReviewPrompt,             // key: 'smrtContent.review'\n  smrtContentApplyCorrectionPrompt,    // key: 'smrtContent.applyCorrection'\n  smrtContentThumbnailAIGeneratePrompt, // key: 'smrtContent.thumbnail.aiGenerate'\n} from '@happyvertical/smrt-content';\n```\n\n`smrtContent.thumbnail.aiGenerate` powers the AI image-generation prompt used by `ThumbnailGenerator` (strategy `'ai-generate'`). Variables substituted into the template: `style`, `title`, `styleHint`, `descriptionClause`. Internal foreign-key fields (`id`, `tenantId`) and the freeform `metadata` blob are intentionally excluded — `metadata` may carry tenant-private configuration or coordinates unrelated to the visual prompt.\n\n## Gotchas\n\n- **STI discriminator**: qualified names like `@happyvertical/smrt-content:Article`\n- **Optional tenancy**: `@TenantScoped({ mode: 'optional' })` — null tenantId = global content\n- **Metadata is primary extension pattern**: use JSON `metadata` field, not additional class fields\n- **Static map coordinates**: uses unary `+` for strict parsing (rejects \"45invalid\" unlike parseFloat)\n- **Review fingerprints**: reviews track content state at review time; stale reviews are detected by fingerprint mismatch\n- **Publish readiness enforcement**: `save()` throws `ValidationError` if blocking requirements aren't met when setting status to `'published'`\n- **Transparency snapshots**: published transparency is frozen into `ContentVersion.metadata.transparency` — use published for public display, preview for editors\n- **Reference pinning**: `ContentReference` is keyed on `(source_id, target_id)`; `targetVersion` is an attribute of the edge, not part of identity. Re-calling `addReference(target, { targetVersion })` updates the pin in place. Unpinned references (`targetVersion: null`) report `isDrifted: false` regardless of how stale the target is — pin them only when you want drift to be detectable.\n- **Generated API routes are not tracked**: everything the vite plugin emits under `src/routes/api/v1` is build output, listed in the bounded `.gitignore` block and regenerated on `npm run dev`. The handwritten handlers beside them (`contents/[id]/chat/**`, `images/**`) stay tracked and linted. Do not commit generated routes — they are not Biome-formatted, so tracking them turns the Lint job red (#2198)\n- **`pnpm typecheck` regenerates package-owned routes safely**: Svelte's analysis may load dependent package Vite configs, but those configs anchor their root to their own package. Content's generated API routes therefore remain under `src/routes/api/v1` and the bounded `.gitignore` block stays stable (#2199).\n- **Tests import generated routes and that is fine**: `contents-api.test.ts` imports `contents/+server.ts` and `contents/[id]/+server.ts` to exercise the generated CRUD handlers against a real SQLite database. The `test` script runs `svelte-kit sync` first, which regenerates the whole route tree, so those files exist by the time Vitest loads — no committed copy needed. Run `pnpm test`, never bare `vitest`, or the imports fail to resolve\n- **`generate:test` exists for the callers that bypass `test`**: `scripts/check-coverage.mjs` runs bare `vitest --coverage`, so without a `generate:test` hook the route imports above fail and the Coverage Gate reports `no coverage produced` rather than a real percentage. It is `cache: false` in `packages/content/turbo.json` — the root task's `outputs` describe core's manifest, so a turbo cache hit would restore nothing and silently skip `svelte-kit sync`\n- **Chat tables**: chat endpoint requires `@happyvertical/smrt-chat` tables; dev server handles missing tables gracefully\n- **Dev server bootstraps all classes**: `hooks.server.ts` generates schemas for all 13 local `@smrt()` classes plus cross-package manifests\n"
 }

package/dist/workbench.d.ts

@@ -477,8 +477,8 @@ declare const _default: {
                 tags?: string[];
             };
         };
-        description?: string | undefined;
         packageName: string;
+        description?: string | undefined;
         displayName: string;
     }[];
     recommendedCommands: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-content",
-  "version": "0.40.69",
+  "version": "0.41.0",
   "description": "Content processing module for SMRT framework - handles documents, web content, and media",
   "type": "module",
   "smrtRawPrimitives": "strict",
@@ -54,17 +54,17 @@
     "@happyvertical/utils": "^0.88.0",
     "fast-xml-parser": "^5.10.1",
     "yaml": "^2.9.0",
-    "@happyvertical/smrt-assets": "0.40.69",
-    "@happyvertical/smrt-chat": "0.40.69",
-    "@happyvertical/smrt-core": "0.40.69",
-    "@happyvertical/smrt-facts": "0.40.69",
-    "@happyvertical/smrt-images": "0.40.69",
-    "@happyvertical/smrt-messages": "0.40.69",
-    "@happyvertical/smrt-prompts": "0.40.69",
-    "@happyvertical/smrt-profiles": "0.40.69",
-    "@happyvertical/smrt-tenancy": "0.40.69",
-    "@happyvertical/smrt-types": "0.40.69",
-    "@happyvertical/smrt-ui": "0.40.69"
+    "@happyvertical/smrt-assets": "0.41.0",
+    "@happyvertical/smrt-chat": "0.41.0",
+    "@happyvertical/smrt-core": "0.41.0",
+    "@happyvertical/smrt-facts": "0.41.0",
+    "@happyvertical/smrt-images": "0.41.0",
+    "@happyvertical/smrt-messages": "0.41.0",
+    "@happyvertical/smrt-prompts": "0.41.0",
+    "@happyvertical/smrt-profiles": "0.41.0",
+    "@happyvertical/smrt-tenancy": "0.41.0",
+    "@happyvertical/smrt-types": "0.41.0",
+    "@happyvertical/smrt-ui": "0.41.0"
   },
   "peerDependencies": {
     "svelte": "^5.56.4"
@@ -85,8 +85,8 @@
     "typescript": "5.9.3",
     "vite": "8.1.4",
     "vitest": "4.1.10",
-    "@happyvertical/smrt-playground": "0.40.69",
-    "@happyvertical/smrt-vitest": "0.40.69"
+    "@happyvertical/smrt-playground": "0.41.0",
+    "@happyvertical/smrt-vitest": "0.41.0"
   },
   "keywords": [
     "ai",