@happyvertical/smrt-assets 0.57.44 → 0.57.45

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,7 +2,7 @@
2
2
  "version": "1.0.0",
3
3
  "timestamp": 0,
4
4
  "packageName": "@happyvertical/smrt-assets",
5
- "packageVersion": "0.57.44",
5
+ "packageVersion": "0.57.45",
6
6
  "objects": {
7
7
  "@happyvertical/smrt-assets:AssetAssociation": {
8
8
  "name": "assetassociation",
@@ -1,3 +1,4 @@
1
+ import type { AssetCollection } from "./assets.js";
1
2
  /** Trusted server capability. Never construct this from an untrusted API payload. */
2
3
  export interface PrivateAssetAccess {
3
4
  tenantId: string;
@@ -11,4 +12,34 @@ export interface PrivateAssetAccess {
11
12
  * Nested capabilities may only narrow their parent's IDs and retain its owner.
12
13
  */
13
14
  export declare function withPrivateAssetAccess<T>(access: PrivateAssetAccess, callback: () => Promise<T>): Promise<T>;
15
+ /** Request for {@link readPrivateAssetMetadata}. Trusted server input only. */
16
+ export interface PrivateAssetMetadataRequest {
17
+ tenantId: string;
18
+ actorUserId: string;
19
+ assetId: string;
20
+ }
21
+ /**
22
+ * Display-safe projection of a private asset. This is an allowlist: it never
23
+ * carries the owner, storage locators (`sourceUri`), the description sidecar,
24
+ * processor metadata or any capability.
25
+ */
26
+ export interface PrivateAssetMetadata {
27
+ id: string;
28
+ tenantId: string;
29
+ name: string;
30
+ mimeType: string;
31
+ version: number;
32
+ typeSlug: string;
33
+ statusSlug: string;
34
+ createdAt: Date | null;
35
+ updatedAt: Date | null;
36
+ }
37
+ /**
38
+ * Read one private asset's display metadata. The host must authorize the
39
+ * actor's relationship to the asset first. Requires the ambient tenant actor to
40
+ * match the request exactly. Missing, public and other-tenant assets all
41
+ * return `null`. Enforcement stays in the interceptor: the read is a guarded
42
+ * `get` of exactly this id inside a one-id capability that closes on return.
43
+ */
44
+ export declare function readPrivateAssetMetadata(collection: AssetCollection, request: PrivateAssetMetadataRequest): Promise<PrivateAssetMetadata | null>;
14
45
  //# sourceMappingURL=private-asset-access.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"private-asset-access.d.ts","sourceRoot":"","sources":["../src/private-asset-access.ts"],"names":[],"mappings":"AAUA,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAgCD;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAoCZ"}
1
+ {"version":3,"file":"private-asset-access.d.ts","sourceRoot":"","sources":["../src/private-asset-access.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAU,CAAC;AAEhD,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAgCD;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAoCZ;AAkID,+EAA+E;AAC/E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,eAAe,EAC3B,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CA+CtC"}
@@ -3,14 +3,14 @@
3
3
  "sensitiveFieldsExcluded": true,
4
4
  "generatedAt": "1970-01-01T00:00:00.000Z",
5
5
  "packageName": "@happyvertical/smrt-assets",
6
- "packageVersion": "0.57.44",
6
+ "packageVersion": "0.57.45",
7
7
  "sourceManifestPath": "dist/manifest.json",
8
8
  "agentDocPath": "AGENTS.md",
9
9
  "sourceHashes": {
10
- "manifest": "fc89dbea10120f8e69f1355bcab61aa1ef04791992b2a569bc3879311c8e432f",
11
- "packageJson": "de64ea5d3d112781682272aaf25887228973bc4afe50f154c4bca518ff9e1da4",
12
- "agents": "09c9e0e5cbf7ab5e0aff28d489ce15a3d88b003ef4d0137dab43f9210c7752aa",
13
- "moduleDoc:agents/private-assets.md": "8540b9eb31f4e7dd03ff50e213c4ad3f72cbe697298817f71dd7f4f2bf1bfeb9"
10
+ "manifest": "74f620370c7a31193ff38651bf6639fc82a0bc4a9f697f0f34616c4c71521c74",
11
+ "packageJson": "b3554d55c21d3da9d1f15c472be3fb9693466ab3a7da3cd5e2117d1867d979e1",
12
+ "agents": "5e66d98d4e6806b15e8ceddefc00266547374b02d02bab81d72c14f5304403f7",
13
+ "moduleDoc:agents/private-assets.md": "e1a4ab4be7048f29d9e5b0d37d298f13e5a88ae9d988ef3a7cad728e03fb5797"
14
14
  },
15
15
  "exports": [
16
16
  ".",
@@ -3721,12 +3721,12 @@
3721
3721
  "polymorphicAssociations": 1,
3722
3722
  "uuidColumns": 40
3723
3723
  },
3724
- "agentDoc": "# @happyvertical/smrt-assets\n\nProvider-agnostic asset management with versioning, type classification, and generic/provenance associations.\n\n## Models\n\n- **Asset** (STI base): versioning via `primaryVersionId` chain + `version` number. `ownerProfileId`, `typeSlug`, `statusSlug`, `mimeType`, `sourceUri`. Derivation chain via `sourceAssetId` (R3-D — was `parentId` before the rename; column `source_asset_id`).\n- **AssetType** / **AssetStatus**: lookup tables for classification and lifecycle.\n- **AssetMetafield**: custom metadata field definitions with JSON validation rules.\n- **Folder**: hierarchical container for assets. Own `SmrtHierarchical` model with its own `folders` table (R3-D — was an STI subclass of Asset before). `Asset.folderId` points to the folder.\n- **AssetAssociation**: generic/provenance polymorphic join — `assetId` + `metaType` + `metaId` + `role` + `sortOrder`. Use it when a relationship is not owned by a base/domain model join table like `content_assets`, `profile_assets`, `event_assets`, `place_assets`, or `product_assets`.\n\n## Key Patterns\n\n- **Versioning**: `createNewVersion()` increments version, chains via `primaryVersionId`. `findVersions()` to retrieve history.\n- **Tag integration**: `addTag()`/`removeTag()` use raw `db.upsert()` on `asset_tags` join table (not a SMRT model).\n- **AssetStore**: abstraction for provider-agnostic file I/O (S3, local, etc.).\n `planFile(asset, opts)` resolves a recoverable URI before bytes are written;\n persist it before `preserveFile(asset, bytes, opts)`. Preservation adopts equal\n existing bytes and rejects changed bytes, changed resolver targets and read\n failures other than not-found. The caller owns receipt fencing/serialization.\n `removeFile(asset)` removes only bytes for recovery cleanup, including an\n already-pruned owner record; `remove(asset)` also deletes the owner record.\n- **Ownership rule**: base/domain-owned asset relationships should live on noun join tables such as `content_assets`, `profile_assets`, `event_assets`, `place_assets`, and `product_assets`; keep `AssetAssociation` for generic/provenance links like image derivation.\n\n## Runtime surface\n\nApps and agents should depend on the public **asset runtime** rather than hand-wiring a collection + store per-package (#1128).\n\n- `createAssetRuntime({ db, storage })` → `AssetRuntime` bundling `AssetCollection`, `AssetAssociationCollection`, and an initialized `AssetStore`.\n- `AssetRuntime.storeSourceAsset(name, data, opts)` — create a new source asset (record + bytes).\n- `AssetRuntime.storeDerivedAsset(source, name, data, opts)` — create a derivative with `sourceAssetId` set and (by default) a provenance `AssetAssociation` under a chosen role.\n- `AssetRuntime.linkDerivation(source, derivative, { role })` — record provenance without touching bytes.\n- `AssetRuntime.setExtractionStatus(asset, status, { error?, extractedAt? })` — write canonical extraction metadata into the asset's description JSON sidecar. Non-destructive: if `description` is free-form prose or non-object JSON, the original value is preserved under the reserved `text` key instead of being overwritten. Existing JSON objects are merged into.\n\nAgents that need asset I/O should accept an `AssetRuntimeLike` in their options rather than asking callers to pass a store + collection separately.\n\n## Serving contract\n\n- `serveAsset({ runtime, asset, tenantId?, disposition?, canAccess?, headers?, remoteMode? })` → standard Web `Response`.\n - `404` when the id doesn't resolve; `403` when the tenant mismatches or `canAccess` denies; `302` when `remoteMode: 'redirect'` and the asset's `sourceUri` is `http(s)`; `502` when `remoteMode: 'proxy'` and the origin fetch fails; `500` on store read errors or unexpected failures; `200` otherwise with `Content-Type`, `Content-Length`, and `Content-Disposition` set.\n - Assets whose `sourceUri` is `http(s)` are supported via `remoteMode`: `'proxy'` (default, fetch and return bytes), `'redirect'` (302 to the origin), or `'error'` (treat as misconfiguration). Pass `fetchImpl` to swap the fetch client.\n - `Content-Disposition` uses an ASCII-safe quoted `filename` fallback and retains the Unicode download name in UTF-8 `filename*` ([RFC 6266](https://www.rfc-editor.org/rfc/rfc6266#section-4.3), [RFC 8187](https://www.rfc-editor.org/rfc/rfc8187#section-3.2.1)). Both names strip C0/DEL/C1 controls and replace `\"` / `\\` / `/` to prevent header injection; isolated UTF-16 surrogates become U+FFFD before encoding, while valid pairs are preserved.\n - The 500 body is a generic `'Internal error serving asset'`; the underlying error is logged via `console.error` so operators can debug without leaking paths/bucket names to clients.\n - Works in SvelteKit `+server.ts` endpoints, Hono, and any runtime with a global `Response` (Node 18+). Pass `responseCtor` for older runtimes.\n- `resolveAssetForServing(options)` → `{ asset, data, contentType, filename, size }` when callers want to render their own framework response. Throws `AssetServeError(status)` on the same failure modes.\n\n## Source/derived vocabulary\n\nThe following roles are exported as `ASSET_ROLES` and should be preferred over ad-hoc strings when apps want cross-package tooling (serving, UI pickers) to agree on meaning:\n\n| Role | Use |\n|------|-----|\n| `source_document` | original upstream document (agenda PDF, minutes) |\n| `document_image` | page/extracted image derived from a source document |\n| `thumbnail` | preview rendition of another asset |\n| `proof` | non-canonical evidence asset backing a fact |\n| `derivation_source` | \"came from\" link on generated media |\n| `attachment` | generic owner-join link |\n| `hero` | primary/featured asset on an owner |\n\nCanonical metadata keys are exported as `ASSET_METADATA_KEYS`: `extractionStatus`, `extractionError`, `extractedAt`, `sourceUrl`, `sourceHash`, `pageNumber`. Extraction status values live in `ASSET_EXTRACTION_STATUS` (`pending | running | succeeded | failed`).\n\n## UI Registry\n\nThe `./ui` subpath exports `ASSETS_MODULE_META` and `ASSETS_UI_SLOTS` so registry-driven hosts (smrt-chat, dynamic admin shells) can discover the package's Svelte components without a hard import.\n\n```ts\nimport { ASSETS_MODULE_META, ASSETS_UI_SLOTS } from '@happyvertical/smrt-assets/ui';\nimport '@happyvertical/smrt-assets/svelte'; // side-effect: ModuleUIRegistry.register(...)\nimport { ModuleUIRegistry } from '@happyvertical/smrt-ui/registry';\n\nconst AssetManager = ModuleUIRegistry.get('@happyvertical/smrt-assets', 'asset-manager');\n```\n\nRegistered slots: `asset-manager` (admin), `asset-grid` / `asset-list` (list), `asset-detail` (detail), `asset-toolbar` / `asset-action-bar` (action), `asset-create-modal` (form). Slot IDs are stable contracts — host apps reference them by string.\n\n## Gotchas\n\n- **Files SDK is a lazy boundary (#1979)**: `AssetStore` loads `@happyvertical/files` through `src/files-runtime.ts` (bundler-invisible), because smrt-assets is reachable from provider-neutral consumer graphs via profiles. Node/tsx/vite-dev runtimes resolve it on first file operation; fully-bundled deployments import `@happyvertical/smrt-assets/filesystem` at startup. Never import the files SDK statically from modules reachable from `src/index.ts`.\n- **Version history manual**: `findVersions()` chaining required — no ORM shortcut\n- **Tag management uses raw SQL**: `asset_tags` is a join table, not an SMRT model\n- **Folder tree traversal**: via `SmrtHierarchical` (`getParent`/`getChildren`/`getAncestors`/`getDescendants`/`getHierarchy`/`moveTo`); `FolderCollection.getTree(rootId?)` and `getPath(folderId)` wrap these for convenience\n- **AssetAssociation polymorphic FK**: requires manual `metaType` string matching\n- **Optional tenancy**: assets can be global (tenantId=null) or tenant-scoped\n\n## Private records\n\n`Asset.accessMode` and the mandatory owning interceptor protect private records\nacross generated and parent STI surfaces. Use the exact actor/owner/ID capability\nonly after host authorization; see [private assets](agents/private-assets.md).\n",
3724
+ "agentDoc": "# @happyvertical/smrt-assets\n\nProvider-agnostic asset management with versioning, type classification, and generic/provenance associations.\n\n## Models\n\n- **Asset** (STI base): versioning via `primaryVersionId` chain + `version` number. `ownerProfileId`, `typeSlug`, `statusSlug`, `mimeType`, `sourceUri`. Derivation chain via `sourceAssetId` (R3-D — was `parentId` before the rename; column `source_asset_id`).\n- **AssetType** / **AssetStatus**: lookup tables for classification and lifecycle.\n- **AssetMetafield**: custom metadata field definitions with JSON validation rules.\n- **Folder**: hierarchical container for assets. Own `SmrtHierarchical` model with its own `folders` table (R3-D — was an STI subclass of Asset before). `Asset.folderId` points to the folder.\n- **AssetAssociation**: generic/provenance polymorphic join — `assetId` + `metaType` + `metaId` + `role` + `sortOrder`. Use it when a relationship is not owned by a base/domain model join table like `content_assets`, `profile_assets`, `event_assets`, `place_assets`, or `product_assets`.\n\n## Key Patterns\n\n- **Versioning**: `createNewVersion()` increments version, chains via `primaryVersionId`. `findVersions()` to retrieve history.\n- **Tag integration**: `addTag()`/`removeTag()` use raw `db.upsert()` on `asset_tags` join table (not a SMRT model).\n- **AssetStore**: abstraction for provider-agnostic file I/O (S3, local, etc.).\n `planFile(asset, opts)` resolves a recoverable URI before bytes are written;\n persist it before `preserveFile(asset, bytes, opts)`. Preservation adopts equal\n existing bytes and rejects changed bytes, changed resolver targets and read\n failures other than not-found. The caller owns receipt fencing/serialization.\n `removeFile(asset)` removes only bytes for recovery cleanup, including an\n already-pruned owner record; `remove(asset)` also deletes the owner record.\n- **Ownership rule**: base/domain-owned asset relationships should live on noun join tables such as `content_assets`, `profile_assets`, `event_assets`, `place_assets`, and `product_assets`; keep `AssetAssociation` for generic/provenance links like image derivation.\n\n## Runtime surface\n\nApps and agents should depend on the public **asset runtime** rather than hand-wiring a collection + store per-package (#1128).\n\n- `createAssetRuntime({ db, storage })` → `AssetRuntime` bundling `AssetCollection`, `AssetAssociationCollection`, and an initialized `AssetStore`.\n- `AssetRuntime.storeSourceAsset(name, data, opts)` — create a new source asset (record + bytes).\n- `AssetRuntime.storeDerivedAsset(source, name, data, opts)` — create a derivative with `sourceAssetId` set and (by default) a provenance `AssetAssociation` under a chosen role.\n- `AssetRuntime.linkDerivation(source, derivative, { role })` — record provenance without touching bytes.\n- `AssetRuntime.setExtractionStatus(asset, status, { error?, extractedAt? })` — write canonical extraction metadata into the asset's description JSON sidecar. Non-destructive: if `description` is free-form prose or non-object JSON, the original value is preserved under the reserved `text` key instead of being overwritten. Existing JSON objects are merged into.\n\n- `AssetRuntime.getPrivateAssetMetadata({ tenantId, actorUserId, assetId })` → `PrivateAssetMetadata | null` — authorized, tenant-scoped display metadata read of one PRIVATE asset so hosts never read `assets` rows. Trusted server capability (host authorizes first); requires an ambient tenant actor matching `tenantId`/`actorUserId` exactly (throws otherwise, including empty ids). Result is an allowlist (`id, tenantId, name, mimeType, version, typeSlug, statusSlug, createdAt, updatedAt`); never owner, `sourceUri`, description/metadata sidecars. There is no size field on `Asset`. Missing, public and other-tenant assets all return `null`. Internally resolves the owner from the tenant-scoped private row, then reads through the guarded collection inside a one-id `withPrivateAssetAccess` that closes on return; inside an existing scope it can only narrow (throws `cannot widen` otherwise).\n\nAgents that need asset I/O should accept an `AssetRuntimeLike` in their options rather than asking callers to pass a store + collection separately.\n\n## Serving contract\n\n- `serveAsset({ runtime, asset, tenantId?, disposition?, canAccess?, headers?, remoteMode? })` → standard Web `Response`.\n - `404` when the id doesn't resolve; `403` when the tenant mismatches or `canAccess` denies; `302` when `remoteMode: 'redirect'` and the asset's `sourceUri` is `http(s)`; `502` when `remoteMode: 'proxy'` and the origin fetch fails; `500` on store read errors or unexpected failures; `200` otherwise with `Content-Type`, `Content-Length`, and `Content-Disposition` set.\n - Assets whose `sourceUri` is `http(s)` are supported via `remoteMode`: `'proxy'` (default, fetch and return bytes), `'redirect'` (302 to the origin), or `'error'` (treat as misconfiguration). Pass `fetchImpl` to swap the fetch client.\n - `Content-Disposition` uses an ASCII-safe quoted `filename` fallback and retains the Unicode download name in UTF-8 `filename*` ([RFC 6266](https://www.rfc-editor.org/rfc/rfc6266#section-4.3), [RFC 8187](https://www.rfc-editor.org/rfc/rfc8187#section-3.2.1)). Both names strip C0/DEL/C1 controls and replace `\"` / `\\` / `/` to prevent header injection; isolated UTF-16 surrogates become U+FFFD before encoding, while valid pairs are preserved.\n - The 500 body is a generic `'Internal error serving asset'`; the underlying error is logged via `console.error` so operators can debug without leaking paths/bucket names to clients.\n - Works in SvelteKit `+server.ts` endpoints, Hono, and any runtime with a global `Response` (Node 18+). Pass `responseCtor` for older runtimes.\n- `resolveAssetForServing(options)` → `{ asset, data, contentType, filename, size }` when callers want to render their own framework response. Throws `AssetServeError(status)` on the same failure modes.\n\n## Source/derived vocabulary\n\nThe following roles are exported as `ASSET_ROLES` and should be preferred over ad-hoc strings when apps want cross-package tooling (serving, UI pickers) to agree on meaning:\n\n| Role | Use |\n|------|-----|\n| `source_document` | original upstream document (agenda PDF, minutes) |\n| `document_image` | page/extracted image derived from a source document |\n| `thumbnail` | preview rendition of another asset |\n| `proof` | non-canonical evidence asset backing a fact |\n| `derivation_source` | \"came from\" link on generated media |\n| `attachment` | generic owner-join link |\n| `hero` | primary/featured asset on an owner |\n\nCanonical metadata keys are exported as `ASSET_METADATA_KEYS`: `extractionStatus`, `extractionError`, `extractedAt`, `sourceUrl`, `sourceHash`, `pageNumber`. Extraction status values live in `ASSET_EXTRACTION_STATUS` (`pending | running | succeeded | failed`).\n\n## UI Registry\n\nThe `./ui` subpath exports `ASSETS_MODULE_META` and `ASSETS_UI_SLOTS` so registry-driven hosts (smrt-chat, dynamic admin shells) can discover the package's Svelte components without a hard import.\n\n```ts\nimport { ASSETS_MODULE_META, ASSETS_UI_SLOTS } from '@happyvertical/smrt-assets/ui';\nimport '@happyvertical/smrt-assets/svelte'; // side-effect: ModuleUIRegistry.register(...)\nimport { ModuleUIRegistry } from '@happyvertical/smrt-ui/registry';\n\nconst AssetManager = ModuleUIRegistry.get('@happyvertical/smrt-assets', 'asset-manager');\n```\n\nRegistered slots: `asset-manager` (admin), `asset-grid` / `asset-list` (list), `asset-detail` (detail), `asset-toolbar` / `asset-action-bar` (action), `asset-create-modal` (form). Slot IDs are stable contracts — host apps reference them by string.\n\n## Gotchas\n\n- **Files SDK is a lazy boundary (#1979)**: `AssetStore` loads `@happyvertical/files` through `src/files-runtime.ts` (bundler-invisible), because smrt-assets is reachable from provider-neutral consumer graphs via profiles. Node/tsx/vite-dev runtimes resolve it on first file operation; fully-bundled deployments import `@happyvertical/smrt-assets/filesystem` at startup. Never import the files SDK statically from modules reachable from `src/index.ts`.\n- **Version history manual**: `findVersions()` chaining required — no ORM shortcut\n- **Tag management uses raw SQL**: `asset_tags` is a join table, not an SMRT model\n- **Folder tree traversal**: via `SmrtHierarchical` (`getParent`/`getChildren`/`getAncestors`/`getDescendants`/`getHierarchy`/`moveTo`); `FolderCollection.getTree(rootId?)` and `getPath(folderId)` wrap these for convenience\n- **AssetAssociation polymorphic FK**: requires manual `metaType` string matching\n- **Optional tenancy**: assets can be global (tenantId=null) or tenant-scoped\n\n## Private records\n\n`Asset.accessMode` and the mandatory owning interceptor protect private records\nacross generated and parent STI surfaces. Use the exact actor/owner/ID capability\nonly after host authorization; see [private assets](agents/private-assets.md).\nFor display metadata (name, mime type, version) use `AssetRuntime.getPrivateAssetMetadata`\ninstead of reading raw `assets` rows to discover the owner.\n",
3725
3725
  "moduleDocs": [
3726
3726
  {
3727
3727
  "path": "agents/private-assets.md",
3728
3728
  "module": "private-assets",
3729
- "content": "# Private asset records\n\n`Asset.accessMode` is `public` by default: the record is available through ordinary\nasset APIs subject to the existing tenant/authentication checks. It does not mean\nthat the underlying bytes are publicly hosted. `private` records are excluded\nfrom ordinary list/get, projection/count and parent STI hydration, even in system\nor super-admin contexts. The policy is installed by importing Asset itself.\nGenerated REST/MCP updates and deletes cannot discover a private record.\n\nA trusted server may use `withPrivateAssetAccess({ tenantId, actorUserId,\nownerProfileId, assetIds }, callback)` after independently authorizing the actor's\nrelationship to the owning business record. Never expose this capability as a\nrequest option or populate it from arbitrary request JSON. It permits only the\nexact private IDs and owner; ordinary public rows are not included within that\nscope. The current tenant/user must match at each operation. Nested scopes may\nonly narrow IDs with the same owner, and scopes close when their callback ends.\nAwait every operation inside the callback. Async-local storage is resolved lazily\non Node; without that server capability, private scope creation explicitly fails\nand ordinary policy reads remain public-only. This does not promise full package\nbrowser runtime support: existing tenancy dependencies retain their own platform\nlimitations.\n\nPrivate writes require the same capability. Classification and ownership of an\nexisting private record are immutable. Core applies a mandatory persisted-write\npredicate at the final database mutation, including natural-key adoption, so an\nordinary create/upsert cannot overwrite a private record that committed after its\npre-save probe. Guarded new writes never fall back to an unconditional SDK upsert;\na late insert collision can require a caller retry. The instance transaction\nexecutor is used throughout. Raw `AssetCollection.query()` is rejected because\narbitrary SQL cannot reliably preserve the private-row predicate; use the guarded\nlist/get APIs. `findGlobal` and `findWithGlobals` retain their behavior through\nguarded list reads. Direct database access is trusted infrastructure, not an\nuntrusted request API.\n\nPrivate bytes must reside in non-public storage. HTTP(S) source locators are\nrejected for private records; hosts must also configure private bucket/filesystem\nACLs. Hiding a locator cannot protect bytes already publicly accessible. Serving\nroutes must authorize the business relationship, validate their signed claim and\nopen only that exact asset capability before resolving the record.\n\n## Schema and release\n\nThe new `access_mode` column has a `public` default, preserving existing asset\nvisibility after explicit migration. Generate/apply the normal manifest migration\nbefore running the new runtime; runtime checks never create or alter application\nschema. Rebuild assets and downstream manifests. A low-cardinality standalone\nindex on access mode is not added: exact reads use the primary key and scoped\nlists retain their existing tenant predicates/indexes.\n\nEducation captures and split worksheet pages are private from their initial\ntransactional insert. Database metadata is atomic; external bytes use the\neducation service's compensating cleanup contract, not a distributed transaction.\n"
3729
+ "content": "# Private asset records\n\n`Asset.accessMode` is `public` by default: the record is available through ordinary\nasset APIs subject to the existing tenant/authentication checks. It does not mean\nthat the underlying bytes are publicly hosted. `private` records are excluded\nfrom ordinary list/get, projection/count and parent STI hydration, even in system\nor super-admin contexts. The policy is installed by importing Asset itself.\nGenerated REST/MCP updates and deletes cannot discover a private record.\n\nA trusted server may use `withPrivateAssetAccess({ tenantId, actorUserId,\nownerProfileId, assetIds }, callback)` after independently authorizing the actor's\nrelationship to the owning business record. Never expose this capability as a\nrequest option or populate it from arbitrary request JSON. It permits only the\nexact private IDs and owner; ordinary public rows are not included within that\nscope. The current tenant/user must match at each operation. Nested scopes may\nonly narrow IDs with the same owner, and scopes close when their callback ends.\nAwait every operation inside the callback. Async-local storage is resolved lazily\non Node; without that server capability, private scope creation explicitly fails\nand ordinary policy reads remain public-only. This does not promise full package\nbrowser runtime support: existing tenancy dependencies retain their own platform\nlimitations.\n\nHosts that only need display metadata call `runtime.getPrivateAssetMetadata({\ntenantId, actorUserId, assetId })` after the same host authorization. It resolves\nthe owner internally, performs a guarded read of exactly that one ID, and returns\nan allowlisted projection (never owner, `sourceUri`, description or metadata) or\n`null` for missing, public and other-tenant assets. It never exposes the\ncapability.\n\nPrivate writes require the same capability. Classification and ownership of an\nexisting private record are immutable. Core applies a mandatory persisted-write\npredicate at the final database mutation, including natural-key adoption, so an\nordinary create/upsert cannot overwrite a private record that committed after its\npre-save probe. Guarded new writes never fall back to an unconditional SDK upsert;\na late insert collision can require a caller retry. The instance transaction\nexecutor is used throughout. Raw `AssetCollection.query()` is rejected because\narbitrary SQL cannot reliably preserve the private-row predicate; use the guarded\nlist/get APIs. `findGlobal` and `findWithGlobals` retain their behavior through\nguarded list reads. Direct database access is trusted infrastructure, not an\nuntrusted request API.\n\nPrivate bytes must reside in non-public storage. HTTP(S) source locators are\nrejected for private records; hosts must also configure private bucket/filesystem\nACLs. Hiding a locator cannot protect bytes already publicly accessible. Serving\nroutes must authorize the business relationship, validate their signed claim and\nopen only that exact asset capability before resolving the record.\n\n## Schema and release\n\nThe new `access_mode` column has a `public` default, preserving existing asset\nvisibility after explicit migration. Generate/apply the normal manifest migration\nbefore running the new runtime; runtime checks never create or alter application\nschema. Rebuild assets and downstream manifests. A low-cardinality standalone\nindex on access mode is not added: exact reads use the primary key and scoped\nlists retain their existing tenant predicates/indexes.\n\nEducation captures and split worksheet pages are private from their initial\ntransactional insert. Database metadata is atomic; external bytes use the\neducation service's compensating cleanup contract, not a distributed transaction.\n"
3730
3730
  }
3731
3731
  ],
3732
3732
  "recipes": [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@happyvertical/smrt-assets",
3
- "version": "0.57.44",
3
+ "version": "0.57.45",
4
4
  "smrtJsdoc": "strict",
5
5
  "description": "Asset management system with versioning, metadata, and AI-powered operations for SMRT framework",
6
6
  "type": "module",
@@ -48,11 +48,11 @@
48
48
  "@happyvertical/ai": "^0.111.0",
49
49
  "@happyvertical/files": "^0.111.0",
50
50
  "@happyvertical/logger": "^0.111.0",
51
- "@happyvertical/smrt-core": "0.57.44",
52
- "@happyvertical/smrt-tags": "0.57.44",
53
- "@happyvertical/smrt-tenancy": "0.57.44",
54
- "@happyvertical/smrt-types": "0.57.44",
55
- "@happyvertical/smrt-ui": "0.57.44",
51
+ "@happyvertical/smrt-core": "0.57.45",
52
+ "@happyvertical/smrt-tags": "0.57.45",
53
+ "@happyvertical/smrt-tenancy": "0.57.45",
54
+ "@happyvertical/smrt-types": "0.57.45",
55
+ "@happyvertical/smrt-ui": "0.57.45",
56
56
  "@happyvertical/sql": "^0.111.0",
57
57
  "@happyvertical/utils": "^0.111.0"
58
58
  },
@@ -65,8 +65,8 @@
65
65
  }
66
66
  },
67
67
  "devDependencies": {
68
- "@happyvertical/smrt-playground": "0.57.44",
69
- "@happyvertical/smrt-vitest": "0.57.44",
68
+ "@happyvertical/smrt-playground": "0.57.45",
69
+ "@happyvertical/smrt-vitest": "0.57.45",
70
70
  "@sveltejs/adapter-auto": "^7.0.1",
71
71
  "@sveltejs/kit": "2.69.1",
72
72
  "@sveltejs/package": "^2.5.8",