@proveanything/smartlinks 1.10.0 → 1.10.2

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.10.0  |  Generated: 2026-04-25T13:26:09.113Z
+Version: 1.10.2  |  Generated: 2026-04-27T09:32:45.351Z
 
 This is a concise summary of all available API functions and types.
 
@@ -1880,24 +1880,24 @@ interface ReplyInput {
 }
 ```
 
-**ScopeFacetClause** (interface)
+**FacetRuleClause** (interface)
 ```typescript
-interface ScopeFacetClause {
-  key: string
-  valueKeys: string[]
+interface FacetRuleClause {
+  * Facet key this clause tests, e.g. "brand", "type", "bread-type".
+  * Must reference a defined facet on the collection.
+  facetKey: string
+  * One or more facet value keys that satisfy the clause (OR semantics).
+  * At least one value required. Server deduplicates and sorts.
+  anyOf: string[]
 }
 ```
 
-**RecordScope** (interface)
+**FacetRule** (interface)
 ```typescript
-interface RecordScope {
-  productId?: string
-  variantId?: string
-  proofId?: string
-  batchId?: string
-  * Arbitrary facet clauses.
-  * Clauses are ANDed together; valueKeys within a clause are ORed.
-  facets?: ScopeFacetClause[]
+interface FacetRule {
+  * All clauses must be satisfied (AND semantics).
+  * Must be non-empty; no duplicate facetKey entries.
+  all: FacetRuleClause[]
 }
 ```
 
@@ -1908,8 +1908,10 @@ interface RecordTarget {
   variantId?: string
   proofId?: string
   batchId?: string
-  * Facet values the caller possesses, keyed by facet key.
-  * A scope clause is satisfied if ANY of the clause's valueKeys appears here.
+  * Facet assignments for the product (e.g. `{ brand: ['samsung'], type: ['tv'] }`).
+  * Used exclusively to match FacetRule records via GIN-indexed containment check.
+  * Does NOT filter legacy scope.facets arrays (that system is removed in SDK 1.12).
+  * Omit to exclude rule records from results.
   facets?: Record<string, string[]>
 }
 ```
@@ -1919,14 +1921,18 @@ interface RecordTarget {
 interface BulkUpsertItem {
   ref: string
   recordType?: string
-  customId?: string
-  sourceSystem?: string
+  productId?: string | null
+  variantId?: string | null
+  batchId?: string | null
+  proofId?: string | null
+  customId?: string | null
+  sourceSystem?: string | null
   startsAt?: string | null
   expiresAt?: string | null
   status?: string | null
-  scope?: RecordScope
   data?: Record<string, unknown> | null
   metadata?: Record<string, unknown> | null
+  facetRule?: FacetRule | null
 }
 ```
 
@@ -1953,10 +1959,9 @@ interface BulkDeleteResult {
 **MatchResult** (interface)
 ```typescript
 interface MatchResult {
-  records: MatchedRecord[]
-  * Only present when strategy is 'best'.
-  * The single highest-specificity record per recordType.
-  best?: Record<string, MatchedRecord>
+  data: MatchEntry[]
+  total: number
+  strategy: 'all' | 'best'
 }
 ```
 
@@ -1965,14 +1970,18 @@ interface MatchResult {
 interface UpsertRecordInput {
   ref: string
   recordType?: string
-  customId?: string
-  sourceSystem?: string
+  productId?: string | null
+  variantId?: string | null
+  batchId?: string | null
+  proofId?: string | null
+  customId?: string | null
+  sourceSystem?: string | null
   startsAt?: string | null
   expiresAt?: string | null
   status?: string | null
-  scope?: RecordScope
   data?: Record<string, unknown> | null
   metadata?: Record<string, unknown> | null
+  facetRule?: FacetRule | null
 }
 ```
 
@@ -2001,10 +2010,15 @@ interface AppRecord {
   visibility: Visibility
   recordType: string | null
   ref: string | null
+  scopeType: string | null
+  scopeId: string | null
   customId: string | null
+  customIdNormalized: string | null
   sourceSystem: string | null
   status: string | null
   productId: string | null
+  variantId: string | null
+  batchId: string | null
   proofId: string | null
   contactId: string | null
   authorId: string | null
@@ -2016,12 +2030,13 @@ interface AppRecord {
   startsAt: string | null
   expiresAt: string | null
   deletedAt: string | null // admin only
-  * Structured scope definition. Empty object means universal.
-  * Platform-canonicalized on write (keys sorted, valueKeys deduplicated).
-  scope: RecordScope
-  * Numeric specificity score computed from scope.
-  * Higher = more specific. 0 = universal scope.
+  * Numeric specificity score. Server-computed from anchor IDs and facetRule.
+  * Higher = more specific. 0 = universal (no anchors, no rule).
   specificity: number
+  * Facet rule for rule records (ref starts with "rule:").
+  * null on all other record types. Mutually exclusive with anchor IDs.
+  facetRule: FacetRule | null
+  singletonKey: string | null
   data: Record<string, unknown>
   owner: Record<string, unknown>
   admin: Record<string, unknown> // admin only
@@ -2032,26 +2047,33 @@ interface AppRecord {
 **CreateRecordInput** (interface)
 ```typescript
 interface CreateRecordInput {
-  recordType: string
-  visibility?: Visibility // default 'owner'
-  ref?: string             // derived from scope if omitted and scope provided
-  status?: string // default 'active'
-  productId?: string
-  proofId?: string
+  recordType?: string
+  visibility?: Visibility
+  ref?: string
+  status?: string
+  productId?: string | null
+  variantId?: string | null
+  batchId?: string | null
+  proofId?: string | null
   contactId?: string
   authorId?: string
   authorType?: string
   parentType?: string
   parentId?: string
-  startsAt?: string // ISO 8601
-  expiresAt?: string
-  scope?: RecordScope
-  customId?: string
-  sourceSystem?: string
+  startsAt?: string | null
+  expiresAt?: string | null
+  scopeType?: string | null
+  scopeId?: string | null
+  customId?: string | null
+  sourceSystem?: string | null
+  * Opt-in singleton cardinality. When set, the server upserts rather than
+  * inserting a duplicate. Values: 'collection' | 'product' | 'variant' | 'batch' | 'proof'
+  singletonPer?: string
   data?: Record<string, unknown>
   owner?: Record<string, unknown>
-  admin?: Record<string, unknown> // admin only
+  admin?: Record<string, unknown>
   metadata?: Record<string, unknown>
+  facetRule?: FacetRule | null
 }
 ```
 
@@ -2065,12 +2087,90 @@ interface UpdateRecordInput {
   visibility?: Visibility
   ref?: string
   recordType?: string
-  startsAt?: string
-  expiresAt?: string
-  scope?: RecordScope
-  customId?: string
-  sourceSystem?: string
+  productId?: string | null
+  variantId?: string | null
+  batchId?: string | null
+  proofId?: string | null
+  startsAt?: string | null
+  expiresAt?: string | null
+  scopeType?: string | null
+  scopeId?: string | null
+  customId?: string | null
+  sourceSystem?: string | null
   metadata?: Record<string, unknown>
+  facetRule?: FacetRule | null
+}
+```
+
+**ResolveAllParams** (interface)
+```typescript
+interface ResolveAllParams {
+  context: {
+  productId?: string
+  variantId?: string
+  batchId?: string
+  proofId?: string
+  * Facet assignments for the product — used for both legacy facet-ref matching
+  * and facetRule evaluation.
+  * e.g. { "brand": "samsung", "type": ["tv", "laptop"] }
+  facets?: Record<string, string | string[]>
+  }
+  recordType?: string
+  tiers?: Array<'proof' | 'batch' | 'variant' | 'product' | 'rule' | 'facet' | 'collection'>
+  limit?: number
+  at?: string
+  includeScheduled?: boolean
+  includeExpired?: boolean
+}
+```
+
+**ResolveAllResult** (interface)
+```typescript
+interface ResolveAllResult {
+  records: ResolveAllEntry[]
+  total: number
+  context: ResolveAllContext
+  truncated: boolean
+}
+```
+
+**ResolveAllEntry** (interface)
+```typescript
+interface ResolveAllEntry {
+  record: AppRecord
+  matchedAt: MatchedAt
+  specificity: number
+  matchedRule?: FacetRule
+  matchedClauseCount?: number
+}
+```
+
+**ResolveAllContext** (interface)
+```typescript
+interface ResolveAllContext {
+  productId?: string
+  variantId?: string
+  batchId?: string
+  proofId?: string
+  facets?: Record<string, string[]>
+}
+```
+
+**PreviewRuleParams** (interface)
+```typescript
+interface PreviewRuleParams {
+  facetRule: FacetRule
+  recordType?: string
+  limit?: number
+}
+```
+
+**PreviewRuleResult** (interface)
+```typescript
+interface PreviewRuleResult {
+  matchingProducts: Array<{ productId: string; name?: string; facets: Record<string, string[]> }>
+  total: number
+  rule: FacetRule
 }
 ```
 
@@ -2140,7 +2240,7 @@ interface PublicCreateBranch {
 
 **BulkDeleteInput** = ``
 
-**MatchedAtLevel** = ``
+**MatchedAt** = ``
 
 ### asset
 
@@ -7306,6 +7406,17 @@ Upsert up to 500 records in a single transaction. Each row is individually error
     input: BulkDeleteInput) → `Promise<BulkDeleteResult>`
 Soft-delete records in bulk. Supports two modes: - **refs mode**: explicit list of refs (max 1000) - **scope mode**: delete by scope anchor (productId / variantId / etc.) POST /records/bulk-delete (admin only) ```ts // Refs mode await app.records.bulkDelete(collectionId, appId, { refs: ['product:prod_abc', 'product:prod_xyz'], recordType: 'nutrition', }); // Scope mode await app.records.bulkDelete(collectionId, appId, { scope: { productId: 'prod_abc' }, }); ```
 
+**resolveAll**(collectionId: string,
+    appId: string,
+    input: ResolveAllParams,
+    admin: boolean = false) → `Promise<ResolveAllResult>`
+Resolve every applicable record for a product context in one call. Returns records across all tiers (proof, batch, variant, product, rule, facet, collection) deduplicated and sorted by specificity descending. POST /records/resolve-all
+
+**previewRule**(collectionId: string,
+    appId: string,
+    input: PreviewRuleParams) → `Promise<PreviewRuleResult>`
+Preview which products in the collection match a given facetRule. Admin only. Use for live "matches N products" feedback while authoring a rule. POST /records/preview-rule
+
 ### app.threads
 
 Conversation-oriented app objects for comments, discussions, Q&A, and reply-driven experiences.

package/docs/app-objects.md

@@ -432,7 +432,7 @@ const productComments = await app.threads.list(collectionId, appId, {
 
 ## Records
 
-**Records** are the most flexible object type — use them for structured data with time-based lifecycles, hierarchies, or custom schemas. Records also support **structured scoping** — each record can declare which products, variants, batches, proofs, or facet values it applies to, and the platform can match records against a runtime context.
+**Records** are the most flexible object type — use them for structured data with time-based lifecycles, hierarchies, or custom schemas. Records also support **structured targeting** — each record can declare which products, variants, batches, or proofs it applies to (via anchor fields), or which product attributes match (via `facetRule`), and the platform can match records against a runtime context.
 
 ### When to Use Records
 
@@ -450,64 +450,102 @@ const productComments = await app.threads.list(collectionId, appId, {
 
 - **Record types** — `recordType` field for categorization (required)
 - **Time windows** — `startsAt` and `expiresAt` for time-based data
-- **Scoped targeting** — `scope` object restricts which products/variants/facets the record applies to
-- **Specificity scoring** — `specificity` enables "best match" resolution across multiple scoped records
+- **Anchor fields** — `productId`, `variantId`, `batchId`, `proofId` restrict which context the record applies to
+- **Facet rules** — `facetRule` matches records to products based on attribute values
+- **Specificity scoring** — `specificity` enables "best match" resolution across multiple targeted records
 - **Parent linking** — attach to products, proofs, contacts, etc.
 - **Author tracking** — `authorId` + `authorType`
 - **Status lifecycle** — custom statuses (default `'active'`)
-- **References** — optional `ref` field for external IDs; auto-derived from scope if omitted
+- **References** — optional `ref` field for external IDs; auto-derived from anchor fields if omitted
 
-### Scoped Records
+### Targeted Records
 
-Every record has a `scope` object. An empty scope (`{}`) means the record is universal — it applies everywhere. A populated scope restricts which context the record applies to.
+Records use flat anchor fields to declare what context they apply to. A record with no anchor fields is universal — it applies everywhere. Populated anchor fields restrict the context to a specific product, variant, batch, or proof.
 
 ```typescript
 import { app } from '@proveanything/smartlinks';
 
-// A nutrition record scoped to a specific product
+// A nutrition record anchored to a specific product
 await app.records.create(collectionId, appId, {
   recordType: 'nutrition',
-  scope: { productId: 'prod_abc' },
+  productId: 'prod_abc',
   data: { calories: 250, protein: 12.5 },
 }, true);
 
 // A nutrition record for a specific variant, overriding the product-level record
 await app.records.create(collectionId, appId, {
   recordType: 'nutrition',
-  scope: { productId: 'prod_abc', variantId: 'var_500ml' },
+  productId: 'prod_abc',
+  variantId: 'var_500ml',
   data: { calories: 260, protein: 12.5 },
 }, true);
 
-// A record scoped to a facet value (applies to all products with tier=gold)
+// A record matching products by facet rule (applies to all products with tier=gold)
 await app.records.create(collectionId, appId, {
   recordType: 'loyalty_promo',
-  scope: {
-    facets: [{ key: 'tier', valueKeys: ['gold', 'platinum'] }]
+  facetRule: {
+    all: [{ facetKey: 'tier', anyOf: ['gold', 'platinum'] }],
   },
   data: { discountPercent: 15 },
 }, true);
 ```
 
-The `ref` field is derived automatically when `scope` is provided and `ref` is omitted:
+The `ref` field is derived automatically from anchor fields when omitted:
 
 ```
-scope: { productId: 'prod_abc' }           → ref: 'product:prod_abc'
-scope: { productId: 'prod_abc', variantId: 'var_x' } → ref: 'product:prod_abc/variant:var_x'
-scope: {}                                  → ref: '' (universal)
+productId: 'prod_abc'                               → ref: 'product:prod_abc'
+productId: 'prod_abc', variantId: 'var_x'          → ref: 'product:prod_abc/variant:var_x'
+(no anchor fields)                                  → ref: '' (universal)
+facetRule: { ... }                                  → ref: 'rule:<ulid>'
 ```
 
 #### Specificity scores
 
 When multiple scoped records match a context, they are ordered by `specificity`. Higher = more specific:
 
-| Scope element | Points |
-|---------------|--------|
+| Field / element | Points |
+|-----------------|--------|
 | `proofId` | +1000 |
 | `batchId` | +500 |
 | `variantId` | +250 |
 | `productId` | +100 |
-| Per facet clause | +10 |
-| Per facet value key | +1 |
+| Per `facetRule` clause | +50 |
+| Per `anyOf` value | +1 |
+| No anchors / no rule | 0 |
+
+### Singleton Cardinality
+
+By default, `create` always inserts a new row — calling it twice produces two records with identical anchor fields. **Singleton cardinality** changes that: pass `singletonPer` on creation and the server will **upsert** instead, ensuring at most one record of a given `recordType` exists per scope boundary.
+
+```typescript
+// Ensure only one active registration record per product per contact
+await app.records.create(collectionId, appId, {
+  recordType: 'product_registration',
+  visibility: 'owner',
+  contactId: user.contactId,
+  productId: product.id,
+  singletonPer: 'product',   // one per (appId + recordType + contactId + productId)
+  data: { registeredAt: new Date().toISOString() },
+});
+```
+
+`singletonPer` values and the scope they enforce:
+
+| Value | De-duplicates across |
+|-------|---------------------|
+| `'collection'` | entire app (one record of this type per app) |
+| `'product'` | `productId` |
+| `'variant'` | `variantId` |
+| `'batch'` | `batchId` |
+| `'proof'` | `proofId` |
+
+The server assigns a **`singletonKey`** to each record that is governed by this rule — an opaque, stable string that acts as the upsert key. If a record with the same key already exists the server updates it in place (clearing `deletedAt` if it was soft-deleted) and returns the existing `id`. `singletonKey` is read-only and exposed on `AppRecord` for debugging but has no meaning to clients.
+
+**When to use `singletonPer`:**
+- One loyalty card per contact per product
+- One registration per proof scan
+- One active subscription record per variant
+- Any "find-or-create" pattern where calling `create` twice should be idempotent
 
 ### Matching Records Against a Context
 
@@ -515,22 +553,22 @@ Use `app.records.match()` to find records whose scope is satisfied by a runtime
 
 ```typescript
 // Find all nutrition records that apply for this product + facet context
-const { records } = await app.records.match(collectionId, appId, {
+const { data } = await app.records.match(collectionId, appId, {
   target: {
     productId: 'prod_abc',
     facets: { tier: ['gold'] },
   },
   recordType: 'nutrition',
 }, true);
-// records is ordered by specificity descending — most specific first
-// each record carries a `matchedAt` field indicating which scope dimension matched
+// data is ordered by specificity descending — most specific first
+// each entry carries a `matchedAt` field indicating which dimension matched
 
-// Or use strategy: 'best' to get the single winner per recordType
-const { best } = await app.records.match(collectionId, appId, {
+// Use strategy: 'best' to get only the single winner per recordType
+const { data: best } = await app.records.match(collectionId, appId, {
   target: { productId: 'prod_abc', variantId: 'var_500ml' },
   strategy: 'best',
 }, true);
-// best.nutrition → the highest-specificity nutrition record for this context
+// best[0] → the highest-specificity record for this context
 ```
 
 Facet matching rules:
@@ -540,29 +578,99 @@ Facet matching rules:
 
 #### `matchedAt` — match attribution
 
-Every record in the response includes a `matchedAt` field indicating **which scope dimension caused the match**. Use it to render attribution labels without inspecting scope fields:
+Every record in the response includes a `matchedAt` field indicating **which matching dimension caused the match**. Use it to render attribution labels:
 
 ```typescript
-const { records } = await app.records.match(collectionId, appId, { target, recordType: 'nutrition' }, true);
-
-for (const record of records) {
-  switch (record.matchedAt) {
-    case 'proof':     /* "Scan-specific" */     break;
-    case 'batch':     /* "Batch-specific" */    break;
-    case 'variant':   /* "Size-specific" */     break;
-    case 'product':   /* "Inherited from product" */ break;
-    case 'facet':     /* "Tier-specific" */     break;
-    case 'universal': /* "Default" */           break;
+const { data } = await app.records.match(collectionId, appId, { target, recordType: 'nutrition' }, true);
+
+for (const entry of data) {
+  switch (entry.matchedAt) {
+    case 'rule':       /* "Matches rule" */           break;
+    case 'proof':      /* "Scan-specific" */          break;
+    case 'batch':      /* "Batch-specific" */         break;
+    case 'variant':    /* "Size-specific" */          break;
+    case 'product':    /* "Inherited from product" */ break;
+    case 'facet':      /* "Tier-specific" */          break;
+    case 'collection': /* "Collection default" */     break;
+    case 'universal':  /* "Default" */                break;
   }
 }
 ```
 
-Precedence follows specificity order: `proof > batch > variant > product > facet > universal`.
+Precedence follows: `rule > proof > batch > variant > product > facet > collection > universal`.
 
 #### React — `useResolvedRecord`
 
 For React consumers, the `useResolvedRecord` hook in `@proveanything/smartlinks-utils-ui` wraps `records.match()` and returns the best-matching record with loading and error states. The raw `records.match()` API exists for non-React consumers and custom resolution logic.
 
+### Facet-Rule Records
+
+A record can declare a **multi-clause boolean rule** (`facetRule`) describing which products it applies to, instead of a single `scope.facets` entry. The rule is AND across facet keys, OR within values of each key:
+
+```typescript
+// Create a record that matches all Samsung TVs and laptops
+await app.records.create(collectionId, appId, {
+  recordType: 'warranty',
+  facetRule: {
+    all: [
+      { facetKey: 'brand', anyOf: ['samsung'] },
+      { facetKey: 'type',  anyOf: ['tv', 'laptop'] },
+    ],
+  },
+  data: { warrantyYears: 2 },
+}, true);
+```
+
+`facetRule` and anchor fields (`productId`, `variantId`, etc.) are mutually exclusive. A record uses either anchor-based targeting or a facetRule, never both. The server assigns `ref: 'rule:<ulid>'` automatically.
+
+Specificity for rule records: `Σ (50 + clause.anyOf.length)` across all clauses. A 2-clause rule with 1 value each scores `(50+1)+(50+1) = 102`, which ranks above a plain product-scoped record (100) in `resolveAll()` results.
+
+Use `records.previewRule()` to see which products a rule would match before creating it:
+
+```typescript
+const { matchingProducts, total } = await app.records.previewRule(collectionId, appId, {
+  facetRule: {
+    all: [{ facetKey: 'brand', anyOf: ['samsung'] }],
+  },
+});
+// total: 42, matchingProducts: [{ productId: 'prod_001', facets: {...} }, ...]
+```
+
+### Resolve All
+
+Use `app.records.resolveAll()` to fetch **every applicable record for a product context** in one request—across all tiers (proof, batch, variant, product, rule, facet, collection defaults), deduplicated and sorted by specificity:
+
+```typescript
+// All records that apply to this product context (admin)
+const { records, total, truncated } = await app.records.resolveAll(collectionId, appId, {
+  context: {
+    productId: 'prod_001',
+    facets: { brand: 'samsung', type: 'tv' },
+  },
+  recordType: 'warranty',
+}, true);
+
+for (const entry of records) {
+  console.log(entry.matchedAt, entry.specificity, entry.record.id);
+  if (entry.matchedAt === 'rule') {
+    console.log('rule fired:', entry.matchedRule, 'clauses:', entry.matchedClauseCount);
+  }
+}
+
+// Public endpoint — visibility-filtered (admin records excluded)
+const { records: publicRecords } = await app.records.resolveAll(collectionId, appId, {
+  context: { productId: 'prod_001', facets: { brand: 'samsung' } },
+}, false);
+
+// Filter to specific tiers
+const { records: ruleRecords } = await app.records.resolveAll(collectionId, appId, {
+  context: { productId: 'prod_001', facets: { brand: 'samsung', type: 'tv' } },
+  tiers: ['product', 'rule', 'collection'],
+}, true);
+```
+
+`truncated: true` means the result hit the safety cap (default 500). Raise it with `limit` (max 5000).
+
 ### Upsert
 
 Create-or-update a record by `ref` in a single call:
@@ -571,7 +679,7 @@ Create-or-update a record by `ref` in a single call:
 const { created } = await app.records.upsert(collectionId, appId, {
   ref: 'product:prod_abc',
   recordType: 'nutrition',
-  scope: { productId: 'prod_abc' },
+  productId: 'prod_abc',
   data: { calories: 250, protein: 12.5 },
 });
 // created: true if new, false if updated
@@ -584,8 +692,8 @@ Upsert or delete large sets of records efficiently:
 ```typescript
 // Bulk upsert up to 500 records in one transaction
 const result = await app.records.bulkUpsert(collectionId, appId, [
-  { ref: 'product:prod_abc', recordType: 'nutrition', scope: { productId: 'prod_abc' }, data: { calories: 250 } },
-  { ref: 'product:prod_xyz', recordType: 'nutrition', scope: { productId: 'prod_xyz' }, data: { calories: 180 } },
+  { ref: 'product:prod_abc', recordType: 'nutrition', productId: 'prod_abc', data: { calories: 250 } },
+  { ref: 'product:prod_xyz', recordType: 'nutrition', productId: 'prod_xyz', data: { calories: 180 } },
 ]);
 // result: { saved: 2, failed: 0, results: [...] }
 
@@ -595,7 +703,7 @@ await app.records.bulkDelete(collectionId, appId, {
   recordType: 'nutrition',
 });
 
-// Bulk delete by scope anchor (all records under a product)
+// Bulk delete by anchor (all records under a product)
 await app.records.bulkDelete(collectionId, appId, {
   scope: { productId: 'prod_abc' },
 });
@@ -649,7 +757,7 @@ await app.records.upsert(collectionId, appId, {
   customId: slug,
   sourceSystem: 'contentful',
   recordType: 'content_page',
-  scope: { productId },
+  productId,
   data: { title, body },
 });
 // upsert finds-or-creates by ref deterministically,
@@ -684,21 +792,21 @@ await app.records.aggregate(collectionId, appId, {
 
 ### Canonical Ref Format
 
-The `ref` field is **server-derived** when you provide a `scope` and omit `ref`. Clients should never construct ref strings manually. The authoritative grammar is slash-joined:
+The `ref` field is **server-derived** when anchor fields are provided and `ref` is omitted. Clients should never construct ref strings manually. The authoritative grammar is slash-joined:
 
 ```
-[facet:{key}={val1}+{val2}/][product:{productId}/][variant:{variantId}/][batch:{batchId}/][proof:{proofId}]
+[product:{productId}/][variant:{variantId}/][batch:{batchId}/][proof:{proofId}]
 ```
 
 Examples:
 
-| Scope | Derived ref |
-|-------|-------------|
-| `{ productId: 'prod_abc' }` | `product:prod_abc` |
-| `{ productId: 'prod_abc', variantId: 'var_500ml' }` | `product:prod_abc/variant:var_500ml` |
-| `{ batchId: 'batch_q1' }` | `batch:batch_q1` |
-| `{ facets: [{ key: 'tier', valueKeys: ['gold'] }] }` | `facet:tier=gold` |
-| `{}` | `''` (universal) |
+| Anchor fields | Derived ref |
+|---------------|-------------|
+| `productId: 'prod_abc'` | `product:prod_abc` |
+| `productId: 'prod_abc', variantId: 'var_500ml'` | `product:prod_abc/variant:var_500ml` |
+| `batchId: 'batch_q1'` | `batch:batch_q1` |
+| `facetRule: { ... }` | `rule:<ulid>` |
+| *(no anchor fields)* | `''` (universal) |
 
 `parseRef` / `buildRef` in `data/refs.ts` should be used for **display and URL round-tripping only**, never as upsert keys. For ETL use cases, set an explicit `ref` using a stable external key (see [External ID / ETL Workflow](#external-id--etl-workflow)).