@happyvertical/smrt-profiles 0.55.9 → 0.55.10

package/dist/manifest.json

@@ -2,7 +2,7 @@
   "version": "1.0.0",
   "timestamp": 0,
   "packageName": "@happyvertical/smrt-profiles",
-  "packageVersion": "0.55.9",
+  "packageVersion": "0.55.10",
   "objects": {
     "@happyvertical/smrt-profiles:ApiKeyCollection": {
       "name": "apikeycollection",
@@ -9615,6 +9615,77 @@
     }
   },
   "moduleType": "smrt",
+  "recipes": [
+    {
+      "id": "profiles.audit-log",
+      "className": "AuditLogRecipe",
+      "label": "Activity log",
+      "summary": "Review who changed a record and when.",
+      "synonyms": [
+        "audit trail",
+        "record history",
+        "activity"
+      ],
+      "models": [
+        "@happyvertical/smrt-profiles:AuditLog"
+      ],
+      "nav": [],
+      "requires": [],
+      "group": {
+        "id": "activity",
+        "label": "Activity",
+        "summary": "Review authorized record history independently of messaging."
+      },
+      "section": {
+        "id": "activity",
+        "label": "Activity",
+        "icon": "book",
+        "description": "See who changed records and why."
+      },
+      "help": {
+        "markdown": "## Activity log\nReview changes to records you are authorized to inspect. Each activity shows the actor, action, time, and recorded reason or resource.\nOpen the related record when your application provides a link.\n\n## Record history\nThe application enables auditing on selected models and authorizes audit reads. Only recorded events appear; enabling auditing does not reconstruct earlier changes.\nSensitive audit details are available only through the application's authorized history service.\n",
+        "fieldRefs": []
+      },
+      "surfaces": [
+        {
+          "kind": "route",
+          "path": "/activity",
+          "export": "@happyvertical/smrt-svelte#ActivityList",
+          "label": "Activity log"
+        }
+      ],
+      "providers": [
+        {
+          "id": "audit-trail",
+          "kind": "activity",
+          "options": [
+            "audit-log"
+          ],
+          "required": true
+        }
+      ],
+      "runtime": "both",
+      "demoSeed": {
+        "data": {
+          "entries": [
+            {
+              "id": "demo-audit",
+              "title": "Demo colleague · updated",
+              "detail": "Approved a fictional record.",
+              "occurredAt": "2026-01-01T12:00:00Z",
+              "href": null
+            }
+          ]
+        }
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package does not build for a browser: node:crypto in root; core migrations (node:os); and its package depends on @happyvertical/smrt-tenancy, which do not build for a browser (#3617, #3624, #3626)."
+        ]
+      }
+    }
+  ],
   "smrtDependencies": [
     "@happyvertical/smrt-assets",
     "@happyvertical/smrt-core",

package/dist/recipes.d.ts

@@ -0,0 +1,48 @@
+import { SmrtRecipe } from '@happyvertical/smrt-core';
+import { AuditLog } from './models/AuditLog.js';
+/** Authorized record history in the application activity feed. */
+export declare class AuditLogRecipe extends SmrtRecipe {
+    static id: string;
+    static label: string;
+    static summary: string;
+    static synonyms: string[];
+    static group: {
+        id: string;
+        label: string;
+        summary: string;
+    };
+    static section: {
+        id: string;
+        label: string;
+        icon: string;
+        description: string;
+    };
+    static models: (typeof AuditLog)[];
+    static runtime: "both";
+    static surfaces: readonly [{
+        readonly kind: "route";
+        readonly path: "/activity";
+        readonly export: "@happyvertical/smrt-svelte#ActivityList";
+        readonly label: "Activity log";
+    }];
+    static providers: {
+        id: string;
+        kind: string;
+        options: string[];
+        required: boolean;
+    }[];
+    static demoSeed: {
+        data: {
+            entries: {
+                id: string;
+                title: string;
+                detail: string;
+                occurredAt: string;
+                href: null;
+            }[];
+        };
+    };
+    static nav: never[];
+    static help: string;
+}
+//# sourceMappingURL=recipes.d.ts.map

package/dist/recipes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipes.d.ts","sourceRoot":"","sources":["../src/recipes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,kEAAkE;AAClE,qBAAa,cAAe,SAAQ,UAAU;IAC5C,MAAM,CAAC,EAAE,SAAwB;IACjC,MAAM,CAAC,KAAK,SAAkB;IAC9B,MAAM,CAAC,OAAO,SAA2C;IACzD,MAAM,CAAC,QAAQ,WAAiD;IAChE,MAAM,CAAC,KAAK;;;;MAIV;IACF,MAAM,CAAC,OAAO;;;;;MAKZ;IACF,MAAM,CAAC,MAAM,sBAAc;IAC3B,MAAM,CAAC,OAAO,EAAG,MAAM,CAAU;IACjC,MAAM,CAAC,QAAQ;;;;;OAOJ;IACX,MAAM,CAAC,SAAS;;;;;QAOd;IACF,MAAM,CAAC,QAAQ;;;;;;;;;;MAYb;IAEF,MAAM,CAAC,GAAG,UAAM;IAChB,MAAM,CAAC,IAAI,SAAyB;CACrC"}

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-profiles",
-  "packageVersion": "0.55.9",
+  "packageVersion": "0.55.10",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "d1dfe9ba29cc27f0bc29a720d1fe5a26c766e5c6e0188a0faba0386ee316c328",
-    "packageJson": "c4fac9a7f9f8d195579866a479bcb65171d4fc9855961348193028e761e86c9d",
+    "manifest": "816ac2484000aace8a2ddb52993c95f6b5ae761f42b44ca01ba7aecc2bf5ea21",
+    "packageJson": "e01adfd5a4a28b77a5032d76bd960e9ac6be3af8aa2a77266e8da328455d7108",
     "agents": "6f73ea6628f32d4799d6c0f9da4ab98a2ae7c5e7e43e2554b8d874233789e170"
   },
   "exports": [
@@ -14236,6 +14236,77 @@
     "uuidColumns": 91
   },
   "agentDoc": "# @happyvertical/smrt-profiles\n\nCentral identity system with multi-auth, relationships, controlled metadata, and audit logging.\n\n## Models\n\n- **Profile** (STI base → Bot, Organization, Person): email (optional; identity uniqueness is arbitrated by `oidc_profile_email_reservations.email_key`, not a DB constraint — legacy duplicates are tolerated and fail closed, #2359), readonly indexed `emailKey` derived with `normalizeIdentityEmail()` for adapter-independent identity lookup, `typeId` FK to ProfileType, plus a `metadata` `@oneToMany('ProfileMetadata')` relationship for controlled per-profile values.\n- **ProfileAsset**: dedicated owned-asset join in `profile_assets` with `relationship` and `sortOrder`.\n- **ProfileLink**: ordered web links in `profile_links` (`platform` from `PROFILE_LINK_PLATFORMS`, validated http(s) `url`, optional `label`, `sortOrder`). `profileId` FK is `onDelete: 'CASCADE'`. Slug is the id (never url/label, so a new link cannot adopt another row through the natural key). Write through `ProfileLinkCollection.replaceForProfile()` / `reorder()` (one transaction each; resolve the profile in the current tenant context and stamp its tenant) or `Profile.setLinks()` / `getLinks()`.\n- **Profile.isPublic**: optional public-figure flag (boolean, default false). Records the fact only; consumers decide visibility.\n- **ProfileRelationship**: bidirectional — creating one auto-creates reciprocal inverse. `contextProfileId` for tertiary relationships. `ProfileRelationshipTerm` tracks start/end dates.\n- **ProfileMetafield**: controlled vocabulary with `validationSchema`. **ProfileMetadata**: per-profile values linked to metafields. `addMetadata()` stamps new rows with the profile's `tenantId` (never rely on auto-population, which super-admin/system context skips, #3235) and resolves the metafield as profile-tenant first, then global, never another tenant's.\n- **AuditLog**: sensitive audit persistence with actor, action, reason, before/after `changes`, indexed `occurredAt`, resourceType/Id, source, and delegated identity. No generated read routes. `createAuditWriter`, consumer-authorized `readAuditTrail`, and bounded `pruneAuditTrail` live in `src/audit-trail.ts`; see [audit contract](../../docs/content/audit-trail.md).\n\n## Auth Methods\n\n| Model | Pattern |\n|-------|---------|\n| NostrIdentity | Encrypted keypair (AES-256-GCM). Requires `SERVER_MASTER_SECRET` env var for decryption. NIP-05 address generation. |\n| OidcIdentity | Multiple issuers (Keycloak/Google/GitHub). Lookup by `issuer + subject` pair. Transactional provisioning derives the readonly nullable unique `identityKey` and backfills legacy rows. |\n| ApiKey | SHA-256 hashed. **Plaintext returned once only** on `generate()`. `keyPrefix` for identification. Scope-based with expiry. |\n| MagicLinkToken | One-time token with expiry for passwordless auth. |\n\n## Identity Resolution\n\nAuth helpers in `src/auth/` build profiles from external identity claims:\n\n- `resolveIdentity()` — top-level dispatcher that returns/creates a Profile from Nostr signatures, OIDC claims, magic link tokens, or API keys.\n- `createProfileFromOidc(claims, provider, options)` — creates `Profile` + `OidcIdentity` for first-time OIDC sign-in using a transaction-capable root database in `options.db`.\n- `ProfileCollection.findUniqueGlobalPersonByEmail(email)` — supported\n  verified-identity lookup; fails closed on tenant-scoped, non-Person, or\n  duplicate case-insensitive matches.\n- `ProfileCollection.requireCanonicalGlobalPerson(profileId, email?)` —\n  validates an application-selected Profile against the same canonical global\n  Person invariant.\n- `ProfileCollection.reserveCanonicalIdentityEmail(profileId, email?)` —\n  validates and synchronizes the private unique\n  `oidc_profile_email_reservations.email_key` used as the database arbiter for\n  concurrent external-identity provisioning. Omitting `email` uses the\n  Profile's stored address, moving or removing an existing reservation as the\n  canonical Profile changes.\n- `createProfileFromNostr(email, nostrData)` — creates `Profile` + `NostrIdentity` for Nostr-authenticated users.\n\n## Agent (bot) profiles (#2995)\n\nAn automated agent is an author, and every authoring seam in the framework\n(`ChatMessage.senderProfileId`, `ChatParticipant.profileId`, a persona's\n`actsAsProfileId`) is a `crossPackageRef` to `Profile` — a native uuid column on\nPostgreSQL/DuckDB. A slug-style agent id is therefore not a representable author\n(`22P02`). `src/agent-profile.ts` is the owning-package API that turns one into\na real Profile so no consumer mints bot profiles itself and no uuid column is\nweakened to text:\n\n- `resolveAgentProfile(profiles, { agentId, tenantId, name? })` /\n  `resolveAgentProfileId(...)` — resolve, creating on first use, the `bot`\n  Profile an agent authors as. Idempotent and tenant-bound: identity is keyed on\n  `(tenantId, slug = agentId, context = AGENT_PROFILE_CONTEXT)`, matching the\n  model's `(tenant_id, slug, context, _meta_type)` unique key, so an agent id\n  resolves to a distinct profile per tenant and never collides with a\n  person/organization sharing the slug. Classification is the `bot` ProfileType\n  (`AGENT_PROFILE_TYPE_SLUG`), created on demand. Parallel first use converges\n  on the natural key rather than on whoever's INSERT won (each attempt re-reads\n  before and after writing), which matters because NULLs are distinct in the\n  `(tenant_id, slug, context)` unique index, so an untenanted agent is not\n  arbitrated by the database (smrt#2360). Pinned against real PostgreSQL by\n  `src/__tests__/agent-profile-postgres.test.ts`\n  (`pnpm --filter @happyvertical/smrt-profiles test:postgres`).\n\nFirst consumer: `@happyvertical/smrt-chat`'s `ChatService`.\n\n## Key Methods\n\n- `Profile.getAssets()` / `addAsset()` / `removeAsset()` and the matching `ProfileCollection` wrappers — canonical owned asset helpers backed by `profile_assets`.\n- `Profile.addMetadata(metafieldSlug, value)` / `Profile.getMetadata()` — validates against metafield schema. `ProfileCollection.batchGetMetadata()` / `batchUpdateMetadata()` for bulk reads/writes.\n- `Profile.getRelationships({ direction: 'from'|'to'|'all' })` — direction matters.\n- `Profile.getRelationshipsFrom()` / `getRelationshipsTo()` — R10-generated `@oneToMany` accessors. ProfileRelationship has two FKs back to Profile, so each `@oneToMany` annotates its inverse explicitly (`{ foreignKey: 'fromProfileId' }` / `'toProfileId'`). Return raw `ProfileRelationship[]`; use `getRelationships()` for slug/direction filtering.\n- AI: `generateBio()` (uses `smrtProfiles.profile.generateBio` prompt via `@happyvertical/smrt-prompts`), `matches(criteria)` (delegates to `is()`).\n\n## Prompt Registry\n\n`generateBio()` is registered with `@happyvertical/smrt-prompts` so tenants can override template/model/params at runtime:\n\n```typescript\nimport { smrtProfilesGenerateBioPrompt } from '@happyvertical/smrt-profiles';\n// key: 'smrtProfiles.profile.generateBio'\n```\n\n## Gotchas\n\n- **SERVER_MASTER_SECRET required** for Nostr private key decryption — centralized key management\n- **API key never returned again**: `ApiKey.generate()` returns plaintext once; only `keyPrefix` visible later\n- **OIDC unique per issuer+subject**: same subject from different issuers =\n  different identities. Both claims are opaque and case-sensitive; preserve\n  exact whitespace after using trim only to reject blank values.\n- **OIDC identity mutations are trusted-only**: generated REST, MCP, and CLI\n  surfaces are read-only. Link or update identities through transactional\n  provisioning APIs so callers cannot rebind issuer/subject authority to an\n  arbitrary Profile. Deprecated `OidcIdentity.findOrCreate()` preserves only\n  transaction-safe exact-link reuse and refuses to create new links;\n  `OidcIdentityCollection.linkToProfile()` and `Profile.linkOidcIdentity()`\n  delegate to that same non-creating compatibility path.\n- **Apply schema migrations for identity race keys**: run `smrt db:status`,\n  `smrt db:migrate`, then `smrt db:status` before deploying. Transactional OIDC\n  provisioning populates `OidcIdentity.identityKey` and\n  `oidc_profile_email_reservations`; legacy rows reserve an address only after\n  safe validation. Stop/upgrade old Profile writers, then run the public,\n  transactional and idempotent `backfillProfileEmailKeys(db)` from one deploy\n  process. Verified-email provisioning and public email-key lookup require the\n  standard `_smrt_backfills` readiness marker and fail closed immediately when\n  it is absent. This keeps table scans in the explicit deploy step; runtime\n  reads use the indexed key and validate only returned candidates.\n- **Public OIDC provisioning requires transactions**:\n  `createProfileFromOidc()` owns a root transaction or uses a savepoint on an\n  already-bound handle. Root adapters must expose `beginTransaction`;\n  transaction-only handles are ambiguous and fail closed. Pass the root\n  database for adapters without nested savepoints, including DuckDB;\n  provisioning fails before durable writes if neither path is safe. Trusted\n  framework packages use the private\n  `@happyvertical/smrt-profiles/internal/oidc-provisioning` subpath instead of\n  duplicating adapter probing, locking, or retry policy, and supply both exact\n  issuer/subject and normalized-email lock keys in deterministic order. The\n  coordinator additionally serializes every root-handle statement it owns per\n  database URL on SQLite/DuckDB — shared `_smrt_backfills` initialization, the\n  provisioning transaction, and the post-commit rebind — because those adapters\n  multiplex one native connection and cannot overlap unrelated root\n  transactions safely. **Never overlap two statements on one such handle,\n  transaction-bound or not** — no `Promise.all` over reads, not even\n  primary-key rebinds — because DuckDB fails the losing prepared statement or\n  aborts the process outright. It retries\n  bounded PostgreSQL deadlock/serialization failures. New OIDC Profiles use per-profile,\n  non-semantic slugs so duplicate display names never invoke natural-key upsert.\n  Caller-owned transactions never execute `_smrt_backfills` DDL; paths that\n  perform canonical email lookup or reservation require the table to already\n  exist or the caller must retry with the root database. Exact issuer/subject\n  reuse skips the email-key readiness-marker lookup, but root coordination still\n  initializes the shared tracker table. Caller-owned exact reuse does not\n  consult the tracker and therefore does not require that table.\n- **Profile-only OIDC linking fails closed on existing email matches**:\n  the typed canonical scenario contract is\n  `src/testing/oidcProvisioningDecisionMatrix.ts`, executed by both Profiles\n  and Users tests; keep public docs pointed at it instead of adding a second\n  behavioral table.\n  `createProfileFromOidc()` preserves exact issuer/subject reuse, including\n  legacy tenant-scoped and non-Person links, but profiles cannot prove whether a\n  User owns a same-email Profile. New identities therefore never attach to an\n  existing email match through this helper; User/session provisioning still\n  rejects unsafe linked Profiles before creating authentication state. Use\n  `UserCollection.getOrCreateFromOidc()` for owner-aware verified-email reuse and\n  its supported transaction-bound hooks. A pre-provisioned owned Person remains\n  fail-closed unless the application explicitly uses `authorizeProfileOwner`\n  to select both the canonical Profile and its existing approved sole owner;\n  the users package revalidates those IDs, emails, and identity authority in\n  the provisioning transaction.\n- **Email storage and identity matching differ**: `Profile.email` has an\n  exact-value DB constraint. Identity boundaries query readonly indexed\n  `Profile.emailKey`, derived by the shared TypeScript\n  `normalizeIdentityEmail()` helper rather than adapter-specific SQL casing or\n  trimming, and deliberately fail closed on duplicate normalized keys.\n- **Manifest objects must remain root-importable**: the non-API\n  `OidcProfileEmailReservation` model and collection are public root exports\n  because generated consumer registration imports every advertised manifest\n  symbol from `@happyvertical/smrt-profiles`. Release-pack validation imports\n  the actual generated register file from the packed tarball.\n- **Optional tenancy** on Profile; AuditLog allows super-admin bypass\n",
