@happyvertical/smrt-cli 0.60.9 → 0.60.11

package/dist/knowledge/intents/relationships-and-trees.md

@@ -0,0 +1,56 @@
+---
+type: Capability
+title: "Polymorphic links, junctions and trees"
+description: "Extend SmrtJunction, SmrtHierarchical and SmrtPolymorphicAssociation instead of writing link tables, parent_id traversal or type/id pairs by hand."
+tags:
+  - smrt
+  - intent
+status: draft
+generated:
+  by: claude/smrt-4687
+  at: 2026-11-05T00:00:00Z
+stale_after: 2027-02-03T00:00:00Z
+audience: internal
+evidence_level: source-inspected
+package_version: 0.60.8
+sources:
+  - id: s1
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/hierarchical.ts
+    path: packages/core/src/hierarchical.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/hierarchical.ts (SmrtHierarchical.moveTo, getDescendants)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/junction.ts
+    path: packages/core/src/junction.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/junction.ts (SmrtJunction.attach, setLinks)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/polymorphic-association.ts
+    path: packages/core/src/polymorphic-association.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/polymorphic-association.ts (SmrtPolymorphicAssociation)"
+---
+
+# Polymorphic links, junctions and trees
+
+# Entry point
+
+All three are exported from `@happyvertical/smrt-core`. Trees: `class Place extends SmrtHierarchical` (a `parentId` self-reference) gives `getAncestors()`, `getDescendants()`, `getHierarchy()` and a cycle-checked `moveTo()`. Many-to-many: a collection extending `SmrtJunction` declares `leftField`/`rightField` and gets `attach()`, `detach()`, `byLeft()`, `byRight()` and `setLinks()`; composite-key owners extend `SmrtJunctionBase`. Links to any model: `class CommentAssociation extends SmrtPolymorphicAssociation` stores `metaType` (qualified class name), `metaId` and `role`, and `hydrate()` resolves the target through the registry. Classes whose self-reference means something else (an evolution chain, a derivation DAG) must not extend `SmrtHierarchical`.
+
+# Why not hand-roll it
+
+`SmrtHierarchical.moveTo()` in `hierarchical.ts` refuses to move a node to itself or beneath one of its own descendants before it saves, which a bare `parentId` update does not, and traversal is breadth-first with one batched query per level.[^s1] `SmrtJunction.attach()` in `junction.ts` spreads caller options first so the fixed left and right keys always win and untrusted options cannot retarget the write, and it upserts on the model's `conflictColumns` (with the documented caveat that a duplicate rewrites the row id); `setLinks()` replaces a left id's full set and is documented as not transactional.[^s2] `SmrtPolymorphicAssociation` keeps `metaId` a bare string with `metaType` resolved through `ObjectRegistry`, rather than an untyped foreign key per target.[^s3]
+
+# Component pages
+
+- [smrt-core](/components/smrt-core.md)
+
+# Detection signals
+
+- `regex:parent_?[iI]d\s*[:=]`
+- `regex:WITH RECURSIVE`
+- `regex:entity_?type`
+
+[^s1]: `packages/core/src/hierarchical.ts` at `478ae36900`: SmrtHierarchical.moveTo, getDescendants.
+[^s2]: `packages/core/src/junction.ts` at `478ae36900`: SmrtJunction.attach, setLinks.
+[^s3]: `packages/core/src/polymorphic-association.ts` at `478ae36900`: SmrtPolymorphicAssociation.

package/dist/knowledge/intents/scheduled-runs.md

