@receiz/sdk 93.1.0 → 94.0.0

package/docs/proof-memory-and-projections.md

@@ -0,0 +1,127 @@
+# Proof Memory And Projections
+
+The Receiz SDK gives developer apps the same default shape Receiz uses internally:
+
+```txt
+verify proof object -> project immediately -> admit into durable proof memory -> append verified additions
+```
+
+The SDK is convenience. It is not authority. The authority remains the sealed artifact, proof bundle, verified append, ownership append, and settlement ledger record.
+
+## Install
+
+```bash
+npm install @receiz/sdk
+```
+
+## Project A Proof Object
+
+```ts
+import { projectReceizAssetManifest } from "@receiz/sdk";
+
+const projection = projectReceizAssetManifest(manifest);
+
+render({
+  title: projection.title,
+  subtitle: projection.subtitle,
+  mediaUrl: projection.mediaUrl,
+  verifyUrl: projection.verifyUrl,
+  rows: projection.rows,
+});
+```
+
+Projection is deterministic display preparation. It does not verify the artifact by itself. Verify first when the manifest comes from an untrusted transport.
+
+## Project A Sports Card
+
+```ts
+import { projectReceizSportsCardManifest } from "@receiz/sdk";
+
+const projection = projectReceizSportsCardManifest(cardManifest);
+
+renderSportsCard({
+  player: projection.title,
+  value: projection.valueLabel,
+  score: projection.scoreLabel,
+  proofRows: projection.rows,
+});
+```
+
+The projection keeps card identity, claim hash, ownership, value basis, append summary, and event proof summary together. Do not split those into unrelated app models.
+
+## Admit Once, Append Forever
+
+```ts
+import { createReceizProofRegister } from "@receiz/sdk";
+
+const memory = createReceizProofRegister({ ownerId: currentUserId });
+
+memory.admitAssetManifest(assetManifest);
+memory.admitSportsCardManifest(cardManifest);
+memory.admitWebhookEvent(webhookEvent);
+
+const snapshot = memory.snapshot();
+```
+
+Persist `snapshot` in your app storage. On next open, reconstruct memory from `snapshot.entries` and render it immediately:
+
+```ts
+const memory = createReceizProofRegister(savedSnapshot);
+const knownTruth = memory.entries();
+```
+
+Then ask Receiz for verified additions after your known head. Do not ask whether known proof is still true.
+
+## Receiz Account Restore Boundary
+
+Receiz Key, Identity Record, and Identity Seal restore use the same law inside Receiz itself. Current restore artifacts carry `receiz.account.state.v3`, which includes profile/account state, action ledger, calendar events, wallet settlement rows and notes, Sports vault cards, pack purchases, card appends, event proofs, entries, competitions, and tournament state.
+
+That private identity artifact is stronger than a later API response. Restore projects the carried account proof memory first; server/database sync may only mirror missing rows or append verified additions the artifact does not possess. It must not rediscover old truth before use.
+
+Developer apps should apply the same pattern with SDK proof memory: store admitted proof objects locally, paint from that known prefix immediately, then request additions after the known head. The SDK does not mint private Receiz login images or keys; it gives external apps the same admit-once, append-forever operating model.
+
+## Duplicate Transport Is Safe
+
+If the same proof object arrives again through another transport, the register keeps the first admitted payload and only fills missing fields. This prevents a weaker partial response from dropping known truth.
+
+```ts
+memory.admitAssetManifest(fullManifest);
+memory.admitAssetManifest(partialManifest);
+
+const retained = memory.snapshot().entries[0];
+```
+
+This is intentional. Receiz proof memory is not `newest response wins`.
+
+## Runtime Schema Exports
+
+```ts
+import { RECEIZ_SCHEMAS } from "@receiz/sdk";
+
+const assetManifestSchema = RECEIZ_SCHEMAS.assetManifest;
+const sportsCardSchema = RECEIZ_SCHEMAS.sportsCardManifest;
+const webhookEventSchema = RECEIZ_SCHEMAS.webhookEvent;
+```
+
+The schemas are packaged for docs, validation UIs, generated forms, test fixtures, and developer tooling. Runtime validators remain available as:
+
+```ts
+import {
+  assertReceizAssetManifest,
+  assertReceizSportsCardManifest,
+  assertReceizWebhookEvent,
+} from "@receiz/sdk";
+```
+
+## Production Rule
+
+Use this order in every integration:
+
+1. Verify stronger proof truth when bytes come from an untrusted transport.
+2. Validate the manifest or event shape.
+3. Project display-ready rows from the verified object.
+4. Admit the object into proof memory.
+5. Persist the proof memory snapshot.
+6. Append later verified additions without rediscovering known truth.
+
+This gives users truthful first paint and gives developers a simple integration that stays aligned with Receiz primitives.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@receiz/sdk",
-  "version": "93.1.0",
+  "version": "94.0.0",
   "description": "TypeScript SDK for Receiz proof-native artifact, public proof, wallet, sports, and Connect integrations.",
   "type": "module",
   "main": "dist/index.js",