@happyvertical/smrt-content 0.44.0 → 0.45.0

package/agents/content-list.md

@@ -1,12 +1,67 @@
 <!-- Module doc for packages/content/AGENTS.md. Linked from the Modules table there. -->
 
-# ContentList: shared adapter, server query, URL state, saved views
+# ContentList: shared adapter, query state, saved views, and lifecycle
 
 `ContentList` reads every row, column, filter, and action through one shared
 adapter (`src/svelte/content-list-controller.ts`) over a `DataTableController`,
 and can source those rows either from a client array or from the bounded
 content query endpoint. This doc covers both modes end to end.
 
+## Trash, restore, and permanent deletion (#2454)
+
+Lifecycle controls are an opt-in server-authoritative seam. Pass a
+`ContentListLifecycleBinding` as `lifecycle`; set `lifecycleMode="trash"` for a
+trash view. Trash mode locks the live status predicate to `deleted`, hides the
+ordinary status control, removes legacy edit/delete buttons, and exposes
+restore, permanent-delete, and empty-trash actions. Omit the binding and
+ContentList keeps its existing `onDelete` behavior.
+
+The browser never treats rendered rows as mutation authority. It sends a
+selection reference, canonical query for `all-matching`, expected count, and
+server revision through `createContentListLifecycleTransport()`. Preview,
+initial apply, and every replay use distinct per-attempt request ids. Apply and
+replay retain the opaque confirmation and idempotency authority envelope, while
+the result's `auditReference` continues to identify the original execution.
+Changing the query or selection invalidates the preview; expired, stale-revision,
+row-revision, query-fingerprint, token, or matching-count failures require a
+new preview.
+
+Mount `createContentListLifecycleRoute()` from
+`@happyvertical/smrt-content/server` at the transport's default
+`POST /api/v1/contents/lifecycle` path. The host supplies a callback that
+authenticates each native `Request` and returns its current principal/tenant
+action context. The route accepts only the three lifecycle action ids and
+delegates to the same `createContentListActionAdapter()` instance used by agent
+and bulk-workflow callers; it never owns a second authorization or mutation
+path. Invalid JSON, missing authentication, and internal failures return
+bounded error envelopes without exposing private error text.
+
+Lifecycle action ids and restore input are stable:
+
+| action | eligible server state | input / consequence |
+|---|---|---|
+| `move-to-trash` | not already `deleted` | soft-deletes content into trash |
+| `restore` | `deleted` | `{ status: 'draft' \| 'review' \| 'published' }`; the server re-runs permission and publish-readiness checks |
+| `permanent-delete` | `deleted` | irreversible deletion; the operator must type the exact server-resolved count |
+
+Permanent deletion binds the row's `updated_at` revision into the final delete.
+On PostgreSQL that comparison is part of the `DELETE` predicate and any cascade
+shares its transaction; embedded adapters compare under the framework's shared
+write queue before cascading. A writer racing preview/apply therefore produces
+`row_revision_drifted` instead of deleting newer content.
+
+The result details expose `count`, accepted/skipped/failed counts,
+representative labels, canonical subtype-aware outcomes
+(`resourceType`/`resourceId`), and `auditReference`. Applying a partial result
+removes only accepted ids from selection, keeping skipped and failed rows
+selected for inspection or retry. The exact query refreshes after success;
+progress, partial exceptions, and the audit reference remain visible in a
+polite live region. Empty trash is available only when an exact server count
+and canonical query are present, so a page-sized guess cannot stand in for its
+scope. `maxSelectionSize` defaults to 200; larger matching sets are announced
+and fail closed until the operator narrows the query, matching the server's
+bounded one-preview selection contract.
+
 ## Realtime, freshness, and background workflows (#2455)
 
 A server-backed list consumes the complete reactive seam exposed by