@@ -0,0 +1,61 @@
+---
+type: Capability
+title: "Scheduled and recurring runs"
+description: "Reach for the smrt-jobs ScheduleRunner and smrt-agents AgentSchedule before writing a cron loop or setInterval poller."
+tags:
+  - smrt
+  - intent
+status: draft
+generated:
+  by: claude/smrt-4687
+  at: 2026-11-05T00:00:00Z
+stale_after: 2027-02-03T00:00:00Z
+audience: internal
+evidence_level: source-inspected
+package_version: 0.60.8
+sources:
+  - id: s1
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/jobs/src/schedule-runner.ts
+    path: packages/jobs/src/schedule-runner.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/jobs/src/schedule-runner.ts (ScheduleRunner.triggerSchedule, validateCronExpression, getNextCronDate)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/agents/src/schedule.ts
+    path: packages/agents/src/schedule.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/agents/src/schedule.ts (AgentSchedule, getNextCronDate import)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/jobs/src/index.ts
+    path: packages/jobs/src/index.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/jobs/src/index.ts (ScheduleRunner, SCHEDULED_JOB_QUEUE exports)"
+---
+
+# Scheduled and recurring runs
+
+# Entry point
+
+Schedules are rows, not code. Define an `AgentSchedule` (`@happyvertical/smrt-agents`: agent type, method, args, 5-field `cron`, IANA `timezone`, optional `tenantId`) and run one `ScheduleRunner` (`createScheduleRunner()` from `@happyvertical/smrt-jobs`). Each due schedule is turned into a `SmrtJob` on the `SCHEDULED_JOB_QUEUE`, so a scheduled run gets the same retries, tenant cap and recovery as any other background job (see [background-work](/intents/background-work.md)). `validateCronExpression()` and `getNextCronDate()` are exported for write-time validation.[^s3]
+
+# Why not hand-roll it
+
+`ScheduleRunner.triggerSchedule()` in `schedule-runner.ts` validates the cron and time zone first and moves a schedule with an invalid expression to `status = 'error'` instead of retrying it on every poll; it then enqueues the job before advancing `next_run`, so a transient failure (a tenant-cap hit, a database blip) leaves the due slot to be retried rather than silently losing the run (#1401), and it enqueues through `enqueueJob` so the per-tenant cap and retry ceiling apply (#1402).[^s1] Cron is evaluated in the row's IANA zone with UTC as the default, never the host process zone (#3859).[^s1] `AgentSchedule.calculateNextRun()` imports `getNextCronDate` from smrt-jobs so the model and the runner cannot compute different next-run times.[^s2] A hand-written `setInterval` loop has none of this.
+
+# Component pages
+
+- [smrt-jobs](/components/smrt-jobs.md)
+- [smrt-agents](/components/smrt-agents.md)
+
+# Detection signals
+
+- `import:node-cron`
+- `import:cron`
+- `import:node-schedule`
+- `import:agenda`
+- `import:croner`
+- `call:setInterval`
+- `regex:cron\.schedule\(`
+
+[^s1]: `packages/jobs/src/schedule-runner.ts` at `478ae36900`: ScheduleRunner.triggerSchedule, validateCronExpression, getNextCronDate.
+[^s2]: `packages/agents/src/schedule.ts` at `478ae36900`: AgentSchedule, getNextCronDate import.
+[^s3]: `packages/jobs/src/index.ts` at `478ae36900`: ScheduleRunner, SCHEDULED_JOB_QUEUE exports.

package/dist/knowledge/intents/search-facts-knowledge.md

@@ -0,0 +1,68 @@
+---
+type: Capability
+title: "Search, facts and extracted knowledge"
+description: "Reach for core semanticSearch, smrt-facts reconciliation and smrt-ingestion before writing embedding search or a facts table."
+tags:
+  - smrt
+  - intent
+status: draft
+generated:
+  by: claude/smrt-4687
+  at: 2026-11-05T00:00:00Z
+stale_after: 2027-02-03T00:00:00Z
+audience: internal
+evidence_level: source-inspected
+package_version: 0.60.8
+sources:
+  - id: s1
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/facts/src/facts.ts
+    path: packages/facts/src/facts.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/facts/src/facts.ts (FactCollection.reconcile)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/collection.ts
+    path: packages/core/src/collection.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/collection.ts (SmrtCollection.findSimilarToEmbedding, semanticSearch)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/embeddings/storage.ts
+    path: packages/core/src/embeddings/storage.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/embeddings/storage.ts (EmbeddingStorage.searchSimilar)"
+  - id: s4
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/ingestion/AGENTS.md
+    path: packages/ingestion/AGENTS.md
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/ingestion/AGENTS.md (ingestion invariants)"
+---
+
+# Search, facts and extracted knowledge
+
+# Entry point
+
+Search: any SmrtCollection with embeddings configured exposes `semanticSearch(query, options)` (core). Knowledge: `FactCollection.reconcile(options)` from `@happyvertical/smrt-facts` decides whether new text creates, merges into or branches an existing `Fact`, with provenance in `FactSource`, entity links in `FactSubject` and document links in `FactContent` (to smrt-content `Content`). Extraction pipelines: smrt-ingestion owns sources, extraction attempts, proposals, review and execution; server-only services are under its `/server` subpath and generated mutation routes are disabled.
+
+# Why not hand-roll it
+
+`FactCollection.reconcile()` in `facts.ts` serializes under a PostgreSQL advisory lock keyed on the reconciliation identity and applies three zones over embedding similarity: at or above 0.85 merge (add a source, bump `sourceCount`), between 0.60 and 0.85 a typed decision or AI disambiguation, below 0.60 create.[^s1] In core, `findSimilarToEmbedding()` runs the tenant interceptor's list prefilter and ranks only that tenant's ids through `EmbeddingStorage.searchSimilar(..., { objectIds })`, where an empty id set returns no results rather than falling through to an unrestricted search, because `_smrt_embeddings` has no tenant column.[^s2][^s3] The ingestion package requires a tenant and confidentiality scope on every record and keeps analysis input, attempts, proposals and decisions append-only.[^s4] A hand-rolled vector search ranks across tenants first and filters afterwards, which both leaks and truncates.
+
+# Component pages
+
+- [smrt-facts](/components/smrt-facts.md)
+- [smrt-content](/components/smrt-content.md)
+- [smrt-ingestion](/components/smrt-ingestion.md)
+- [smrt-core](/components/smrt-core.md)
+
+# Detection signals
+
+- `import:@pinecone-database/pinecone`
+- `import:pgvector`
+- `import:minisearch`
+- `import:flexsearch`
+- `import:lunr`
+- `regex:cosine_?[sS]imilarity`
+
+[^s1]: `packages/facts/src/facts.ts` at `478ae36900`: FactCollection.reconcile.
+[^s2]: `packages/core/src/collection.ts` at `478ae36900`: SmrtCollection.findSimilarToEmbedding, semanticSearch.
+[^s3]: `packages/core/src/embeddings/storage.ts` at `478ae36900`: EmbeddingStorage.searchSimilar.
+[^s4]: `packages/ingestion/AGENTS.md` at `478ae36900`: ingestion invariants.

package/dist/knowledge/intents/secrets-and-config.md

@@ -0,0 +1,66 @@
+---
+type: Capability
+title: "Secrets and configuration"
+description: "Reach for smrt-secrets for per-tenant encrypted secrets and smrt-config for application configuration instead of raw env reads and ad-hoc encryption."
+tags:
+  - smrt
+  - intent
+status: draft
+generated:
+  by: claude/smrt-4687
+  at: 2026-11-05T00:00:00Z
+stale_after: 2027-02-03T00:00:00Z
+audience: internal
+evidence_level: source-inspected
+package_version: 0.60.8
+sources:
+  - id: s1
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/secrets/src/services/SecretService.ts
+    path: packages/secrets/src/services/SecretService.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/secrets/src/services/SecretService.ts (SecretService.store)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/secrets/src/index.ts
+    path: packages/secrets/src/index.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/secrets/src/index.ts (public exports)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/config/src/loaded-config.ts
+    path: packages/config/src/loaded-config.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/config/src/loaded-config.ts (globalThis.__smrtConfigCache)"
+  - id: s4
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/config/src/index.ts
+    path: packages/config/src/index.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/config/src/index.ts (loadConfig)"
+---
+
+# Secrets and configuration
+
+# Entry point
+
+Secrets: `SecretService.create({ db, ... })` from `@happyvertical/smrt-secrets`, then `store(name, value, { description, category, expiresAt })` inside a tenant context (`storeForTenant()` outside one). Values are envelope-encrypted by the @happyvertical/secrets store under a per-tenant data key, and key drift is diagnosed with `diagnoseTenantSecretKeyDrift()`. Config: `await loadConfig()` once at startup (finds `smrt.config.*`), then `getConfig()`, `getModuleConfig()` or `getPackageConfig()` from `@happyvertical/smrt-config`; `defineConfig()` types the file.[^s2][^s4]
+
+# Why not hand-roll it
+
+`SecretService.store()` in `SecretService.ts` looks the secret up for the current tenant only (an unscoped lookup once found another tenant's same-named row and overwrote it with an envelope encrypted under the wrong key, #1501), refuses to save over a foreign row even if a lookup regresses, keys the upsert on slug plus `context = tenantId` so tenants can reuse names, and writes a `SecretAuditLog` row for create, update and failure alike, classifying tenant-key failures.[^s1] For config, `loaded-config.ts` keeps the parsed config on `globalThis.__smrtConfigCache` so every module instance, including pnpm workspace packages loaded from different paths, sees the same object.[^s3] Raw `process.env` reads and home-made AES have no tenant boundary, rotation or audit trail.
+
+# Component pages
+
+- [smrt-secrets](/components/smrt-secrets.md)
+- [smrt-config](/components/smrt-config.md)
+
+# Detection signals
+
+- `import:dotenv`
+- `import:node-vault`
+- `import:cosmiconfig`
+- `import:convict`
+- `regex:process\.env\.\w*SECRET`
+- `regex:createCipheriv\(`
+
+[^s1]: `packages/secrets/src/services/SecretService.ts` at `478ae36900`: SecretService.store.
+[^s2]: `packages/secrets/src/index.ts` at `478ae36900`: public exports.
+[^s3]: `packages/config/src/loaded-config.ts` at `478ae36900`: globalThis.__smrtConfigCache.
+[^s4]: `packages/config/src/index.ts` at `478ae36900`: loadConfig.

package/dist/knowledge/intents/tenant-scoping.md

@@ -0,0 +1,63 @@
+---
+type: Capability
+title: "Tenant scoping and cross-tenant reads"
+description: "Reach for smrt-tenancy and the core allowCrossTenant opt-in instead of filtering by tenant_id by hand."
+tags:
+  - smrt
+  - intent
+status: draft
+generated:
+  by: claude/smrt-4687
+  at: 2026-11-05T00:00:00Z
+stale_after: 2027-02-03T00:00:00Z
+audience: internal
+evidence_level: source-inspected
+package_version: 0.60.8
+sources:
+  - id: s1
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/tenancy/src/interceptor.ts
+    path: packages/tenancy/src/interceptor.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/tenancy/src/interceptor.ts (createTenantInterceptor, rawQueryPolicy)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/tenancy/src/index.ts
+    path: packages/tenancy/src/index.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/tenancy/src/index.ts (withTenant, withSystemContext, queryGlobal, queryWithGlobals)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/object.ts
+    path: packages/core/src/object.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/object.ts (SmrtObject.assertRelatedTenant, allowCrossTenant)"
+  - id: s4
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/collection.ts
+    path: packages/core/src/collection.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/collection.ts (SmrtCollection.findSimilarToEmbedding tenant prefilter)"
+---
+
+# Tenant scoping and cross-tenant reads
+
+# Entry point
+
+Import from `@happyvertical/smrt-tenancy`. Declare a model with `@TenantScoped({ mode })` and a `@tenantId()` field, call `enableTenancy()` once at startup, and run request work inside `withTenant({ tenantId }, fn)` (adapters: `createSvelteKitHandle`, `createExpressMiddleware`, `createCliContext`). Collections then filter by tenant automatically. Read shared rows with `queryWithGlobals()`/`queryGlobal()`, use `withSystemContext()` only for reviewed system work, and opt into a cross-tenant relationship load with `{ allowCrossTenant: true }` on `loadRelated`/`getRelated` (core).[^s2]
+
+# Why not hand-roll it
+
+A hand-written `WHERE tenant_id = ?` covers only the query you wrote. The interceptor in `interceptor.ts` throws `TenantIsolationError` for any raw SQL against a tenant-scoped class unless the call passes `allowRawOnTenantScoped` (default `rawQueryPolicy: 'throw'`).[^s1] In core, `SmrtObject.assertRelatedTenant()` makes relationship loads, including cache hits from an earlier eager load, throw on a cross-tenant reference, and only the exact value `allowCrossTenant === true` bypasses it, not a truthy value from untyped callers (#1321).[^s3] Semantic search runs the tenant interceptor's list prefilter first and ranks only that tenant's ids, because the embeddings table has no tenant column.[^s4]
+
+# Component pages
+
+- [smrt-tenancy](/components/smrt-tenancy.md)
+- [smrt-core](/components/smrt-core.md)
+
+# Detection signals
+
+- `regex:WHERE\s+tenant_id`
+- `regex:tenant_?[iI]d\s*=\s*\?`
+- `regex:tenantId\s*[!=]==`
+
+[^s1]: `packages/tenancy/src/interceptor.ts` at `478ae36900`: createTenantInterceptor, rawQueryPolicy.
+[^s2]: `packages/tenancy/src/index.ts` at `478ae36900`: withTenant, withSystemContext, queryGlobal, queryWithGlobals.
+[^s3]: `packages/core/src/object.ts` at `478ae36900`: SmrtObject.assertRelatedTenant, allowCrossTenant.
+[^s4]: `packages/core/src/collection.ts` at `478ae36900`: SmrtCollection.findSimilarToEmbedding tenant prefilter.

package/dist/knowledge/intents/webhooks-and-events.md

@@ -0,0 +1,71 @@
+---
+type: Capability
+title: "Webhooks and events"
+description: "Reach for smrt-webhooks for outbound signed delivery and the core DispatchBus for in-process events; there is no generic inbound webhook receiver at this revision."
+tags:
+  - smrt
+  - intent
+status: draft
+generated:
+  by: claude/smrt-4687
+  at: 2026-11-05T00:00:00Z
+stale_after: 2027-02-03T00:00:00Z
+audience: internal
+evidence_level: source-inspected
+package_version: 0.60.8
+sources:
+  - id: s1
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/webhooks/src/security.ts
+    path: packages/webhooks/src/security.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/webhooks/src/security.ts (assertWebhookUrl, assertHmacSecret, sendPublicWebhook)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/webhooks/src/dispatcher.ts
+    path: packages/webhooks/src/dispatcher.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/webhooks/src/dispatcher.ts (WebhookDispatcher.deliver)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/dispatch/bus.ts
+    path: packages/core/src/dispatch/bus.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/dispatch/bus.ts (DispatchBus.emit, process)"
+  - id: s4
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/jobs/src/forge-projection.ts
+    path: packages/jobs/src/forge-projection.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/jobs/src/forge-projection.ts (ForgeDelivery inbox)"
+  - id: s5
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/events/package.json
+    path: packages/events/package.json
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/events/package.json (description)"
+---
+
+# Webhooks and events
+
+# Entry point
+
+Outbound: `@happyvertical/smrt-webhooks` is server-only. Subscribers are `WebhookSubscription` rows managed through `WebhookAdminService`; publish from the change feed with `WebhookChangeFeed` (preferred) or `registerWebhookModelEvents()` (never both for one model), and run deliveries with `runWebhookDeliveryJob` on the smrt-jobs queue. In-process events: `createDispatchBus()` / `DispatchBus` (`emit()`, `on()`, `subscribe()`, `process()`) in `@happyvertical/smrt-core`. Corrections to the expected home: [smrt-events](/components/smrt-events.md) is the calendar and event-hierarchy model, not an event bus; and no package provides a generic inbound webhook receiver at this revision. The closest inbound pattern is the provider-neutral forge delivery inbox in smrt-jobs (`ForgeDelivery`, `ForgeProjectionRuntime`).[^s4][^s5]
+
+# Why not hand-roll it
+
+`sendPublicWebhook()` in `security.ts` validates every DNS answer as a public address, pins the socket lookup to the validated answer so a second resolution cannot rebind, follows no redirects, uses no proxy or pooled sockets, and bounds DNS (5 s) and request (10 s) time; `assertWebhookUrl()` rejects non-HTTPS, ports other than 443, embedded credentials and localhost, and `assertHmacSecret()` requires a 32 to 4096 byte secret.[^s1] `WebhookDispatcher.deliver()` signs `timestamp.payload` with HMAC-SHA256 over the exact stored bytes and sends a stable `x-smrt-delivery` id because HTTP delivery is at-least-once and receivers must deduplicate.[^s2] `DispatchBus` derives the tenant server-side from the active context and claims a dispatch with a conditional UPDATE on `status = 'pending'`, so a subscriber in one tenant cannot see another tenant's dispatches.[^s3]
+
+# Component pages
+
+- [smrt-webhooks](/components/smrt-webhooks.md)
+- [smrt-core](/components/smrt-core.md)
+- [smrt-jobs](/components/smrt-jobs.md)
+- [smrt-events](/components/smrt-events.md)
+
+# Detection signals
+
+- `import:svix`
+- `regex:createHmac\(`
+- `regex:x-[a-z-]*signature`
+
+[^s1]: `packages/webhooks/src/security.ts` at `478ae36900`: assertWebhookUrl, assertHmacSecret, sendPublicWebhook.
+[^s2]: `packages/webhooks/src/dispatcher.ts` at `478ae36900`: WebhookDispatcher.deliver.
+[^s3]: `packages/core/src/dispatch/bus.ts` at `478ae36900`: DispatchBus.emit, process.
+[^s4]: `packages/jobs/src/forge-projection.ts` at `478ae36900`: ForgeDelivery inbox.
+[^s5]: `packages/events/package.json` at `478ae36900`: description.

package/dist/{oidcProvisioningPrimitives-KpIiLmG4-CnRTofeV.js → oidcProvisioningPrimitives-KpIiLmG4-D5-0dAY3.js}

@@ -1,8 +1,8 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
 import { n as __exportAll$1 } from "./NostrIdentity-RJaATTCt-BbRHWyee.js";
-import { t as OidcIdentity } from "./OidcIdentity-COeMidoC-B-cVovG3.js";
-import { l as saveOidcRaceArbiter, n as Profile, r as ProfileCollection } from "./ProfileCollection-CmRaiE9U-52qjwbhJ.js";
-import { t as ProfileTypeCollection } from "./ProfileTypeCollection-BRLK8cHS-QVwjfqe8.js";
+import { t as OidcIdentity } from "./OidcIdentity-COeMidoC-ETkpZbIS.js";
+import { l as saveOidcRaceArbiter, n as Profile, r as ProfileCollection } from "./ProfileCollection-CmRaiE9U-BYvpJg0y.js";
+import { t as ProfileTypeCollection } from "./ProfileTypeCollection-BRLK8cHS-BKuh_ajh.js";
 import { smrt } from "@happyvertical/smrt-core";
 //#region ../profiles/dist/chunks/oidcProvisioningPrimitives-KpIiLmG4.js
 var oidcProvisioningPrimitives_KpIiLmG4_exports = /* @__PURE__ */ __exportAll({

package/dist/{operator-fwao3Y1j.js → operator-B0ZraSEE.js}

@@ -1,5 +1,5 @@
-import { m as withSystemContext } from "./dist-BJABhykg.js";
-import { Ct as TenantStatus, E as PasswordCredentialService, K as UserCollection, N as RoleCollection, Q as UsersPasswordCredentialCollection, V as TenantCollection, dt as normalizeUsername, g as MembershipCollection, ht as verifySecretHash, j as PermissionResolver, lt as normalizeEmail, st as isValidEmail, wt as UserStatus, yt as MembershipStatus } from "./PasswordCredentialService-DHJNKEeJ-DQlR62e-.js";
+import { m as withSystemContext } from "./dist-CivxAJ6C.js";
+import { Ct as TenantStatus, E as PasswordCredentialService, K as UserCollection, N as RoleCollection, Q as UsersPasswordCredentialCollection, V as TenantCollection, dt as normalizeUsername, g as MembershipCollection, ht as verifySecretHash, j as PermissionResolver, lt as normalizeEmail, st as isValidEmail, wt as UserStatus, yt as MembershipStatus } from "./PasswordCredentialService-BSSP_kyT-t7bjBu4L.js";
 import { isPostgresDatabase, withEmbeddedWriteTransaction } from "@happyvertical/smrt-core";
 //#region ../users/dist/operator.js
 var OperatorProvisioningError = class extends Error {

package/dist/{portability-CbMgEnD1.js → portability-sL8U5Hld.js}

@@ -1,9 +1,10 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
-import { A as assertExternalArtifactPath, L as errorCode } from "./cli-CtRx1_yP.js";
+import { A as assertExternalArtifactPath, L as errorCode } from "./cli-DXIN1FbA.js";
 import { closeSync, constants, existsSync, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createHash, randomBytes } from "node:crypto";
+import { isLocalAssetLocator, localAssetKey, makeLocalAssetLocator } from "@happyvertical/smrt-assets/locator";
 //#region src/app/portability-assets.ts
 /**
 * Filesystem asset portability for logical export/import bundles.
@@ -102,45 +103,47 @@ function readBoundedDescriptor(descriptor, expectedSize, changedCode) {
 	if (readSync(descriptor, Buffer.allocUnsafe(1), 0, 1, null) !== 0) throw fail(changedCode);
 	return bytes;
 }
-function readRegularFileUnchecked(path, approvedRoot, onOpened) {
+function readRegularFileUnchecked(path, approvedRoot, onOpened, requireSingleLink = false) {
 	const lexicalPath = resolve(path);
 	if (!isInside(approvedRoot, lexicalPath)) throw fail("asset-outside-root");
 	const before = lstatSync(lexicalPath);
-	if (before.isSymbolicLink() || !before.isFile()) throw fail("asset-not-regular");
+	if (!before.isFile() || requireSingleLink && before.nlink !== 1) throw fail("asset-not-regular");
 	if (before.size > 67108864) throw fail("asset-too-large");
 	if (!isInside(approvedRoot, realpathSync(lexicalPath))) throw fail("asset-outside-root");
 	const noFollow = constants.O_NOFOLLOW ?? 0;
 	const descriptor = openSync(lexicalPath, constants.O_RDONLY | noFollow);
 	try {
 		const opened = fstatSync(descriptor);
-		if (!opened.isFile() || opened.size !== before.size) throw fail("asset-changed-during-read");
+		if (!opened.isFile() || opened.size !== before.size || requireSingleLink && opened.nlink !== 1) throw fail("asset-changed-during-read");
 		onOpened?.();
 		const openedPath = statSync(lexicalPath);
 		if (!isInside(approvedRoot, realpathSync(lexicalPath)) || openedPath.dev !== opened.dev || openedPath.ino !== opened.ino) throw fail("asset-changed-during-read");
 		const bytes = readBoundedDescriptor(descriptor, opened.size, "asset-changed-during-read");
 		const after = fstatSync(descriptor);
 		const afterPath = statSync(lexicalPath);
-		if (after.dev !== opened.dev || after.ino !== opened.ino || after.size !== opened.size || bytes.byteLength !== opened.size || !isInside(approvedRoot, realpathSync(lexicalPath)) || afterPath.dev !== opened.dev || afterPath.ino !== opened.ino) throw fail("asset-changed-during-read");
+		if (after.dev !== opened.dev || after.ino !== opened.ino || after.size !== opened.size || requireSingleLink && after.nlink !== 1 || bytes.byteLength !== opened.size || !isInside(approvedRoot, realpathSync(lexicalPath)) || afterPath.dev !== opened.dev || afterPath.ino !== opened.ino) throw fail("asset-changed-during-read");
 		return bytes;
 	} finally {
 		closeSync(descriptor);
 	}
 }
-function readRegularFile(path, approvedRoot, onOpened) {
+function readRegularFile(path, approvedRoot, onOpened, requireSingleLink = false) {
 	try {
-		return readRegularFileUnchecked(path, approvedRoot, onOpened);
+		return readRegularFileUnchecked(path, approvedRoot, onOpened, requireSingleLink);
 	} catch (error) {
 		if (isSanitizedFailure(error)) throw error;
 		throw fail("asset-changed-during-read");
 	}
 }
-function pathFromSourceUri(sourceUri) {
-	if (typeof sourceUri !== "string" || !sourceUri.startsWith("file://")) throw fail("unsupported-asset-source");
+function pathFromSourceUri(sourceUri, root) {
+	if (typeof sourceUri !== "string") throw fail("unsupported-asset-source");
 	try {
-		return fileURLToPath(sourceUri);
+		if (isLocalAssetLocator(sourceUri)) return join(root, localAssetKey(sourceUri));
+		if (sourceUri.startsWith("file://")) return fileURLToPath(sourceUri);
 	} catch {
 		throw fail("unsupported-asset-source");
 	}
+	throw fail("unsupported-asset-source");
 }
 function assetRows(tables) {
 	const table = tables.find((candidate) => candidate?.name === "assets");
@@ -175,7 +178,8 @@ function collectFilesystemAssets({ tables, sourceRoot, assetRoot, onSourceOpened
 		const payloadPath = payloadPathForKey(key);
 		if (payloadPaths.has(payloadPath)) throw fail("duplicate-payload-path");
 		payloadPaths.add(payloadPath);
-		const bytes = readRegularFile(pathFromSourceUri(row.source_uri), root, onSourceOpened);
+		const relativeLocator = typeof row.source_uri === "string" && isLocalAssetLocator(row.source_uri);
+		const bytes = readRegularFile(pathFromSourceUri(row.source_uri, root), root, onSourceOpened, relativeLocator);
 		totalBytes += bytes.byteLength;
 		if (totalBytes > 268435456) throw fail("asset-total-too-large");
 		const contentDigest = digestBytes(bytes);
@@ -183,7 +187,8 @@ function collectFilesystemAssets({ tables, sourceRoot, assetRoot, onSourceOpened
 			key,
 			byteLength: bytes.byteLength,
 			contentDigest,
-			payloadPath
+			payloadPath,
+			...relativeLocator ? { locator: "relative" } : {}
 		});
 		payloads.push({
 			path: payloadPath,
@@ -231,6 +236,7 @@ function verifyFilesystemAssets({ assetBundle, tables, sourceRoot, assetRoot })
 	}
 	const keys = /* @__PURE__ */ new Set();
 	const paths = /* @__PURE__ */ new Set();
+	const relativeLocators = /* @__PURE__ */ new Set();
 	const verified = [];
 	let totalBytes = 0;
 	for (const rawEntry of bundle.entries) {
@@ -239,6 +245,8 @@ function verifyFilesystemAssets({ assetBundle, tables, sourceRoot, assetRoot })
 		const payloadPath = normalizePayloadPath(entry?.payloadPath);
 		if (!key || key.length > 512 || keys.has(key)) throw fail("duplicate-asset-key");
 		if (paths.has(payloadPath)) throw fail("duplicate-payload-path");
+		if (entry?.locator === "relative") relativeLocators.add(key);
+		else if (entry?.locator !== void 0) throw fail("invalid-asset-locator");
 		keys.add(key);
 		paths.add(payloadPath);
 		const byteLength = entry?.byteLength;
@@ -270,7 +278,7 @@ function verifyFilesystemAssets({ assetBundle, tables, sourceRoot, assetRoot })
 		assetRoot,
 		allowMissing: true
 	});
-	for (const entry of verified) rowByKey.get(entry.key).source_uri = pathToFileURL(join(root, entry.relativePath)).href;
+	for (const entry of verified) rowByKey.get(entry.key).source_uri = relativeLocators.has(entry.key) ? makeLocalAssetLocator(entry.relativePath) : pathToFileURL(join(root, entry.relativePath)).href;
 	return {
 		root,
 		entries: verified

package/dist/{resolveIdentity-j2WFuKDT-C9XtigVZ.js → resolveIdentity-j2WFuKDT-BieMIOLz.js}

@@ -1,10 +1,10 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
-import { m as withSystemContext } from "./dist-BJABhykg.js";
+import { m as withSystemContext } from "./dist-CivxAJ6C.js";
 import { a as verifyAuthEvent, n as __exportAll$1, t as NostrIdentity } from "./NostrIdentity-RJaATTCt-BbRHWyee.js";
 import { t as ApiKey } from "./ApiKey-9YuYcpWy-BdrXOe-N.js";
-import { t as OidcIdentity } from "./OidcIdentity-COeMidoC-B-cVovG3.js";
-import { c as normalizeIdentityEmail, o as coordinateOidcProvisioning, s as isOidcProvisioningRaceConflict } from "./ProfileCollection-CmRaiE9U-52qjwbhJ.js";
-import { n as insertOidcProvisioningIdentity, t as createOidcProvisioningPerson } from "./oidcProvisioningPrimitives-KpIiLmG4-CnRTofeV.js";
+import { t as OidcIdentity } from "./OidcIdentity-COeMidoC-ETkpZbIS.js";
+import { c as normalizeIdentityEmail, o as coordinateOidcProvisioning, s as isOidcProvisioningRaceConflict } from "./ProfileCollection-CmRaiE9U-BYvpJg0y.js";
+import { n as insertOidcProvisioningIdentity, t as createOidcProvisioningPerson } from "./oidcProvisioningPrimitives-KpIiLmG4-D5-0dAY3.js";
 import { resolveDatabase } from "@happyvertical/smrt-core";
 //#region ../profiles/dist/chunks/resolveIdentity-j2WFuKDT.js
 var resolveIdentity_j2WFuKDT_exports = /* @__PURE__ */ __exportAll({
@@ -72,13 +72,13 @@ async function resolveIdentity(context) {
 	};
 }
 async function findProfileByExternalId(provider, externalId, options) {
-	const { OidcIdentityCollection } = await import("./OidcIdentityCollection-D4DIZv0K-CexIL7No.js").then((n) => n.r).then((n) => n.r);
+	const { OidcIdentityCollection } = await import("./OidcIdentityCollection-D4DIZv0K-Do3bwRuw.js").then((n) => n.r).then((n) => n.r);
 	const identities = await (await OidcIdentityCollection.create(options)).findByProvider(provider);
 	for (const identity of identities) if (identity.subject === externalId || identity.email?.includes(externalId)) {
 		const profile = await identity.getProfile();
 		if (profile) return profile;
 	}
-	const { ProfileCollection } = await import("./ProfileCollection-CmRaiE9U-52qjwbhJ.js").then((n) => n.i).then((n) => n.r);
+	const { ProfileCollection } = await import("./ProfileCollection-CmRaiE9U-BYvpJg0y.js").then((n) => n.i).then((n) => n.r);
 	const profiles = await (await ProfileCollection.create(options)).list({
 		where: { email: `${externalId}@users.noreply.github.com` },
 		limit: 1
@@ -99,7 +99,7 @@ async function reuseExistingOidcIdentityForProfile(profileId, claims, provider,
 		createConcurrencyError: (cause) => new Error("Concurrent exact OIDC identity reuse did not converge.", cause === void 0 ? void 0 : { cause }),
 		rebindRootResult: rebindOidcProfileResult,
 		provision: (tx) => withSystemContext(async () => {
-			const { OidcIdentityCollection } = await import("./OidcIdentityCollection-D4DIZv0K-CexIL7No.js").then((n) => n.r).then((n) => n.r);
+			const { OidcIdentityCollection } = await import("./OidcIdentityCollection-D4DIZv0K-Do3bwRuw.js").then((n) => n.r).then((n) => n.r);
 			const identity = await (await OidcIdentityCollection.create({ db: tx })).findBySubject(normalizedClaims.iss, normalizedClaims.sub);
 			if (!identity) throw new Error("OidcIdentity.findOrCreate() no longer creates authentication links; use UserCollection.getOrCreateFromOidc() or createProfileFromOidc().");
 			if (identity.profileId !== profileId) throw new Error(`OIDC identity ${normalizedClaims.iss} subject ${normalizedClaims.sub} belongs to a different Profile.`);
@@ -133,7 +133,7 @@ async function coordinateProfileOidcProvisioning(claims, provider, options) {
 	});
 }
 async function provisionOidcProfile(claims, provider, options) {
-	const { OidcIdentityCollection } = await import("./OidcIdentityCollection-D4DIZv0K-CexIL7No.js").then((n) => n.r).then((n) => n.r);
+	const { OidcIdentityCollection } = await import("./OidcIdentityCollection-D4DIZv0K-Do3bwRuw.js").then((n) => n.r).then((n) => n.r);
 	const existingIdentity = await (await OidcIdentityCollection.create(options)).findBySubject(claims.iss, claims.sub);
 	if (existingIdentity) {
 		const profile2 = await existingIdentity.getProfile();
@@ -148,7 +148,7 @@ async function provisionOidcProfile(claims, provider, options) {
 			created: false
 		};
 	}
-	const { ProfileCollection } = await import("./ProfileCollection-CmRaiE9U-52qjwbhJ.js").then((n) => n.i).then((n) => n.r);
+	const { ProfileCollection } = await import("./ProfileCollection-CmRaiE9U-BYvpJg0y.js").then((n) => n.i).then((n) => n.r);
 	const profileCollection = await ProfileCollection.create(options);
 	if (claims.email) {
 		if (await profileCollection.findUniqueGlobalPersonByEmail(claims.email)) {
@@ -175,8 +175,8 @@ async function provisionOidcProfile(claims, provider, options) {
 	};
 }
 async function rebindOidcProfileResult(result, rootDb) {
-	const { OidcIdentityCollection } = await import("./OidcIdentityCollection-D4DIZv0K-CexIL7No.js").then((n) => n.r).then((n) => n.r);
-	const { ProfileCollection } = await import("./ProfileCollection-CmRaiE9U-52qjwbhJ.js").then((n) => n.i).then((n) => n.r);
+	const { OidcIdentityCollection } = await import("./OidcIdentityCollection-D4DIZv0K-Do3bwRuw.js").then((n) => n.r).then((n) => n.r);
+	const { ProfileCollection } = await import("./ProfileCollection-CmRaiE9U-BYvpJg0y.js").then((n) => n.i).then((n) => n.r);
 	const profileId = requireOidcProfileId(result.profile.id);
 	const identityId = requireOidcProfileId(result.oidcIdentity.id);
 	const [profile, oidcIdentity] = await withSystemContext(async () => {
@@ -225,11 +225,11 @@ async function createProfileFromNostr(email, nostrData, options) {
 			created: false
 		};
 	}
-	const { Person } = await import("./oidcProvisioningPrimitives-KpIiLmG4-CnRTofeV.js").then((n) => n.r).then((n) => n.o);
-	const { ProfileTypeCollection } = await import("./ProfileTypeCollection-BRLK8cHS-QVwjfqe8.js").then((n) => n.n).then((n) => n.n);
+	const { Person } = await import("./oidcProvisioningPrimitives-KpIiLmG4-D5-0dAY3.js").then((n) => n.r).then((n) => n.o);
+	const { ProfileTypeCollection } = await import("./ProfileTypeCollection-BRLK8cHS-BKuh_ajh.js").then((n) => n.n).then((n) => n.n);
 	let personType = await (await ProfileTypeCollection.create(options)).getBySlug("person");
 	if (!personType) {
-		const { ProfileType } = await import("./ProfileCollection-CmRaiE9U-52qjwbhJ.js").then((n) => n.i).then((n) => n.h);
+		const { ProfileType } = await import("./ProfileCollection-CmRaiE9U-BYvpJg0y.js").then((n) => n.i).then((n) => n.h);
 		personType = new ProfileType({
 			...options,
 			slug: "person",