+  "recipes": [
+    {
+      "id": "profiles.audit-log",
+      "className": "AuditLogRecipe",
+      "label": "Activity log",
+      "summary": "Review who changed a record and when.",
+      "synonyms": [
+        "audit trail",
+        "record history",
+        "activity"
+      ],
+      "models": [
+        "@happyvertical/smrt-profiles:AuditLog"
+      ],
+      "nav": [],
+      "requires": [],
+      "group": {
+        "id": "activity",
+        "label": "Activity",
+        "summary": "Review authorized record history independently of messaging."
+      },
+      "section": {
+        "id": "activity",
+        "label": "Activity",
+        "icon": "book",
+        "description": "See who changed records and why."
+      },
+      "help": {
+        "markdown": "## Activity log\nReview changes to records you are authorized to inspect. Each activity shows the actor, action, time, and recorded reason or resource.\nOpen the related record when your application provides a link.\n\n## Record history\nThe application enables auditing on selected models and authorizes audit reads. Only recorded events appear; enabling auditing does not reconstruct earlier changes.\nSensitive audit details are available only through the application's authorized history service.\n",
+        "fieldRefs": []
+      },
+      "surfaces": [
+        {
+          "kind": "route",
+          "path": "/activity",
+          "export": "@happyvertical/smrt-svelte#ActivityList",
+          "label": "Activity log"
+        }
+      ],
+      "providers": [
+        {
+          "id": "audit-trail",
+          "kind": "activity",
+          "options": [
+            "audit-log"
+          ],
+          "required": true
+        }
+      ],
+      "runtime": "both",
+      "demoSeed": {
+        "data": {
+          "entries": [
+            {
+              "id": "demo-audit",
+              "title": "Demo colleague · updated",
+              "detail": "Approved a fictional record.",
+              "occurredAt": "2026-01-01T12:00:00Z",
+              "href": null
+            }
+          ]
+        }
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package does not build for a browser: node:crypto in root; core migrations (node:os); and its package depends on @happyvertical/smrt-tenancy, which do not build for a browser (#3617, #3624, #3626)."
+        ]
+      }
+    }
+  ],
   "browser": {
     "status": "server-only",
     "issues": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-profiles",
-  "version": "0.55.9",
+  "version": "0.55.10",
   "description": "Profile management system with relationships, metadata, and reciprocal associations for SMRT framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,10 +30,10 @@
     "@happyvertical/ai": "^0.103.1",
     "@happyvertical/files": "^0.103.1",
     "@happyvertical/logger": "^0.103.1",
-    "@happyvertical/smrt-assets": "0.55.9",
-    "@happyvertical/smrt-core": "0.55.9",
-    "@happyvertical/smrt-prompts": "0.55.9",
-    "@happyvertical/smrt-tenancy": "0.55.9",
+    "@happyvertical/smrt-assets": "0.55.10",
+    "@happyvertical/smrt-core": "0.55.10",
+    "@happyvertical/smrt-prompts": "0.55.10",
+    "@happyvertical/smrt-tenancy": "0.55.10",
     "@happyvertical/sql": "^0.103.1",
     "@happyvertical/utils": "^0.103.1",
     "@noble/curves": "^2.4.0",
@@ -41,7 +41,7 @@
   },
   "devDependencies": {
     "@faker-js/faker": "^10.6.0",
-    "@happyvertical/smrt-vitest": "0.55.9",
+    "@happyvertical/smrt-vitest": "0.55.10",
     "@types/node": "24.13.6",
     "fast-glob": "3.3.3",
     "typescript": "6.0.3",