@@ -142,6 +197,25 @@ Adapter exports (also re-exported from `./svelte`): `createContentListController
 `resolveSelectedContentListRows`, `resolveSelectedContents`, plus the
 `CONTENT_LIST_*` identity constants.
 
+## Agent data-surface conformance (#2456)
+
+`dataSurface` publishes the mounted list's readable columns, supported query
+operators, visible state, selection scope, freshness, and only the actions its
+mounted workflow/lifecycle bindings can execute. Visible commands run through
+the registry's revision check; their acknowledgements describe the accepted
+controller revision, while a disconnected registry refuses them.
+
+For silent agent reads, register
+`createContentListDataSurfaceDefinition({ collection, scope })` from
+`@happyvertical/smrt-content/server` in the server-owned
+`createDataSurfaceTools()` catalog. The factory resolves both the collection
+and optional application scope from the live principal context, then delegates
+rows, counts, facets, and offset continuations to `executeContentQuery()`.
+Tenant, hidden, and sensitive fields remain outside discovery and projection;
+the model request can only narrow the trusted scope. Durable actions continue
+through `createContentListActionAdapter()` and its principal-bound
+preview/apply contract rather than through the browser registry.
+
 Notes:
 
 - Controller modes are all `manual`: the adapter owns search, filters, sorting,
@@ -194,15 +268,19 @@ Notes:
   — which owns both in compact mode — is not mounted there. A page size arriving
   from a saved view or a surface command would otherwise strand the operator on
   page one, and a refresh over retained rows would be silent.
-- `dataSurface` registers the compact table only. Agent addressability for the
-  grid and detailed presentations lands with #2456.
-- Compact mode stays mounted for empty and loading results — DataTable renders
-  its own `empty` snippet and loading row — because it owns the mounted surface:
-  swapping it for the shared empty panel unregisters the surface, and an agent
-  whose own search returned nothing then gets `not_found` on the command that
-  would undo it. The shared loading/empty panels are the card presentations'
-  only; the `error` branch still replaces the list in every mode, since a load
-  failure is host-driven rather than surface-driven.
+- `dataSurface` registers at the `ContentList` boundary, independently of its
+  renderer. Grid, detailed, compact, loading, empty, and error presentations
+  therefore retain one stable surface identity. A `set-view` command updates
+  the published `viewMode` and revision before the renderer changes, so its
+  acknowledgement always describes the accepted presentation.
+- The mounted snapshot publishes the controller state and normalized selection
+  together with the active query fingerprint, total, presentation, and
+  freshness (`stale`, `refreshing`, `offline`, last update, truncation, and
+  warnings). Context-only changes advance the same revision stream as visible
+  controller commands; stale command revisions are refused by the registry.
+- Discovery publishes per-column search/filter/sort operators. A server-backed
+  list narrows the derived `site` column to read-only because the content query
+  translator cannot soundly project, filter, or sort that display value.
 
 ## ContentList server-backed mode (#2452)
 
@@ -965,10 +1043,11 @@ keeps the control from misstating the query; `readContentListFilter` stays
 value-only and must not drive a control. Choosing any real option replaces every
 filter on that column, so the operator is never stuck.
 
-`review` is now offered outright. `deleted` is deliberately not: that is the
-trash lifecycle (#2454), and offering it here would imply a restore/purge
-affordance this list does not have. `Content.type` is freeform, so its option
-list is a display vocabulary rather than the model's domain.
+`review` is now offered outright. `deleted` is deliberately not part of the
+ordinary status vocabulary: the opt-in trash lifecycle locks that predicate
+and supplies the restore/purge affordances as one inseparable mode.
+`Content.type` is freeform, so its option list is a display vocabulary rather
+than the model's domain.
 
 Everything a restore or a translation refused is reported in one dismissible
 notice rather than thrown — a stale link or an out-of-date saved view must still

package/dist/chunks/{content-corrections-BxfA3tW1.js → content-corrections-B4mPd_th.js}

@@ -52,8 +52,11 @@ var ContentCorrection = class extends SmrtObject {
 		}
 	}
 };
-__decorateClass([foreignKey("Content", { required: true })], ContentCorrection.prototype, "contentId", 2);
-__decorateClass([foreignKey("ContentVersion")], ContentCorrection.prototype, "contentVersionId", 2);
+__decorateClass([foreignKey("Content", {
+	required: true,
+	onDelete: "CASCADE"
+})], ContentCorrection.prototype, "contentId", 2);
+__decorateClass([foreignKey("ContentVersion", { onDelete: "CASCADE" })], ContentCorrection.prototype, "contentVersionId", 2);
 __decorateClass([crossPackageRef("@happyvertical/smrt-facts:Fact")], ContentCorrection.prototype, "factId", 2);
 __decorateClass([crossPackageRef("@happyvertical/smrt-facts:Fact")], ContentCorrection.prototype, "replacementFactId", 2);
 __decorateClass([tenantId({ nullable: true })], ContentCorrection.prototype, "tenantId", 2);
@@ -104,4 +107,4 @@ var ContentCorrectionCollection = class extends SmrtCollection {
 //#endregion
 export { content_corrections_exports as n, ContentCorrection as r, ContentCorrectionCollection as t };
 
-//# sourceMappingURL=content-corrections-BxfA3tW1.js.map
+//# sourceMappingURL=content-corrections-B4mPd_th.js.map

package/dist/chunks/content-corrections-B4mPd_th.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-corrections-B4mPd_th.js","names":[],"sources":["../../src/content-correction.ts","../../src/content-corrections.ts"],"sourcesContent":["import type { SmrtObjectOptions } from '@happyvertical/smrt-core';\nimport {\n  crossPackageRef,\n  foreignKey,\n  SmrtObject,\n  smrt,\n} from '@happyvertical/smrt-core';\nimport { TenantScoped, tenantId } from '@happyvertical/smrt-tenancy';\nimport type {\n  ContentCorrectionStatus,\n  ContentCorrectionType,\n} from './content-governance';\n\nexport interface ContentCorrectionOptions extends SmrtObjectOptions {\n  contentId?: string;\n  contentVersionId?: string;\n  factId?: string;\n  replacementFactId?: string;\n  correctionType?: ContentCorrectionType;\n  status?: ContentCorrectionStatus;\n  summary?: string;\n  incorrectText?: string;\n  correctedText?: string;\n  publicNote?: string;\n  metadata?: string | Record<string, unknown>;\n  tenantId?: string | null;\n  publishedAt?: Date | null;\n  createdAt?: Date;\n  updatedAt?: Date;\n}\n\n@TenantScoped({ mode: 'optional' })\n@smrt({\n  tableName: 'content_corrections',\n  api: { include: ['list', 'get', 'create', 'update'] },\n  mcp: { include: ['list', 'get', 'create', 'update'] },\n  cli: true,\n})\nexport class ContentCorrection extends SmrtObject {\n  @foreignKey('Content', { required: true, onDelete: 'CASCADE' })\n  contentId = '';\n\n  @foreignKey('ContentVersion', { onDelete: 'CASCADE' })\n  contentVersionId = '';\n\n  @crossPackageRef('@happyvertical/smrt-facts:Fact')\n  factId = '';\n\n  @crossPackageRef('@happyvertical/smrt-facts:Fact')\n  replacementFactId = '';\n  correctionType: ContentCorrectionType = 'fact';\n  status: ContentCorrectionStatus = 'draft';\n  summary = '';\n  incorrectText = '';\n  correctedText = '';\n  publicNote = '';\n  metadata = '';\n\n  @tenantId({ nullable: true })\n  tenantId: string | null = null;\n\n  publishedAt: Date | null = null;\n  createdAt = new Date();\n  updatedAt = new Date();\n\n  constructor(options: ContentCorrectionOptions = {}) {\n    super(options);\n    if (options.contentId) this.contentId = options.contentId;\n    if (options.contentVersionId !== undefined)\n      this.contentVersionId = options.contentVersionId;\n    if (options.factId !== undefined) this.factId = options.factId;\n    if (options.replacementFactId !== undefined)\n      this.replacementFactId = options.replacementFactId;\n    if (options.correctionType !== undefined)\n      this.correctionType = options.correctionType;\n    if (options.status !== undefined) this.status = options.status;\n    if (options.summary !== undefined) this.summary = options.summary;\n    if (options.incorrectText !== undefined)\n      this.incorrectText = options.incorrectText;\n    if (options.correctedText !== undefined)\n      this.correctedText = options.correctedText;\n    if (options.publicNote !== undefined) this.publicNote = options.publicNote;\n    if (options.tenantId !== undefined) this.tenantId = options.tenantId;\n    if (options.publishedAt !== undefined)\n      this.publishedAt = options.publishedAt;\n    if (options.createdAt) this.createdAt = options.createdAt;\n    if (options.updatedAt) this.updatedAt = options.updatedAt;\n\n    if (options.metadata !== undefined) {\n      this.metadata =\n        typeof options.metadata === 'string'\n          ? options.metadata\n          : JSON.stringify(options.metadata);\n    }\n  }\n\n  getMetadata(): Record<string, unknown> {\n    try {\n      return this.metadata ? JSON.parse(this.metadata) : {};\n    } catch {\n      return {};\n    }\n  }\n}\n","import { SmrtCollection } from '@happyvertical/smrt-core';\nimport { ContentCorrection } from './content-correction';\n\nexport class ContentCorrectionCollection extends SmrtCollection<ContentCorrection> {\n  static readonly _itemClass = ContentCorrection;\n\n  async listForContent(contentId: string): Promise<ContentCorrection[]> {\n    return this.list({\n      where: { contentId },\n      orderBy: 'created_at DESC',\n    });\n  }\n\n  async getPublishedForContent(\n    contentId: string,\n  ): Promise<ContentCorrection[]> {\n    return this.list({\n      where: { contentId, status: 'published' },\n      orderBy: 'published_at DESC',\n    });\n  }\n\n  async issue(\n    options: ConstructorParameters<typeof ContentCorrection>[0],\n  ): Promise<ContentCorrection> {\n    if (!options) {\n      return this.create({});\n    }\n\n    return this.create({\n      ...options,\n      metadata:\n        typeof options.metadata === 'string'\n          ? options.metadata\n          : options.metadata\n            ? JSON.stringify(options.metadata)\n            : undefined,\n    });\n  }\n}\n"],"mappings":"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"}