@proveanything/smartlinks 2.0.50 → 2.0.51

package/dist/api/sequence.d.ts

@@ -30,6 +30,9 @@ export declare namespace sequence {
      *   const { number, isNew } = await sequence.allocate(collectionId, {
      *     appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId,
      *   })
+      *
+     * @deprecated Being removed. Number things in your app's own server function with
+     * `ctx.sl.counters.next()` + `ctx.sl.appRecords.claim()` (docs/server-functions.md).
      */
     function allocate(collectionId: string, input: AllocateSequenceInput): Promise<AllocatedSequence>;
 }

package/dist/api/sequence.js

@@ -18,6 +18,9 @@ export var sequence;
      *   const { number, isNew } = await sequence.allocate(collectionId, {
      *     appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId,
      *   })
+      *
+     * @deprecated Being removed. Number things in your app's own server function with
+     * `ctx.sl.counters.next()` + `ctx.sl.appRecords.claim()` (docs/server-functions.md).
      */
     async function allocate(collectionId, input) {
         return post(`${base(collectionId)}/allocate`, input);

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.50  |  Generated: 2026-10-09T10:28:38.661Z
+Version: 2.0.51  |  Generated: 2026-10-10T07:57:23.889Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2600,10 +2600,73 @@ interface AppDataHandle {
 }
 ```
 
+**AppRecordClaimResult<T = any>** (interface)
+```typescript
+interface AppRecordClaimResult<T = any> {
+  record: T;
+  created: boolean;
+  conflict?: 'singleton' | 'customId';
+}
+```
+
+**ServerFunctionCounters** (interface)
+```typescript
+interface ServerFunctionCounters {
+  next(name: string, opts?: { start?: number; by?: number }): Promise<number>;
+  get(name: string): Promise<number | null>;
+}
+```
+
+**ResolvedTag** (interface)
+```typescript
+interface ResolvedTag {
+  id: string;
+  claimSetId: string;
+  code: string;
+}
+```
+
+**ContactUpsertDetails** (interface)
+```typescript
+interface ContactUpsertDetails {
+  email?: string;
+  phone?: string;
+  firstName?: string;
+  lastName?: string;
+  displayName?: string;
+  company?: string;
+  locale?: string;
+  timezone?: string;
+  customFields?: Record<string, string | number | boolean>;
+}
+```
+
+**ServerFunctionInteractionEvent** (interface)
+```typescript
+interface ServerFunctionInteractionEvent {
+  interactionId: string;
+  contactId?: string | null;
+  outcome?: string;
+  metadata?: Record<string, any>;
+  productId?: string;
+  proofId?: string;
+  variantId?: string;
+  batchId?: string;
+  eventType?: string;
+}
+```
+
 **ServerFunctionSl** (interface)
 ```typescript
 interface ServerFunctionSl {
-  appRecords: any;
+  appRecords: { claim(fields: Record<string, any>): Promise<AppRecordClaimResult>; [method: string]: any };
+  counters: ServerFunctionCounters;
+  tags: { resolve(id: string): Promise<ResolvedTag | null> };
+  contacts: {
+  upsert(details: ContactUpsertDetails): Promise<{ contactId: string; created: boolean }>;
+  forCaller(): Promise<{ contactId: string } | null>;
+  };
+  interactions: { record(event: ServerFunctionInteractionEvent): Promise<{ eventId: string }> };
   products: any;
   attestations: any;
   appData: AppDataHandle & { global: AppDataHandle; collection: AppDataHandle };
@@ -5229,8 +5292,11 @@ interface UnsubscribeResponse {
 ```typescript
 interface CommsSignupRequest {
   email: string
+  templateId: string
   topics?: string[]
   firstName?: string
+  fields?: { firstName?: string; lastName?: string; displayName?: string; company?: string; locale?: string; timezone?: string; customFields?: Record<string, string | number | boolean> }
+  appId?: string
 }
 ```
 
@@ -5597,9 +5663,23 @@ export interface UnsubscribeResponse { ok: true; applied?: { channels?: Record<s
 // Public sign-up (double opt-in)
 export interface CommsSignupRequest {
   email: string
+  /**
+   * Required: YOUR app's confirmation email — a template in this collection (SL.template) whose body
+   * uses `{{ action_url }}` for the confirm link (`{{ topics }}` lists what they signed up for). The
+   * platform sends no default sign-up email.
+   */
+  templateId: string
   /** Topic ids from the collection's comm settings (e.g. ["newsletter"]). */
   topics?: string[]
   firstName?: string
+  /**
+   * The form's other answers — firstName/lastName/displayName/company/locale/timezone and
+   * `customFields`. Applied to the contact when the address is confirmed, and only where the contact
+   * has no value yet (never overwritten). Small: ~2 KB.
+   */
+  fields?: { firstName?: string; lastName?: string; displayName?: string; company?: string; locale?: string; timezone?: string; customFields?: Record<string, string | number | boolean> }
+  /** Your app id, recorded with the sent email. */
+  appId?: string
 }
 export interface CommsSignupResponse { ok: true; pending: true }
 
@@ -12157,7 +12237,7 @@ Soft-delete a secret. DELETE /secrets/:ref
 ### sequence
 
 **allocate**(collectionId: string, input: AllocateSequenceInput) → `Promise<AllocatedSequence>`
-Allocate (or return the existing) sequence number for a subject. Idempotent — safe to call on load (auto-enter) and on a button tap; a subject that already has a number gets it back with `isNew: false`. const { number, isNew } = await sequence.allocate(collectionId, { appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId, })
+Allocate (or return the existing) sequence number for a subject. Idempotent — safe to call on load (auto-enter) and on a button tap; a subject that already has a number gets it back with `isNew: false`. const { number, isNew } = await sequence.allocate(collectionId, { appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId, }) `ctx.sl.counters.next()` + `ctx.sl.appRecords.claim()` (docs/server-functions.md).
 
 ### sessions
 

package/dist/docs/comms.md

@@ -320,14 +320,30 @@ link; nothing is consented until it's clicked. The answer is always the same, so
 used to find out who's registered.
 
 ```typescript
-await comms.signup('collectionId', { email: 'sam@example.com', topics: ['newsletter'] })
+await comms.signup('collectionId', {
+  email: 'sam@example.com',
+  topics: ['newsletter'],
+  templateId: config.confirmationTemplateId, // YOUR confirmation email (required)
+  fields: { firstName: 'Sam', customFields: { favouriteStore: 'Leeds' } }, // optional
+  appId: 'my-newsletter',
+})
 // → { ok: true, pending: true }  — tell the visitor to check their inbox
 ```
 
+- **The confirmation email is the app's own** (emails belong to the app that runs the flow — there is
+  no platform default): a template in the collection, created and edited in the app's admin, e.g.
+  `SL.template.create(collectionId, { name: 'Confirm your subscription', type: 'email', engine: 'liquid',
+  subject: 'Please confirm your subscription', body: '…<a href="{{ action_url }}">Yes, subscribe me</a>…' })`.
+  It gets `{{ action_url }}` (the confirm link), `{{ topics }}` (labels) and `{{ contact.firstName }}`.
+- **Form answers** (`fields`) are applied only once the address is confirmed, and only to the
+  contact's empty fields — a sign-up can never overwrite someone else's details.
+
 - Topics must exist in the collection's comm settings. Give a newsletter topic
   `defaults.policy: 'opt-in'`: broadcasts on an opt-in topic only reach people who said yes
   (confirmed sign-ups), never the whole contact list.
 - Confirming turns on the email channel and the topics, and marks the address verified.
+- Don't use `contact.publicUpsert` + `comms.upsertConsent` for a signed-out form: consent calls act only
+  for the signed-in contact. `comms.signup` is the signed-out path.
 - Set comm settings `signup.confirmedUrl` (https) to send people to your own "thanks" page after
   they confirm (`?confirmed=1`, or `0` for an expired link); otherwise SmartLinks shows a short page.
 

package/dist/docs/overview.md

@@ -93,7 +93,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Container Tracking** | `docs/container-tracking.md` | Physical/logical **item** container groupings — *not* app containers (see containers.md) |
 | **Lots** | `docs/lots.md` | Cross-SKU production "Lot" entity |
 | **Loyalty** | `docs/loyalty.md` | Points, members, earning rules |
-| **Sequences** | `docs/sequences.md` | Atomic monotonic number allocation (raffle / queue / edition) |
+| **Sequences** | `docs/sequences.md` | RETIRING — number things in your own server function: `ctx.sl.counters` + `appRecords.claim` (server-functions.md) |
 | **Integrations** | `docs/integrations.md` | Inbound/outbound external-system integration flows |
 | **Item Context** | `docs/item-context.md` | The `itemContext` container prop (serial / NFC authenticity context) |
 | **Native Facade** | `docs/native-facade.md` | `host.native` / `SL.native` device-capability facade |

package/dist/docs/sequences.md

@@ -1,5 +1,11 @@
 # Sequences & claim-order allocation
 
+> **Retiring — don't build on this.** `SL.sequence.allocate` is being removed. Number things in your
+> app's own server function instead: `ctx.sl.counters.next()` for the next number and
+> `ctx.sl.appRecords.claim()` to key it to a tag/person and make sure no number is ever held twice —
+> see server-functions.md → "Uniqueness, numbering and people". (The counter here lived inside the
+> app config doc, where an admin save could rewind it.)
+
 > **SmartLinks SDK 2.x** (current `latest`). Install `@proveanything/smartlinks@^2`.
 
 A **sequence** hands out a guaranteed-unique, monotonic number — `1, 2, 3, …` — and stamps it

package/dist/docs/server-functions.md

@@ -182,8 +182,9 @@ interface ServerFunctionContext {
   appId: string
 
   /** SmartLinks SDK, pre-scoped to your declared `authority`. Capabilities cap what it may do.
-   *  Key resources: `sl.appRecords` (per-app records), `sl.appData` (general/app-wide config +
-   *  data — URLs, flags, counters, arrays), `sl.products`, `sl.attestations`. */
+   *  Key resources: `sl.appRecords` (per-app records, incl. race-safe `claim`), `sl.appData`
+   *  (general/app-wide config + data — URLs, flags, arrays), `sl.counters` (atomic numbering),
+   *  `sl.tags`, `sl.contacts`, `sl.interactions`, `sl.products`, `sl.attestations`. */
   sl: SmartLinks
 
   /** Capability-gated secrets (need `secrets:<name>`). `get(name)` reads this app's own secret on the
@@ -506,7 +507,11 @@ Prefer the platform primitives above over a dependency; when you do need one, pi
 | Read or write SmartLinks data | `ctx.sl.*` (records, products, attestations, …) | the matching `sl:<res>:<read\|write>` |
 | Read/write your app's own data (config, URLs, counters, arrays) | `ctx.sl.appData.get()` / `ctx.sl.appData.set({…})` — collection-scoped by default; `ctx.sl.appData.global.*` (or `{ scope:'global' }`, or declare `dataScope:'global'`) for the app-wide bucket. It's your OWN namespace, so **any** authority may read/write it | `sl:data:read` / `sl:data:write` |
 | Read ANOTHER app's data (as the caller may see it) | `ctx.sl.app('other-app').data.get()` — caller-authority, this collection, public-filtered, read-only | `sl:data:read` |
-| Guarantee a UNIQUE claim (pool of numbers, one-per-user, idempotency key) | `ctx.sl.appRecords.create({ ref: 'ball:57' })` — the DB unique index rejects a duplicate `ref` (catch = "already taken") | `sl:records:write` |
+| Guarantee a UNIQUE claim (one entry per tag, one-per-user, idempotency key, a number nobody else holds) | `ctx.sl.appRecords.claim({ …, singletonPer, customId })` → `{ record, created, conflict? }` — see below | `sl:records:write` |
+| Hand out the next number (tickets, order numbers) | `ctx.sl.counters.next('tickets')` — atomic, distinct per caller | `sl:data:write` |
+| Check a tapped tag is real | `ctx.sl.tags.resolve(proofId)` → `{ id, claimSetId, code }` or `null` | `sl:tags:read` |
+| Put a visitor's details on a contact | `ctx.sl.contacts.upsert({ email, firstName, … })` → `{ contactId, created }` (fills empty fields only) | `sl:contacts:write` |
+| Record "they did X" | `ctx.sl.interactions.record({ interactionId, contactId, outcome, metadata })` | `sl:interactions:write` |
 
 Notes:
 - **Talking to the SmartLinks core is `ctx.sl`, not HTTP.** The common pattern — *validate /
@@ -525,6 +530,81 @@ Notes:
 
 ---
 
+## Uniqueness, numbering and people — the race-safe primitives
+
+A public function is called by many people at once. These primitives make the outcome right no matter
+how the calls interleave — the **database** decides, never a read-then-write in your code.
+
+### `appRecords.claim(fields)` — a unique create
+
+Like `create`, but the record names a **unique key**, and it's inserted only if that key is free.
+Otherwise you get the record already holding it back, **unchanged** (never updated):
+
+```ts
+const { record, created, conflict } = await ctx.sl.appRecords.claim({
+  recordType: 'entry',
+  singletonPer: 'proof', proofId: tag.id,   // key 1: one live entry per tag
+  customId: String(number),                 // key 2: one record per number, ever
+  data: { number },
+})
+// created: true  → you got it
+// created: false → conflict 'singleton' (this tag already has an entry: `record` is it)
+//                  or 'customId' (that number is held by someone else: take another)
+```
+
+- **`singletonPer`** — `'collection' | 'product' | 'variant' | 'batch' | 'proof'`, with its anchor id
+  (`productId`, `proofId`, …). One **live** record per key; deleting it frees the key.
+- **`customId`** — unique per `(recordType, scopeType, scopeId, sourceSystem)`, case-insensitive, and
+  **never reused** (deleted records keep theirs). Right for numbers that must never be handed out twice.
+- Give at least one; with both, the record is created only if both are free.
+- Of any number of concurrent claims on one key, **exactly one** gets `created: true`.
+
+### `counters.next(name, { start?, by? })` — the next number
+
+An atomic counter for your app in this collection: every caller gets a distinct value, even under a
+burst (one row, incremented in one statement). The first call returns `start` (default 1). Counters only
+move forward and live apart from your config, so no config save can rewind one. `counters.get(name)`
+reads the last value handed out (`null` before the first). Name a new counter to start again from `start`.
+
+**Counter + claim = a number nobody else can ever hold.** Take `next()`, then `claim` with
+`customId: String(n)`. If the claim says `conflict: 'customId'`, take `next()` again. A failed or raced
+attempt only leaves a gap — never a duplicate.
+
+### `tags.resolve(id)` — is this tap real?
+
+A tap hands your app the virtual-proof id `<claimSetId>-<code>`. `resolve` returns
+`{ id, claimSetId, code }` when that code exists in a claim set of **this** collection, else `null`.
+Key records to the returned canonical `id`, and refuse `null` — otherwise anyone can invent ids.
+
+### `contacts.upsert(details)` / `contacts.forCaller()`
+
+`upsert` finds the contact by `email` or `phone` (one is required) or creates it, and only **fills
+empty fields** — it never overwrites a name or field the contact already has, because a visitor's typed
+details are unverified. It's race-safe: two simultaneous entries with one email end on one contact.
+Returns `{ contactId, created }`. `forCaller()` is the signed-in caller's own contact (`null` when
+anonymous). **Never return contact ids to public callers** — keep them on your records.
+
+This is not consent. A ticked "keep me updated" box is evidence you can record (below); subscribing
+someone to marketing is the double opt-in flow (`comms.signup`, see comms.md).
+
+### `interactions.record(event)` — "they did X"
+
+Records an event of one of **your app's interaction types**: create the type once in admin with
+`SL.interactions.ensureType(collectionId, { appId, key: 'raffle-entry' })`, keep its id in your app
+config, and pass that id. Unknown ids are refused (`INTERACTION_TYPE_NOT_FOUND`). The event runs the
+type's effects and emits `interaction.submitted`, like any submission.
+
+```ts
+await ctx.sl.interactions.record({
+  interactionId: config.interactionIds.entered,
+  contactId,                         // optional
+  outcome: 'entered',
+  metadata: { number, consent: true },
+})
+```
+
+---
+
 ## Worked example — a public competition entry
 
 ```ts
@@ -756,6 +836,9 @@ const ctx = createFunctionTestContext({
 
 const res = await submitCompetitionEntry(ctx, { method: 'POST', body: { email: 'a@b.com', answer: '42' } })
 // ctx.sl.appRecords.create(...) throws CapabilityError unless `def` declares sl:records:write
+// With no `sl` impl, records / counters / contacts / interactions run in memory with the platform's
+// uniqueness rules — assert on ctx.memory. Share createFunctionTestMemory() between contexts to
+// simulate concurrent callers; restrict ids with knownTags / knownInteractionTypes.
 ```
 
 Pass the **`def`** (not a hand-typed capability list) so "tested" can't drift from

package/dist/openapi.yaml

@@ -19218,16 +19218,113 @@ components:
     AppDataHandle:
       type: object
       properties: {}
+    AppRecordClaimResult:
+      type: object
+      properties:
+        record:
+          type: object
+          additionalProperties: true
+        created:
+          type: boolean
+        conflict:
+          type: string
+          enum:
+            - singleton
+            - customId
+      required:
+        - record
+        - created
+    ServerFunctionCounters:
+      type: object
+      properties: {}
+    ResolvedTag:
+      type: object
+      properties:
+        id:
+          type: string
+        claimSetId:
+          type: string
+        code:
+          type: string
+      required:
+        - id
+        - claimSetId
+        - code
+    ContactUpsertDetails:
+      type: object
+      properties:
+        email:
+          type: string
+        phone:
+          type: string
+        firstName:
+          type: string
+        lastName:
+          type: string
+        displayName:
+          type: string
+        company:
+          type: string
+        locale:
+          type: string
+        timezone:
+          type: string
+        customFields:
+          type: object
+          additionalProperties:
+            type: object
+            additionalProperties: true
+    ServerFunctionInteractionEvent:
+      type: object
+      properties:
+        interactionId:
+          type: string
+        contactId:
+          type: string
+        outcome:
+          type: string
+        metadata:
+          type: object
+          additionalProperties: true
+        productId:
+          type: string
+        proofId:
+          type: string
+        variantId:
+          type: string
+        batchId:
+          type: string
+        eventType:
+          type: string
+      required:
+        - interactionId
     ServerFunctionSl:
       type: object
       properties:
-        appRecords: {}
+        appRecords:
+          type: object
+          additionalProperties: true
+        counters:
+          $ref: "#/components/schemas/ServerFunctionCounters"
+        tags:
+          type: object
+          additionalProperties: true
+        contacts:
+          type: object
+          additionalProperties: true
+        interactions:
+          type: object
+          additionalProperties: true
         products: {}
         attestations: {}
         appData:
           $ref: "#/components/schemas/AppDataHandle"
       required:
         - appRecords
+        - counters
+        - tags
+        - contacts
+        - interactions
         - products
         - attestations
         - appData
@@ -23658,14 +23755,22 @@ components:
       properties:
         email:
           type: string
+        templateId:
+          type: string
         topics:
           type: array
           items:
             type: string
         firstName:
           type: string
+        fields:
+          type: object
+          additionalProperties: true
+        appId:
+          type: string
       required:
         - email
+        - templateId
     CommsSignupResponse:
       type: object
       properties:

package/dist/testing/index.d.ts

@@ -8,6 +8,7 @@ export declare class CapabilityError extends Error {
 export interface TestSlImpl {
     appRecords?: {
         create?(fields: any): any;
+        claim?(fields: any): any;
         update?(id: string, fields: any): any;
         upsert?(fields: any): any;
         delete?(id: string): any;
@@ -15,6 +16,21 @@ export interface TestSlImpl {
         query?(params: any): any;
         listTypes?(): any;
     };
+    counters?: {
+        next?(name: string, opts?: any): any;
+        get?(name: string): any;
+    };
+    /** Tag lookup. Default: any `<claimSetId>-<code>` resolves (pass `knownTags` to restrict). */
+    tags?: {
+        resolve?(id: string): any;
+    };
+    contacts?: {
+        upsert?(details: any): any;
+        forCaller?(): any;
+    };
+    interactions?: {
+        record?(event: any): any;
+    };
     products?: {
         get?(id: string, opts?: any): any;
         query?(body?: any, opts?: any): any;
@@ -64,7 +80,27 @@ export interface CreateFunctionTestContextOptions {
     fetch?: typeof fetch;
     /** What the platform would have prefetched as `ctx.inputs` (e.g. `{ entity: product }`). Default `{}`. */
     inputs?: ServerFunctionInputs;
+    /** Tags that exist, as `<claimSetId>-<code>` ids — `ctx.sl.tags.resolve` returns null for any other. */
+    knownTags?: string[];
+    /** Interaction type ids that exist for this app — `interactions.record` refuses others. Default: any. */
+    knownInteractionTypes?: string[];
+    /** Share one in-memory store between several contexts (e.g. concurrent callers in one test). */
+    memory?: FunctionTestMemory;
+}
+/** The harness's in-memory platform state (when no impl is injected). */
+export interface FunctionTestMemory {
+    records: any[];
+    counters: Record<string, number>;
+    contacts: Array<{
+        contactId: string;
+        email?: string;
+        phone?: string;
+        [k: string]: any;
+    }>;
+    interactions: any[];
 }
+/** A fresh in-memory store — pass the same one to several test contexts to simulate concurrent callers. */
+export declare function createFunctionTestMemory(): FunctionTestMemory;
 export interface FunctionTestContext extends ServerFunctionContext {
     /** Captured log lines (also written via ctx.log). */
     logs: Array<{
@@ -72,6 +108,8 @@ export interface FunctionTestContext extends ServerFunctionContext {
         message: string;
         data?: Record<string, any>;
     }>;
+    /** The in-memory platform state this context reads and writes. */
+    memory: FunctionTestMemory;
 }
 /**
  * Build a capability-enforcing test ctx for a server function. Run your handler with it:

package/dist/testing/index.js

@@ -14,6 +14,21 @@
 //  - `ctx.secrets` are FIXTURES you provide; real sealed secrets are server-only and
 //    never resolvable locally.
 //  - `ctx.fetch` is gated by the `network` capability just like production.
+//  - Without an injected impl, appRecords / counters / contacts / interactions run against an
+//    in-memory store with the platform's uniqueness rules (claim: singletonPer + customId; contacts by
+//    email/phone, fill-empty only), so idempotency and "never two of the same number" are testable.
+//    Inspect it via `ctx.memory`.
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 export class CapabilityError extends Error {
     constructor(capability, message) {
         super(message || `capability not granted: ${capability}`);
@@ -58,6 +73,10 @@ function allowsSl(p, resource, op) {
         return true; // write implies read
     return false;
 }
+/** A fresh in-memory store — pass the same one to several test contexts to simulate concurrent callers. */
+export function createFunctionTestMemory() {
+    return { records: [], counters: {}, contacts: [], interactions: [] };
+}
 const stub = (method, args) => ({ __stub: true, method, args });
 /**
  * Build a capability-enforcing test ctx for a server function. Run your handler with it:
@@ -79,18 +98,75 @@ export function createFunctionTestContext(opts) {
             throw new CapabilityError(`sl:${resource}:${op}`);
         return fn ? fn(...args) : stub(`${resource}.${name}`, args);
     };
+    const mem = opts.memory || createFunctionTestMemory();
     const ar = impl.appRecords || {};
     const pr = impl.products || {};
     const at = impl.attestations || {};
+    // In-memory records with the platform's unique keys (used when no appRecords impl is injected).
+    const singletonKey = (f) => {
+        const t = f.recordType || 'default';
+        switch (f.singletonPer) {
+            case 'collection': return `${t}:collection`;
+            case 'product': return f.productId ? `${t}:product:${f.productId}` : null;
+            case 'variant': return f.productId && f.variantId ? `${t}:variant:${f.productId}:${f.variantId}` : null;
+            case 'batch': return f.productId && f.batchId ? `${t}:batch:${f.productId}:${f.batchId}` : null;
+            case 'proof': return f.proofId ? `${t}:proof:${f.proofId}` : null;
+            default: return null;
+        }
+    };
+    const customKey = (f) => {
+        const c = f.customId == null ? '' : String(f.customId).trim().toLowerCase();
+        return c ? [f.recordType || 'default', f.scopeType || '', f.scopeId || '', f.sourceSystem || '', c].join('|') : null;
+    };
+    let nextRecordId = 1;
+    const memRecords = {
+        create: async (fields) => {
+            const rec = Object.assign({ id: `rec-${nextRecordId++}`, recordType: 'default', data: {}, admin: {}, status: 'active', createdAt: new Date().toISOString() }, fields);
+            mem.records.push(rec);
+            return Object.assign({}, rec);
+        },
+        claim: async (fields) => {
+            const sk = singletonKey(fields);
+            const ck = customKey(fields);
+            if (fields.singletonPer && !sk)
+                throw Object.assign(new Error(`claim: singletonPer "${fields.singletonPer}" needs its anchor id`), { code: 'INVALID_CLAIM' });
+            if (!sk && !ck)
+                throw Object.assign(new Error('claim: give the record a unique key — singletonPer (+ anchor) or customId'), { code: 'INVALID_CLAIM' });
+            const bySingleton = sk ? mem.records.find((r) => !r.deletedAt && singletonKey(r) === sk) : null;
+            if (bySingleton)
+                return { record: Object.assign({}, bySingleton), created: false, conflict: 'singleton' };
+            const byCustom = ck ? mem.records.find((r) => customKey(r) === ck) : null; // deleted records keep their customId
+            if (byCustom)
+                return { record: Object.assign({}, byCustom), created: false, conflict: 'customId' };
+            return { record: await memRecords.create(fields), created: true };
+        },
+        get: async (id) => { const r = mem.records.find((x) => x.id === id); return r ? Object.assign({}, r) : null; },
+        update: async (id, fields) => { const r = mem.records.find((x) => x.id === id); if (!r)
+            return null; Object.assign(r, fields); return Object.assign({}, r); },
+        delete: async (id) => { const r = mem.records.find((x) => x.id === id); if (r)
+            r.deletedAt = new Date().toISOString(); return {}; },
+        // Simple equality filter on top-level fields (recordType, proofId, customId, status, …).
+        query: async (params = {}) => {
+            const _a = params || {}, { limit, offset, sort } = _a, where = __rest(_a, ["limit", "offset", "sort"]);
+            const all = mem.records.filter((r) => !r.deletedAt && Object.entries(where).every(([k, v]) => r[k] === v));
+            const from = offset || 0;
+            const size = limit || 200;
+            const data = all.slice(from, from + size).map((r) => (Object.assign({}, r)));
+            // Same envelope as the platform: { data, pagination }.
+            return { data, pagination: { total: all.length, limit: size, offset: from, hasMore: from + data.length < all.length } };
+        },
+    };
+    const recordsFn = (name) => ar[name] ? ar[name].bind(ar) : (impl.appRecords ? undefined : memRecords[name]);
     const sl = {
         appRecords: {
-            create: gated('records', 'write', ar.create && ar.create.bind(ar), 'create'),
-            update: gated('records', 'write', ar.update && ar.update.bind(ar), 'update'),
-            upsert: gated('records', 'write', ar.upsert && ar.upsert.bind(ar), 'upsert'),
-            delete: gated('records', 'write', ar.delete && ar.delete.bind(ar), 'delete'),
-            get: gated('records', 'read', ar.get && ar.get.bind(ar), 'get'),
-            query: gated('records', 'read', ar.query && ar.query.bind(ar), 'query'),
-            listTypes: gated('records', 'read', ar.listTypes && ar.listTypes.bind(ar), 'listTypes'),
+            create: gated('records', 'write', recordsFn('create'), 'create'),
+            claim: gated('records', 'write', recordsFn('claim'), 'claim'),
+            update: gated('records', 'write', recordsFn('update'), 'update'),
+            upsert: gated('records', 'write', recordsFn('upsert'), 'upsert'),
+            delete: gated('records', 'write', recordsFn('delete'), 'delete'),
+            get: gated('records', 'read', recordsFn('get'), 'get'),
+            query: gated('records', 'read', recordsFn('query'), 'query'),
+            listTypes: gated('records', 'read', recordsFn('listTypes'), 'listTypes'),
         },
         products: {
             get: gated('products', 'read', pr.get && pr.get.bind(pr), 'get'),
@@ -122,6 +198,62 @@ export function createFunctionTestContext(opts) {
                 delete memConfig[k]; }), 'delete'),
     });
     sl.appData = Object.assign(makeAppData(), { global: makeAppData(), collection: makeAppData() });
+    const cn = impl.counters || {};
+    sl.counters = {
+        next: gated('data', 'write', cn.next ? cn.next.bind(cn) : (async (name, o = {}) => {
+            var _a, _b;
+            const start = (_a = o.start) !== null && _a !== void 0 ? _a : 1;
+            const by = (_b = o.by) !== null && _b !== void 0 ? _b : 1;
+            mem.counters[name] = mem.counters[name] == null ? start : mem.counters[name] + by;
+            return mem.counters[name];
+        }), 'counters.next'),
+        get: gated('data', 'read', cn.get ? cn.get.bind(cn) : (async (name) => { var _a; return (_a = mem.counters[name]) !== null && _a !== void 0 ? _a : null; }), 'counters.get'),
+    };
+    const tg = impl.tags || {};
+    sl.tags = {
+        resolve: gated('tags', 'read', tg.resolve ? tg.resolve.bind(tg) : (async (id) => {
+            const s = String(id || '');
+            const i = s.indexOf('-');
+            if (i <= 0 || i >= s.length - 1)
+                return null;
+            if (opts.knownTags && !opts.knownTags.includes(s))
+                return null;
+            return { id: s, claimSetId: s.slice(0, i), code: s.slice(i + 1) };
+        }), 'tags.resolve'),
+    };
+    const ct = impl.contacts || {};
+    const fillable = ['firstName', 'lastName', 'displayName', 'company', 'locale', 'timezone'];
+    sl.contacts = {
+        upsert: gated('contacts', 'write', ct.upsert ? ct.upsert.bind(ct) : (async (d = {}) => {
+            const email = d.email ? String(d.email).trim().toLowerCase() : undefined;
+            const phone = d.phone ? String(d.phone).replace(/[^\d+]/g, '') : undefined;
+            if (!email && !phone)
+                throw Object.assign(new Error('contacts.upsert: an email or phone is required'), { code: 'CONTACT_IDENTITY_REQUIRED' });
+            const found = mem.contacts.find((c) => (email && c.email === email) || (phone && c.phone === phone));
+            if (found) {
+                for (const k of fillable)
+                    if (d[k] && !found[k])
+                        found[k] = d[k];
+                found.customFields = Object.assign(Object.assign({}, (d.customFields || {})), (found.customFields || {}));
+                return { contactId: found.contactId, created: false };
+            }
+            const contactId = `contact-${mem.contacts.length + 1}`;
+            mem.contacts.push(Object.assign(Object.assign({}, d), { email, phone, contactId }));
+            return { contactId, created: true };
+        }), 'contacts.upsert'),
+        forCaller: gated('contacts', 'write', ct.forCaller ? ct.forCaller.bind(ct) : (async () => (opts.caller && opts.caller.userId ? { contactId: `contact-of-${opts.caller.userId}` } : null)), 'contacts.forCaller'),
+    };
+    const it = impl.interactions || {};
+    sl.interactions = {
+        record: gated('interactions', 'write', it.record ? it.record.bind(it) : (async (event = {}) => {
+            if (!event.interactionId || (opts.knownInteractionTypes && !opts.knownInteractionTypes.includes(event.interactionId))) {
+                throw Object.assign(new Error(`"${event.interactionId}" is not an interaction type of this app`), { code: 'INTERACTION_TYPE_NOT_FOUND' });
+            }
+            const eventId = `event-${mem.interactions.length + 1}`;
+            mem.interactions.push(Object.assign(Object.assign({}, event), { eventId, userId: (opts.caller && opts.caller.userId) || null }));
+            return { eventId };
+        }), 'interactions.record'),
+    };
     sl.app = (appId) => {
         const other = (impl.app && impl.app(appId)) || {};
         const od = other.data || {};
@@ -178,5 +310,6 @@ export function createFunctionTestContext(opts) {
         },
         inputs: Object.freeze(Object.assign({}, (opts.inputs || {}))),
         logs,
+        memory: mem,
     };
 }

package/dist/types/appManifest.d.ts

@@ -365,9 +365,96 @@ export interface AppDataHandle {
  *  - by CALLER identity — everything else (products, attestations, and `app(id)` cross-app reads)
  *    is bounded by what the invoking user could do through the permissioned API.
  */
+/** `ctx.sl.appRecords.claim` result. `conflict` says which unique key was already held. */
+export interface AppRecordClaimResult<T = any> {
+    record: T;
+    created: boolean;
+    conflict?: 'singleton' | 'customId';
+}
+/** `ctx.sl.counters` — this app's atomic named counters in the collection. */
+export interface ServerFunctionCounters {
+    /** The next value — distinct for every caller, even under a burst. First call returns `start` (default 1). */
+    next(name: string, opts?: {
+        start?: number;
+        by?: number;
+    }): Promise<number>;
+    /** The last value handed out, or `null` before the first `next`. */
+    get(name: string): Promise<number | null>;
+}
+/** A tap's tag, resolved and checked to belong to this collection. */
+export interface ResolvedTag {
+    /** Canonical virtual-proof id `<claimSetId>-<code>` — key things to THIS, not the raw input. */
+    id: string;
+    claimSetId: string;
+    code: string;
+}
+/** Contact details a function may pass to `ctx.sl.contacts.upsert` (plain strings, capped). */
+export interface ContactUpsertDetails {
+    email?: string;
+    phone?: string;
+    firstName?: string;
+    lastName?: string;
+    displayName?: string;
+    company?: string;
+    locale?: string;
+    timezone?: string;
+    customFields?: Record<string, string | number | boolean>;
+}
+/** An interaction event recorded from a server function. */
+export interface ServerFunctionInteractionEvent {
+    /** The interaction TYPE id — created first in admin with `interactions.ensureType`, kept in config. */
+    interactionId: string;
+    contactId?: string | null;
+    /** e.g. 'entered'. Letters, digits, `. : - _`. Default 'submitted'. */
+    outcome?: string;
+    metadata?: Record<string, any>;
+    productId?: string;
+    proofId?: string;
+    variantId?: string;
+    batchId?: string;
+    eventType?: string;
+}
 export interface ServerFunctionSl {
-    /** THIS app's records (own namespace). */
-    appRecords: any;
+    /**
+     * THIS app's records (own namespace): create / update / upsert / delete / get / query / listTypes,
+     * plus `claim(fields)` — a race-safe UNIQUE create. The record names a unique key — `singletonPer`
+     * (+ its anchor, e.g. `{ singletonPer: 'proof', proofId }`) and/or `customId` — and is inserted only
+     * if the key is free; otherwise the record holding it comes back UNCHANGED with `created: false`.
+     * Of any number of concurrent claims on one key, exactly one is created (the database decides).
+     */
+    appRecords: {
+        claim(fields: Record<string, any>): Promise<AppRecordClaimResult>;
+        [method: string]: any;
+    };
+    /** Atomic named counters for this app in this collection (`sl:data:write` / `sl:data:read`). */
+    counters: ServerFunctionCounters;
+    /** Tags (`sl:tags:read`): `resolve(id)` → the real tag in THIS collection, or `null` for a made-up id. */
+    tags: {
+        resolve(id: string): Promise<ResolvedTag | null>;
+    };
+    /**
+     * Contacts (`sl:contacts:write`). `upsert` finds by email/phone or creates, and only FILLS EMPTY
+     * fields — never overwrites (details typed by a visitor are unverified). `forCaller` is the signed-in
+     * caller's own contact (null when anonymous). Never return contact ids to public callers.
+     */
+    contacts: {
+        upsert(details: ContactUpsertDetails): Promise<{
+            contactId: string;
+            created: boolean;
+        }>;
+        forCaller(): Promise<{
+            contactId: string;
+        } | null>;
+    };
+    /**
+     * Interactions (`sl:interactions:write`). `record` stores an event of one of THIS app's interaction
+     * types (refused if the type doesn't exist), runs the type's effects and emits `interaction.submitted`.
+     */
+    interactions: {
+        record(event: ServerFunctionInteractionEvent): Promise<{
+            eventId: string;
+        }>;
+    };
     /** Products, scoped by caller authority + declared capability. */
     products: any;
     /** Attestations, scoped by caller authority + declared capability. */

package/dist/types/comms.d.ts

@@ -184,9 +184,31 @@ export interface UnsubscribeResponse {
 }
 export interface CommsSignupRequest {
     email: string;
+    /**
+     * Required: YOUR app's confirmation email — a template in this collection (SL.template) whose body
+     * uses `{{ action_url }}` for the confirm link (`{{ topics }}` lists what they signed up for). The
+     * platform sends no default sign-up email.
+     */
+    templateId: string;
     /** Topic ids from the collection's comm settings (e.g. ["newsletter"]). */
     topics?: string[];
     firstName?: string;
+    /**
+     * The form's other answers — firstName/lastName/displayName/company/locale/timezone and
+     * `customFields`. Applied to the contact when the address is confirmed, and only where the contact
+     * has no value yet (never overwritten). Small: ~2 KB.
+     */
+    fields?: {
+        firstName?: string;
+        lastName?: string;
+        displayName?: string;
+        company?: string;
+        locale?: string;
+        timezone?: string;
+        customFields?: Record<string, string | number | boolean>;
+    };
+    /** Your app id, recorded with the sent email. */
+    appId?: string;
 }
 export interface CommsSignupResponse {
     ok: true;

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.50  |  Generated: 2026-10-09T10:28:38.661Z
+Version: 2.0.51  |  Generated: 2026-10-10T07:57:23.889Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2600,10 +2600,73 @@ interface AppDataHandle {
 }
 ```
 
+**AppRecordClaimResult<T = any>** (interface)
+```typescript
+interface AppRecordClaimResult<T = any> {
+  record: T;
+  created: boolean;
+  conflict?: 'singleton' | 'customId';
+}
+```
+
+**ServerFunctionCounters** (interface)
+```typescript
+interface ServerFunctionCounters {
+  next(name: string, opts?: { start?: number; by?: number }): Promise<number>;
+  get(name: string): Promise<number | null>;
+}
+```
+
+**ResolvedTag** (interface)
+```typescript
+interface ResolvedTag {
+  id: string;
+  claimSetId: string;
+  code: string;
+}
+```
+
+**ContactUpsertDetails** (interface)
+```typescript
+interface ContactUpsertDetails {
+  email?: string;
+  phone?: string;
+  firstName?: string;
+  lastName?: string;
+  displayName?: string;
+  company?: string;
+  locale?: string;
+  timezone?: string;
+  customFields?: Record<string, string | number | boolean>;
+}
+```
+
+**ServerFunctionInteractionEvent** (interface)
+```typescript
+interface ServerFunctionInteractionEvent {
+  interactionId: string;
+  contactId?: string | null;
+  outcome?: string;
+  metadata?: Record<string, any>;
+  productId?: string;
+  proofId?: string;
+  variantId?: string;
+  batchId?: string;
+  eventType?: string;
+}
+```
+
 **ServerFunctionSl** (interface)
 ```typescript
 interface ServerFunctionSl {
-  appRecords: any;
+  appRecords: { claim(fields: Record<string, any>): Promise<AppRecordClaimResult>; [method: string]: any };
+  counters: ServerFunctionCounters;
+  tags: { resolve(id: string): Promise<ResolvedTag | null> };
+  contacts: {
+  upsert(details: ContactUpsertDetails): Promise<{ contactId: string; created: boolean }>;
+  forCaller(): Promise<{ contactId: string } | null>;
+  };
+  interactions: { record(event: ServerFunctionInteractionEvent): Promise<{ eventId: string }> };
   products: any;
   attestations: any;
   appData: AppDataHandle & { global: AppDataHandle; collection: AppDataHandle };
@@ -5229,8 +5292,11 @@ interface UnsubscribeResponse {
 ```typescript
 interface CommsSignupRequest {
   email: string
+  templateId: string
   topics?: string[]
   firstName?: string
+  fields?: { firstName?: string; lastName?: string; displayName?: string; company?: string; locale?: string; timezone?: string; customFields?: Record<string, string | number | boolean> }
+  appId?: string
 }
 ```
 
@@ -5597,9 +5663,23 @@ export interface UnsubscribeResponse { ok: true; applied?: { channels?: Record<s
 // Public sign-up (double opt-in)
 export interface CommsSignupRequest {
   email: string
+  /**
+   * Required: YOUR app's confirmation email — a template in this collection (SL.template) whose body
+   * uses `{{ action_url }}` for the confirm link (`{{ topics }}` lists what they signed up for). The
+   * platform sends no default sign-up email.
+   */
+  templateId: string
   /** Topic ids from the collection's comm settings (e.g. ["newsletter"]). */
   topics?: string[]
   firstName?: string
+  /**
+   * The form's other answers — firstName/lastName/displayName/company/locale/timezone and
+   * `customFields`. Applied to the contact when the address is confirmed, and only where the contact
+   * has no value yet (never overwritten). Small: ~2 KB.
+   */
+  fields?: { firstName?: string; lastName?: string; displayName?: string; company?: string; locale?: string; timezone?: string; customFields?: Record<string, string | number | boolean> }
+  /** Your app id, recorded with the sent email. */
+  appId?: string
 }
 export interface CommsSignupResponse { ok: true; pending: true }
 
@@ -12157,7 +12237,7 @@ Soft-delete a secret. DELETE /secrets/:ref
 ### sequence
 
 **allocate**(collectionId: string, input: AllocateSequenceInput) → `Promise<AllocatedSequence>`
-Allocate (or return the existing) sequence number for a subject. Idempotent — safe to call on load (auto-enter) and on a button tap; a subject that already has a number gets it back with `isNew: false`. const { number, isNew } = await sequence.allocate(collectionId, { appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId, })
+Allocate (or return the existing) sequence number for a subject. Idempotent — safe to call on load (auto-enter) and on a button tap; a subject that already has a number gets it back with `isNew: false`. const { number, isNew } = await sequence.allocate(collectionId, { appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId, }) `ctx.sl.counters.next()` + `ctx.sl.appRecords.claim()` (docs/server-functions.md).
 
 ### sessions
 

package/docs/comms.md

@@ -320,14 +320,30 @@ link; nothing is consented until it's clicked. The answer is always the same, so
 used to find out who's registered.
 
 ```typescript
-await comms.signup('collectionId', { email: 'sam@example.com', topics: ['newsletter'] })
+await comms.signup('collectionId', {
+  email: 'sam@example.com',
+  topics: ['newsletter'],
+  templateId: config.confirmationTemplateId, // YOUR confirmation email (required)
+  fields: { firstName: 'Sam', customFields: { favouriteStore: 'Leeds' } }, // optional
+  appId: 'my-newsletter',
+})
 // → { ok: true, pending: true }  — tell the visitor to check their inbox
 ```
 
+- **The confirmation email is the app's own** (emails belong to the app that runs the flow — there is
+  no platform default): a template in the collection, created and edited in the app's admin, e.g.
+  `SL.template.create(collectionId, { name: 'Confirm your subscription', type: 'email', engine: 'liquid',
+  subject: 'Please confirm your subscription', body: '…<a href="{{ action_url }}">Yes, subscribe me</a>…' })`.
+  It gets `{{ action_url }}` (the confirm link), `{{ topics }}` (labels) and `{{ contact.firstName }}`.
+- **Form answers** (`fields`) are applied only once the address is confirmed, and only to the
+  contact's empty fields — a sign-up can never overwrite someone else's details.
+
 - Topics must exist in the collection's comm settings. Give a newsletter topic
   `defaults.policy: 'opt-in'`: broadcasts on an opt-in topic only reach people who said yes
   (confirmed sign-ups), never the whole contact list.
 - Confirming turns on the email channel and the topics, and marks the address verified.
+- Don't use `contact.publicUpsert` + `comms.upsertConsent` for a signed-out form: consent calls act only
+  for the signed-in contact. `comms.signup` is the signed-out path.
 - Set comm settings `signup.confirmedUrl` (https) to send people to your own "thanks" page after
   they confirm (`?confirmed=1`, or `0` for an expired link); otherwise SmartLinks shows a short page.
 

package/docs/overview.md

@@ -93,7 +93,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Container Tracking** | `docs/container-tracking.md` | Physical/logical **item** container groupings — *not* app containers (see containers.md) |
 | **Lots** | `docs/lots.md` | Cross-SKU production "Lot" entity |
 | **Loyalty** | `docs/loyalty.md` | Points, members, earning rules |
-| **Sequences** | `docs/sequences.md` | Atomic monotonic number allocation (raffle / queue / edition) |
+| **Sequences** | `docs/sequences.md` | RETIRING — number things in your own server function: `ctx.sl.counters` + `appRecords.claim` (server-functions.md) |
 | **Integrations** | `docs/integrations.md` | Inbound/outbound external-system integration flows |
 | **Item Context** | `docs/item-context.md` | The `itemContext` container prop (serial / NFC authenticity context) |
 | **Native Facade** | `docs/native-facade.md` | `host.native` / `SL.native` device-capability facade |

package/docs/sequences.md

@@ -1,5 +1,11 @@
 # Sequences & claim-order allocation
 
+> **Retiring — don't build on this.** `SL.sequence.allocate` is being removed. Number things in your
+> app's own server function instead: `ctx.sl.counters.next()` for the next number and
+> `ctx.sl.appRecords.claim()` to key it to a tag/person and make sure no number is ever held twice —
+> see server-functions.md → "Uniqueness, numbering and people". (The counter here lived inside the
+> app config doc, where an admin save could rewind it.)
+
 > **SmartLinks SDK 2.x** (current `latest`). Install `@proveanything/smartlinks@^2`.
 
 A **sequence** hands out a guaranteed-unique, monotonic number — `1, 2, 3, …` — and stamps it

package/docs/server-functions.md

@@ -182,8 +182,9 @@ interface ServerFunctionContext {
   appId: string
 
   /** SmartLinks SDK, pre-scoped to your declared `authority`. Capabilities cap what it may do.
-   *  Key resources: `sl.appRecords` (per-app records), `sl.appData` (general/app-wide config +
-   *  data — URLs, flags, counters, arrays), `sl.products`, `sl.attestations`. */
+   *  Key resources: `sl.appRecords` (per-app records, incl. race-safe `claim`), `sl.appData`
+   *  (general/app-wide config + data — URLs, flags, arrays), `sl.counters` (atomic numbering),
+   *  `sl.tags`, `sl.contacts`, `sl.interactions`, `sl.products`, `sl.attestations`. */
   sl: SmartLinks
 
   /** Capability-gated secrets (need `secrets:<name>`). `get(name)` reads this app's own secret on the
@@ -506,7 +507,11 @@ Prefer the platform primitives above over a dependency; when you do need one, pi
 | Read or write SmartLinks data | `ctx.sl.*` (records, products, attestations, …) | the matching `sl:<res>:<read\|write>` |
 | Read/write your app's own data (config, URLs, counters, arrays) | `ctx.sl.appData.get()` / `ctx.sl.appData.set({…})` — collection-scoped by default; `ctx.sl.appData.global.*` (or `{ scope:'global' }`, or declare `dataScope:'global'`) for the app-wide bucket. It's your OWN namespace, so **any** authority may read/write it | `sl:data:read` / `sl:data:write` |
 | Read ANOTHER app's data (as the caller may see it) | `ctx.sl.app('other-app').data.get()` — caller-authority, this collection, public-filtered, read-only | `sl:data:read` |
-| Guarantee a UNIQUE claim (pool of numbers, one-per-user, idempotency key) | `ctx.sl.appRecords.create({ ref: 'ball:57' })` — the DB unique index rejects a duplicate `ref` (catch = "already taken") | `sl:records:write` |
+| Guarantee a UNIQUE claim (one entry per tag, one-per-user, idempotency key, a number nobody else holds) | `ctx.sl.appRecords.claim({ …, singletonPer, customId })` → `{ record, created, conflict? }` — see below | `sl:records:write` |
+| Hand out the next number (tickets, order numbers) | `ctx.sl.counters.next('tickets')` — atomic, distinct per caller | `sl:data:write` |
+| Check a tapped tag is real | `ctx.sl.tags.resolve(proofId)` → `{ id, claimSetId, code }` or `null` | `sl:tags:read` |
+| Put a visitor's details on a contact | `ctx.sl.contacts.upsert({ email, firstName, … })` → `{ contactId, created }` (fills empty fields only) | `sl:contacts:write` |
+| Record "they did X" | `ctx.sl.interactions.record({ interactionId, contactId, outcome, metadata })` | `sl:interactions:write` |
 
 Notes:
 - **Talking to the SmartLinks core is `ctx.sl`, not HTTP.** The common pattern — *validate /
@@ -525,6 +530,81 @@ Notes:
 
 ---
 
+## Uniqueness, numbering and people — the race-safe primitives
+
+A public function is called by many people at once. These primitives make the outcome right no matter
+how the calls interleave — the **database** decides, never a read-then-write in your code.
+
+### `appRecords.claim(fields)` — a unique create
+
+Like `create`, but the record names a **unique key**, and it's inserted only if that key is free.
+Otherwise you get the record already holding it back, **unchanged** (never updated):
+
+```ts
+const { record, created, conflict } = await ctx.sl.appRecords.claim({
+  recordType: 'entry',
+  singletonPer: 'proof', proofId: tag.id,   // key 1: one live entry per tag
+  customId: String(number),                 // key 2: one record per number, ever
+  data: { number },
+})
+// created: true  → you got it
+// created: false → conflict 'singleton' (this tag already has an entry: `record` is it)
+//                  or 'customId' (that number is held by someone else: take another)
+```
+
+- **`singletonPer`** — `'collection' | 'product' | 'variant' | 'batch' | 'proof'`, with its anchor id
+  (`productId`, `proofId`, …). One **live** record per key; deleting it frees the key.
+- **`customId`** — unique per `(recordType, scopeType, scopeId, sourceSystem)`, case-insensitive, and
+  **never reused** (deleted records keep theirs). Right for numbers that must never be handed out twice.
+- Give at least one; with both, the record is created only if both are free.
+- Of any number of concurrent claims on one key, **exactly one** gets `created: true`.
+
+### `counters.next(name, { start?, by? })` — the next number
+
+An atomic counter for your app in this collection: every caller gets a distinct value, even under a
+burst (one row, incremented in one statement). The first call returns `start` (default 1). Counters only
+move forward and live apart from your config, so no config save can rewind one. `counters.get(name)`
+reads the last value handed out (`null` before the first). Name a new counter to start again from `start`.
+
+**Counter + claim = a number nobody else can ever hold.** Take `next()`, then `claim` with
+`customId: String(n)`. If the claim says `conflict: 'customId'`, take `next()` again. A failed or raced
+attempt only leaves a gap — never a duplicate.
+
+### `tags.resolve(id)` — is this tap real?
+
+A tap hands your app the virtual-proof id `<claimSetId>-<code>`. `resolve` returns
+`{ id, claimSetId, code }` when that code exists in a claim set of **this** collection, else `null`.
+Key records to the returned canonical `id`, and refuse `null` — otherwise anyone can invent ids.
+
+### `contacts.upsert(details)` / `contacts.forCaller()`
+
+`upsert` finds the contact by `email` or `phone` (one is required) or creates it, and only **fills
+empty fields** — it never overwrites a name or field the contact already has, because a visitor's typed
+details are unverified. It's race-safe: two simultaneous entries with one email end on one contact.
+Returns `{ contactId, created }`. `forCaller()` is the signed-in caller's own contact (`null` when
+anonymous). **Never return contact ids to public callers** — keep them on your records.
+
+This is not consent. A ticked "keep me updated" box is evidence you can record (below); subscribing
+someone to marketing is the double opt-in flow (`comms.signup`, see comms.md).
+
+### `interactions.record(event)` — "they did X"
+
+Records an event of one of **your app's interaction types**: create the type once in admin with
+`SL.interactions.ensureType(collectionId, { appId, key: 'raffle-entry' })`, keep its id in your app
+config, and pass that id. Unknown ids are refused (`INTERACTION_TYPE_NOT_FOUND`). The event runs the
+type's effects and emits `interaction.submitted`, like any submission.
+
+```ts
+await ctx.sl.interactions.record({
+  interactionId: config.interactionIds.entered,
+  contactId,                         // optional
+  outcome: 'entered',
+  metadata: { number, consent: true },
+})
+```
+
+---
+
 ## Worked example — a public competition entry
 
 ```ts
@@ -756,6 +836,9 @@ const ctx = createFunctionTestContext({
 
 const res = await submitCompetitionEntry(ctx, { method: 'POST', body: { email: 'a@b.com', answer: '42' } })
 // ctx.sl.appRecords.create(...) throws CapabilityError unless `def` declares sl:records:write
+// With no `sl` impl, records / counters / contacts / interactions run in memory with the platform's
+// uniqueness rules — assert on ctx.memory. Share createFunctionTestMemory() between contexts to
+// simulate concurrent callers; restrict ids with knownTags / knownInteractionTypes.
 ```
 
 Pass the **`def`** (not a hand-typed capability list) so "tested" can't drift from

package/openapi.yaml

@@ -19218,16 +19218,113 @@ components:
     AppDataHandle:
       type: object
       properties: {}
+    AppRecordClaimResult:
+      type: object
+      properties:
+        record:
+          type: object
+          additionalProperties: true
+        created:
+          type: boolean
+        conflict:
+          type: string
+          enum:
+            - singleton
+            - customId
+      required:
+        - record
+        - created
+    ServerFunctionCounters:
+      type: object
+      properties: {}
+    ResolvedTag:
+      type: object
+      properties:
+        id:
+          type: string
+        claimSetId:
+          type: string
+        code:
+          type: string
+      required:
+        - id
+        - claimSetId
+        - code
+    ContactUpsertDetails:
+      type: object
+      properties:
+        email:
+          type: string
+        phone:
+          type: string
+        firstName:
+          type: string
+        lastName:
+          type: string
+        displayName:
+          type: string
+        company:
+          type: string
+        locale:
+          type: string
+        timezone:
+          type: string
+        customFields:
+          type: object
+          additionalProperties:
+            type: object
+            additionalProperties: true
+    ServerFunctionInteractionEvent:
+      type: object
+      properties:
+        interactionId:
+          type: string
+        contactId:
+          type: string
+        outcome:
+          type: string
+        metadata:
+          type: object
+          additionalProperties: true
+        productId:
+          type: string
+        proofId:
+          type: string
+        variantId:
+          type: string
+        batchId:
+          type: string
+        eventType:
+          type: string
+      required:
+        - interactionId
     ServerFunctionSl:
       type: object
       properties:
-        appRecords: {}
+        appRecords:
+          type: object
+          additionalProperties: true
+        counters:
+          $ref: "#/components/schemas/ServerFunctionCounters"
+        tags:
+          type: object
+          additionalProperties: true
+        contacts:
+          type: object
+          additionalProperties: true
+        interactions:
+          type: object
+          additionalProperties: true
         products: {}
         attestations: {}
         appData:
           $ref: "#/components/schemas/AppDataHandle"
       required:
         - appRecords
+        - counters
+        - tags
+        - contacts
+        - interactions
         - products
         - attestations
         - appData
@@ -23658,14 +23755,22 @@ components:
       properties:
         email:
           type: string
+        templateId:
+          type: string
         topics:
           type: array
           items:
             type: string
         firstName:
           type: string
+        fields:
+          type: object
+          additionalProperties: true
+        appId:
+          type: string
       required:
         - email
+        - templateId
     CommsSignupResponse:
       type: object
       properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.50",
+  "version": "2.0.51",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",