@x12i/memorix-docs 1.0.2 → 1.1.0

package/files/use-cases/builder-acceptance-ops.md

@@ -0,0 +1,112 @@
+# Acceptance tour on the ops narrative
+
+> **Use case id:** `builder-acceptance-ops`
+> **Goal:** Walk WI-100 / employees success path in Studio without API deep-dive.
+> **Audiences:** builders
+> **Tags:** acceptance, ops, studio
+
+## Reading path
+
+1. **Platform Overview** (builders) → chapters: `5-a-short-ops-tour-what-success-looks-like`, `9-acceptance-workspace`
+1. **Workflow & Studio** (builders) → chapters: `7-short-ops-tour-acceptance`
+1. **Agent Packs & Ops** (builders) → chapters: `1-what-you-should-see-after-a-good-install`, `2-install-checklist-fresh-g12ops`
+
+## From: Platform Overview — 5. A short ops tour (what success looks like)
+
+Use subjects from the permanent narrative: employee **Alex**, work item **WI-100**, procedure **PROC-2**.
+
+1. **Design** — confirm ops metadata is installed for your `g12ops*` org.
+2. **Operate** — run a Memory pull from ops-source; inspect landing of raw material.
+3. **Operate** — start the relevant pipeline; watch attempts and artifacts.
+4. **Explore** — open `WI-100` (or Alex); confirm composition siblings appear.
+5. **Explore** — traverse relationship links; confirm you see navigation, not pasted neighbor fields.
+6. **Design / Operate** — if intelligence proposed metadata, review and **explicitly** install or reject — never expect auto-install.
+
+---
+
+## From: Platform Overview — 9. Acceptance workspace
+
+Always use a fresh `g12ops*` organization with agent `ops`. Never use live customer orgs for drills. See [_shared/ops-scenario.md](../../_shared/ops-scenario.md).
+
+## From: Workflow & Studio — 7. Short ops tour (acceptance)
+
+Subjects: employee **Alex**, work item **WI-100**, procedure **PROC-2**.
+
+1. **Scope** — fresh `g12ops*` + agent `ops`.
+2. **Design** — confirm ops metadata installed (explicit install if needed).
+3. **Operate** — Memory pull from ops-source; confirm raw landed.
+4. **Operate** — run the documented pipeline; open artifacts if anything fails.
+5. **Explore** — open `WI-100`; confirm composition siblings (snapshot + workflow, …).
+6. **Explore** — edit workflow assignment; save; confirm revision bump.
+7. **Explore** — traverse relationships; confirm expansion, not copied payloads.
+8. Optional: open a KnowX assertion and walk the review siblings (book `12`).
+
+---
+
+## From: Agent Packs & Ops — 1. What you should see after a good install
+
+| Area | Healthy signal |
+|---|---|
+| Design → Agents | `ops` (and documented children) present |
+| Design → Types | employees, work-items, procedures, … |
+| Design → Abstracts | People-style unions bound to concrete types |
+| Design → Relationships | Documented definitions available |
+| Operate → Memory | Pull from ops-source succeeds |
+| Operate → Runs | Pipeline attempts succeed; artifacts readable |
+| Explore | WI-100 composition (snapshot, workflow, …); Alex visible; links expand |
+
+Custom kinds (if your pack declares them): appear under metadata kinds / effective metadata after install. They do **not** by themselves run pipelines.
+
+---
+
+## From: Agent Packs & Ops — 2. Install checklist (fresh `g12ops*`)
+
+Work top to bottom. Do not skip scope.
+
+### A. Workspace
+
+- [ ] Create / select a **fresh** `g12ops*` organization
+- [ ] Scope bar agent = **`ops`** (or the documented agent set)
+- [ ] You are **not** on a live customer org
+- [ ] Service + Studio + ops-source are up (prefer `dev-stack`)
+
+### B. Metadata install
+
+- [ ] Design → metadata install / publish for the **ops** pack
+- [ ] Confirmation step completed (explicit — not a silent side effect)
+- [ ] Effective agents/types refresh in Design
+- [ ] (Optional) If the pack declares custom kinds, confirm they appear under kinds / effective metadata
+
+### C. Memory
+
+- [ ] Operate → Memory pull from **ops-source** (localhost fixture)
+- [ ] Raw material landed for employees / work-items / procedures / activity-events as documented
+- [ ] No raw secrets pasted into forms — credential refs only if prompted
+
+### D. Pipeline
+
+- [ ] Operate → start the documented ops pipeline / schedule
+- [ ] Attempts green (or failures opened with readable artifacts)
+- [ ] Do not “fix” by inventing subjects outside the data plane
+
+### E. Explore verification
+
+- [ ] Open **WI-100** — composition siblings present (snapshot, workflow, …)
+- [ ] Open **Alex** (employee) — snapshot healthy
+- [ ] Traverse a relationship link — expansion shows current targets, not pasted neighbor blobs
+- [ ] Unresolved targets (if any in the scenario) are visible as unresolved — not silently invented
+
+### F. Optional intelligence
+
+- [ ] If you run intelligence proposals, **review then install/reject** — proposals alone must not change types
+- [ ] Prefer shipped ops pack for acceptance demos
+
+---
+
+## Also see
+
+- **Building Pipelines** (`08-pipelines`) — Pipeline definition, step kinds, AI fail-closed, operations, and the complete ops tutorial.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/choose-access-method.md

@@ -0,0 +1,111 @@
+# Choose the right access method
+
+> **Use case id:** `choose-access-method`
+> **Goal:** Map a task to best / acceptable / forbidden calls using the patterns matrix.
+> **Audiences:** developers
+> **Tags:** patterns, http
+
+## Reading path
+
+1. **Data Access Patterns** (developers) → chapters: `2-master-decision-matrix`, `5-exact-read-versus-list`, `25-decision-tree`
+
+## From: Data Access Patterns — 2. Master decision matrix
+
+For every runtime goal: preferred method, acceptable ad-hoc, forbidden method, and the consistency / retry story.
+
+| Goal | Best | Acceptable | Forbidden | Consistency / retry |
+|---|---|---|---|---|
+| Read one known content instance | Service `GET /api/data/content` (exact) | In-process `@x12i/memorix-data` `getContent` | Mongo `findOne` | Current revision; retry transient failures |
+| Find records matching fields | Bounded list/query + opaque cursor | Temporary ad-hoc filter with hard limit | Unbounded `listAll` / decoded cursors | Cursor contract; retry **same** query+cursor |
+| Read all content about one subject | Explicit composition | Two–three independent exact gets | Flatten siblings into the snapshot; invent `associated*` | Current siblings; per-sibling revisions |
+| Read a union such as People | Abstract list / get | Concrete lists + UI label (diagnosis only) | Abstract collection / abstract `recordId` | Metadata-dependent projection |
+| Follow relationships | Relationship query / `expandRelationships` | Bounded investigation queries | Client-side org-wide joins; copied payloads | Current targets; unresolved stays unresolved |
+| Read current related properties | Related-property / expansion APIs | Two bounded queries | Persist expanded targets on the source | Current; may go stale if cached naïvely |
+| Process a small known set | Batch get (if exposed) or bounded list of addresses | Parallel exact gets with concurrency cap | Cartesian fan-out | Per-item |
+| Process a large set | Pipeline + DataRef | Async export for reporting | Interactive mega-list | Captured/ledgered; retry failed items |
+| Import external data | Memory pull → raw | Controlled source test via Memory | Direct snapshot insert from connector | Source cursor; resume committed cursor |
+| Write one content instance | `patch` / `upsert` / `replace` / `remove` + precondition | Operator script through the same API | Blind replace; Mongo update | Exact revision; never blind-retry after stale |
+| Update an abstract property | `patchAbstract` reverse write | Temporary concrete patch when mapping is clear | Writing an “abstract record” | Maps to one concrete revision |
+| Modify many records | Pipeline / batch with per-item revisions | Capture-all-then-write for tiny sets | Client update-many; list-mutate active sort | Partial success ledger |
+| Create relationships | Relationship engine (discover / materialize / rebuild) | Dry-run / verify | Manual link inserts; `associated*` | Idempotent materialization |
+| Inspect execution history | Operations / pipeline / Memory APIs | Studio Operate views | Treating ledgers as subject content | Operational identity |
+| Inspect evidence / expected slots | `/api/data-journey/*` (matrix, coverage, evidence) | Studio Explore evidence UI | Inventing cells; treating journey rows as subject content | Read-only; views = slots only |
+| Export large data | Asynchronous export artifact | Paginated offline consumer with checkpoint | Single-request dump | Export contract |
+| Investigate once | Bounded ad-hoc API query | Studio Explore | Direct Mongo shell | Read-only unless labeled write |
+| Save a repeated query | Metadata-defined view | Temporary client query | Hardcoded DB query in the product | Versioned with metadata |
+| Repeated business process | Pipeline definition | Scheduled Memory + pipeline | UI-embedded “batch engine” | Durable run ledger |
+| Propose new object type | Intelligence proposal → human install | Export draft for review | Intelligence auto-publish / AI writing records | Proposal ≠ live metadata |
+| Secret to connector | `credentialRef` | — | Secret in body / Memory payload | Never log credentials |
+
+---
+
+## From: Data Access Patterns — 5. Exact read versus list
+
+| Situation | Use |
+|---|---|
+| Known `recordId` / content address | Exact get |
+| Unknown `recordId`, known properties | List / query |
+| Several known addresses | Batch get or parallel exact gets (capped) |
+| Same subject, several sibling types | Composition |
+| Abstract union | Abstract list |
+| Different related subjects | Relationship traversal |
+| Large unknown set | Pipeline / export |
+
+**Why not list a known id?** A list walk is more expensive, harder to reason about under concurrency, and invites “first hit wins” bugs. Exact get is O(1) identity.
+
+**Why not guess `recordId` from business fields?** External ids live under `concept.identifiers`. Guessing subject ids from titles or provider keys is unsafe; list/filter by identifier fields or resolve through Memory/mapping metadata instead.
+
+**Ops example:** Host knows `WI-100`’s Memorix `recordId` → exact snapshot get. Host only knows provider work-item key → bounded list/filter on identifier fields, then exact get thereafter.
+
+---
+
+## From: Data Access Patterns — 25. Decision tree
+
+```text
+Do you know the exact content address?
+├─ Yes → exact read / exact revision-safe write
+└─ No  → bounded list/query (then exact thereafter)
+
+Do you need several content types for the same subject?
+├─ Yes → composition
+└─ No  → keep exact content read
+
+Do you need another subject?
+├─ Existing semantic link     → relationship traversal / expansion
+├─ Investigating a possible link → bounded ad-hoc query
+└─ Repeated meaningful join   → relationship metadata + discovery
+
+Is the write one small known instance?
+├─ Yes → revision-safe direct write
+└─ No  → capture addresses → batch/pipeline
+
+Does data come from an external source?
+└─ Memory → raw first → pipeline promote
+
+Is the work large, repeatable, scheduled, or retryable?
+└─ Pipeline (DataRef + ledger)
+
+Is this a one-off investigation?
+└─ Bounded ad-hoc API query — never direct Mongo
+
+Need evidence cone / expected slots for Explore?
+└─ /api/data-journey/* (read-only) — see Runtime Data Client §17
+
+Is this a reusable product screen/query?
+└─ Metadata-defined view (not a hardcoded DB query)
+
+Is this a metadata shape suggestion?
+└─ Intelligence proposal → human install (never auto-publish)
+```
+
+Process debug (`/health`, `/_live`) is not an access pattern for domain data — see [Platform Overview](../../00-platform-overview/developers/BOOK.md). Remote clients do not install `@x12i/core-service` / ports kits.
+---
+
+## Also see
+
+- **Runtime Data Client** (`02-runtime-data-client`) — Connection, scope, exact reads, writes, compose, abstracts, and client anti-patterns through Memorix Service / OpenAPI.
+- **Lists, Queries, Pagination** (`03-lists-queries-pagination`) — List contracts, query grammar, cursors, page size, and multi-resource listing without foot-guns.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/client-first-read-write.md

@@ -0,0 +1,374 @@
+# Product backend first safe read/write
+
+> **Use case id:** `client-first-read-write`
+> **Goal:** Call /api/data correctly with scope, revision preconditions, and explicit compose.
+> **Audiences:** developers
+> **Tags:** http, client, data
+
+## Reading path
+
+1. **Runtime Data Client** (developers) → chapters: `2-connection-and-scope`, `4-exact-content-reads`, `6-explicit-composition`, `9-concrete-writes`, `10-patch-language`
+1. **Data Access Patterns** (developers) → chapters: `2-master-decision-matrix`
+
+## From: Runtime Data Client — 2. Connection and scope
+
+### Canonical client configuration
+
+```ts
+type MemorixClientConfig = {
+  baseUrl: string;       // e.g. http://127.0.0.1:5100
+  orgId: string;         // exactly one — entire org data universe
+  agentIds: string[];    // one or more unique ids — effective metadata only
+};
+```
+
+HTTP form (every `/api/*` call):
+
+```http
+x-memorix-org-id: g12ops<suffix>
+x-memorix-agent-ids: ops
+```
+
+Rules:
+
+1. Exactly **one** `orgId` — selects the organization data universe.
+2. One or more unique **`agentIds`** — selects **effective metadata** only.
+3. Canonical agent ordering is applied by the service; send a stable unique list.
+4. There is **no** singular `agentId` in supported APIs — singular headers are rejected (`400`).
+5. `agentIds` never filter which organization rows you can read; they do not replace authorization.
+6. Deployment authentication (mTLS, gateway tokens, …) is **separate** from Memorix data/metadata scope.
+
+### Where scope is supplied
+
+| Channel | Role |
+|---|---|
+| HTTP headers | Canonical for service callers |
+| SDK client config | Maps to the same headers / scope object |
+| Query / body | Must not invent a *different* scope semantics per route |
+
+There is **one** scope rule for the platform: org selects data universe; agents select effective metadata. Studio’s scope bar sets the same pair.
+
+### Example — configure then probe OpenAPI
+
+```bash
+ORG=g12opsabc123
+AGENTS=ops
+BASE=http://127.0.0.1:5100
+
+curl -sS \
+  -H "x-memorix-org-id: $ORG" \
+  -H "x-memorix-agent-ids: $AGENTS" \
+  "$BASE/api/openapi.json" | head
+```
+
+```ts
+const client = {
+  baseUrl: process.env.MEMORIX_BASE_URL!,
+  orgId: "g12opsabc123",
+  agentIds: ["ops"],
+};
+
+function scopeHeaders(c: typeof client): HeadersInit {
+  return {
+    "x-memorix-org-id": c.orgId,
+    "x-memorix-agent-ids": c.agentIds.join(","),
+  };
+}
+```
+
+### Process debug vs product API
+
+| Surface | Purpose | Client installs kits? |
+|---|---|---|
+| `/api/*` (OpenAPI) | Product contract — data, metadata, Memory, pipelines, … | N/A — call HTTP |
+| `GET /health` | Process liveness (local stack) | **No** — do not install `@x12i/core-service` / ports kits |
+| `GET /_live` | In-process request rings for the bound service | **No** — debug only; not a domain API |
+
+Local URLs and the Memorix zone (**5100–5119**) are oriented in [Platform Overview](../../00-platform-overview/developers/BOOK.md). Authors of **new HTTP processes** (workers Memorix invokes) follow HTTP compliance in [Building Services](../../07-services/developers/BOOK.md). Remote data clients only need `baseUrl` + scope headers.
+
+### Antipatterns
+
+- Omitting agent headers and hoping defaults apply.
+- Sending `agentId` (singular) “because Studio used to.”
+- Using `agentIds` as a substitute for per-record ACL.
+- Pointing a host app at Mongo “just for reads.”
+- Treating `/_live` or `/health` as substitutes for `/api/data` or `/api/data-journey`.
+
+---
+
+## From: Runtime Data Client — 4. Exact content reads
+
+Exact reads retrieve **one** content instance. They do **not** automatically compose siblings or expand relationships.
+
+### Addressing
+
+| Field | When |
+|---|---|
+| `recordId` / `id` | Always for get-by-id |
+| `objectType` | Required for concrete content |
+| `contentType` | Required for concrete content |
+| Discriminator | When the content profile is multi-instance |
+| Projection / view | When the API exposes a view name |
+| Scope | Always |
+
+### What you can retrieve
+
+- Singleton content (e.g. Alex’s employee snapshot)
+- Discriminated content (e.g. `wi-100` analysis `capacity`)
+- Missing content → not-found / unavailable semantics (see errors)
+- Reserved-but-empty subject → identity reserved, content not yet present
+- Raw, snapshot, workflow, context, analysis, decision, discovery — as metadata allows
+
+### Typical response envelope fields
+
+`format`, `recordId`, `revision`, `objectType`, `contentType`, `dataCategory`, optional discriminator, `concept`, `data`, `_system`, plus request/correlation id on the HTTP layer.
+
+### Example — read WI-100 snapshot
+
+```bash
+curl -sS \
+  -H "x-memorix-org-id: $ORG" \
+  -H "x-memorix-agent-ids: $AGENTS" \
+  "$BASE/api/data/content?objectType=work-items&contentType=snapshots&id=wi-100"
+```
+
+```ts
+async function getSnapshot(recordId: string) {
+  const url = new URL("/api/data/content", client.baseUrl);
+  url.searchParams.set("objectType", "work-items");
+  url.searchParams.set("contentType", "snapshots");
+  url.searchParams.set("id", recordId);
+  const res = await fetch(url, { headers: scopeHeaders(client) });
+  if (!res.ok) throw new Error(await res.text());
+  return res.json(); // memorix-record/2
+}
+```
+
+### May / must-not
+
+- **You may** read one instance and later compose if the UI needs siblings.
+- **You must not** assume a get returns related employees “because the work item mentions them.”
+- **You must not** treat absence of a sibling as an error unless your product requires that sibling.
+
+---
+
+## From: Runtime Data Client — 6. Explicit composition
+
+Composition is **requested**. Same `recordId`, multiple content types/instances.
+
+### Shape rules
+
+- Response uses **arrays per content type** (even singleton types appear as arrays in compose).
+- Siblings are **not** flattened into one mega-document.
+- Clients may select which content types to include.
+- Workflow / context / analysis / decisions appear only when selected.
+- Composition carries **no** relationship definitions — neighbors stay relationship APIs.
+
+### Ops examples
+
+| Request | Result idea |
+|---|---|
+| Compose `wi-100` with `snapshots` + `workflow` | One snapshot array entry + workflow array entry |
+| Include two analyses | `analysis: [capacity, delivery-risk]` (names illustrative) |
+| Include three decisions | Arrays under decisions; independent revisions |
+| Optional sibling missing | Empty array or omitted per contract — not a fake null record |
+
+```text
+composeSubject(wi-100)
+  snapshots[]     revision N
+  workflow[]      revision M
+  analysis[]      each own revision
+  decisions[]     each own revision
+```
+
+```bash
+curl -sS -X POST \
+  -H "content-type: application/json" \
+  -H "x-memorix-org-id: $ORG" \
+  -H "x-memorix-agent-ids: $AGENTS" \
+  -d '{"recordId":"wi-100","explicit":true,"contentTypes":["snapshots","workflow","analysis","decisions"]}' \
+  "$BASE/api/data/compose"
+```
+
+OpenAPI operation: `dataCompose`. `explicit: true` is required. Response keeps **arrays per content type**; missing siblings are empty/omitted arrays (plus warnings when the contract exposes them) — not invented singleton objects.
+
+### May / must-not
+
+- **You may** compose for a dossier / Studio Explore-style view.
+- **You must not** invent a single “subject revision” by taking `max(sibling revisions)`.
+- **You must not** flatten arrays into one object keyed only by content type when multiple discriminators exist.
+- **You must not** call compose as `GET` with query params — the service accepts **`POST /api/data/compose`** only.
+
+---
+
+## From: Runtime Data Client — 9. Concrete writes
+
+Supported write operations through the data plane:
+
+| Op | Intent |
+|---|---|
+| `add` | Create only if absent |
+| `upsert` | Create if absent **or** update at exact revision |
+| `patch` | Partial update at exact revision |
+| `replace` | Full content replace at exact revision |
+| `remove` | Delete instance at exact revision |
+
+Every write requires:
+
+- Memorix scope
+- Concrete content address (`objectType`, `contentType`, `recordId`, discriminator if needed)
+- Explicit precondition
+- Immutable envelope fields respected
+
+### Preconditions
+
+```json
+{ "kind": "absent" }
+```
+
+```json
+{ "kind": "revision", "revision": 3 }
+```
+
+| Op | Precondition |
+|---|---|
+| `add` | `absent` |
+| `patch` / `replace` / `remove` | Exact `revision` |
+| `upsert` | `absent` **or** exact `revision` |
+
+Explain:
+
+- Blind overwrite is **forbidden**.
+- Successful create produces **revision 1**.
+- Successful update increments revision **once**.
+- Stale write performs **no mutation** (conflict).
+- Failure atomicity: a rejected write leaves the prior revision unchanged.
+
+### Immutable / ownership reminders
+
+- Do not patch `format`, subject identity, or discriminator in place.
+- Lifecycle and server timestamps follow ownership rules (chapter 13).
+- Directory identity conflicts stop the write — `recordId` already bound to a different object type/category.
+
+### Example — add then patch WI-100
+
+```ts
+// Create snapshot (absent)
+await writeContent({
+  op: "add",
+  objectType: "work-items",
+  contentType: "snapshots",
+  recordId: "wi-100",
+  precondition: { kind: "absent" },
+  record: {
+    format: "memorix-record/2",
+    recordId: "wi-100",
+    objectType: "work-items",
+    contentType: "snapshots",
+    dataCategory: "entity",
+    concept: { title: "Prepare quarterly operations review" },
+    data: { status: "in-progress", priority: "normal" },
+  },
+});
+
+// Later: patch with exact revision from prior read
+await writeContent({
+  op: "patch",
+  objectType: "work-items",
+  contentType: "snapshots",
+  recordId: "wi-100",
+  precondition: { kind: "revision", revision: 1 },
+  patch: [{ op: "set", path: "data.status", value: "blocked" }],
+});
+```
+
+Wire the same intent through `/api/data` per OpenAPI — never via Mongo `updateOne`.
+
+### Retry behavior (preview)
+
+Network unknown after write → re-read before sending another write. Stale revision → reconcile; do not convert to blind upsert. See chapters 19–20.
+
+---
+
+## From: Runtime Data Client — 10. Patch language
+
+Patches are structured operations with path rules — not free-form JSON Merge Patch against the whole envelope unless the contract says so.
+
+### Typical operations
+
+| Op | Use |
+|---|---|
+| `set` | Set a value at an allowed path |
+| `unset` / remove | Clear an allowed path where supported |
+
+### Path rules (client view)
+
+- Prefer paths under `data`, and allowed `concept` / `_system` subsets per contract.
+- Envelope fields (`format`, `recordId`, `objectType`, `contentType`, …) are immutable via patch.
+- Discriminator values are immutable via patch/replace.
+- Lifecycle modifications follow metadata rules — illegal transitions fail.
+- Concept / data / system ownership is contract-defined; do not invent cross-bucket ownership.
+- Conflicting ops in one request fail validation.
+- Invalid or unsafe paths fail before mutation.
+- Validation runs **after** patch application against V2 + profiles.
+
+### Valid vs invalid (illustrative)
+
+**Valid**
+
+- Set `data.priority` on WI-100 snapshot.
+- Unset an optional `data` field allowed by schema.
+- Set `concept.title` when the profile allows title edits.
+
+**Invalid**
+
+- Set `revision` or `format`.
+- Set discriminator in place.
+- Set root `associatedEmployees` or any `associated*`.
+- Patch Mongo `_id`.
+- Invent `/../../` or injection-shaped paths.
+- Conflicting `set` + `unset` on the same path in one request.
+
+### After patch
+
+Re-read if your client needs the server-normalized record (defaults, timestamps, omitted empty buckets). Do not assume the patch document equals the stored document byte-for-byte.
+
+---
+
+## From: Data Access Patterns — 2. Master decision matrix
+
+For every runtime goal: preferred method, acceptable ad-hoc, forbidden method, and the consistency / retry story.
+
+| Goal | Best | Acceptable | Forbidden | Consistency / retry |
+|---|---|---|---|---|
+| Read one known content instance | Service `GET /api/data/content` (exact) | In-process `@x12i/memorix-data` `getContent` | Mongo `findOne` | Current revision; retry transient failures |
+| Find records matching fields | Bounded list/query + opaque cursor | Temporary ad-hoc filter with hard limit | Unbounded `listAll` / decoded cursors | Cursor contract; retry **same** query+cursor |
+| Read all content about one subject | Explicit composition | Two–three independent exact gets | Flatten siblings into the snapshot; invent `associated*` | Current siblings; per-sibling revisions |
+| Read a union such as People | Abstract list / get | Concrete lists + UI label (diagnosis only) | Abstract collection / abstract `recordId` | Metadata-dependent projection |
+| Follow relationships | Relationship query / `expandRelationships` | Bounded investigation queries | Client-side org-wide joins; copied payloads | Current targets; unresolved stays unresolved |
+| Read current related properties | Related-property / expansion APIs | Two bounded queries | Persist expanded targets on the source | Current; may go stale if cached naïvely |
+| Process a small known set | Batch get (if exposed) or bounded list of addresses | Parallel exact gets with concurrency cap | Cartesian fan-out | Per-item |
+| Process a large set | Pipeline + DataRef | Async export for reporting | Interactive mega-list | Captured/ledgered; retry failed items |
+| Import external data | Memory pull → raw | Controlled source test via Memory | Direct snapshot insert from connector | Source cursor; resume committed cursor |
+| Write one content instance | `patch` / `upsert` / `replace` / `remove` + precondition | Operator script through the same API | Blind replace; Mongo update | Exact revision; never blind-retry after stale |
+| Update an abstract property | `patchAbstract` reverse write | Temporary concrete patch when mapping is clear | Writing an “abstract record” | Maps to one concrete revision |
+| Modify many records | Pipeline / batch with per-item revisions | Capture-all-then-write for tiny sets | Client update-many; list-mutate active sort | Partial success ledger |
+| Create relationships | Relationship engine (discover / materialize / rebuild) | Dry-run / verify | Manual link inserts; `associated*` | Idempotent materialization |
+| Inspect execution history | Operations / pipeline / Memory APIs | Studio Operate views | Treating ledgers as subject content | Operational identity |
+| Inspect evidence / expected slots | `/api/data-journey/*` (matrix, coverage, evidence) | Studio Explore evidence UI | Inventing cells; treating journey rows as subject content | Read-only; views = slots only |
+| Export large data | Asynchronous export artifact | Paginated offline consumer with checkpoint | Single-request dump | Export contract |
+| Investigate once | Bounded ad-hoc API query | Studio Explore | Direct Mongo shell | Read-only unless labeled write |
+| Save a repeated query | Metadata-defined view | Temporary client query | Hardcoded DB query in the product | Versioned with metadata |
+| Repeated business process | Pipeline definition | Scheduled Memory + pipeline | UI-embedded “batch engine” | Durable run ledger |
+| Propose new object type | Intelligence proposal → human install | Export draft for review | Intelligence auto-publish / AI writing records | Proposal ≠ live metadata |
+| Secret to connector | `credentialRef` | — | Secret in body / Memory payload | Never log credentials |
+
+---
+
+## Also see
+
+- **Lists, Queries, Pagination** (`03-lists-queries-pagination`) — List contracts, query grammar, cursors, page size, and multi-resource listing without foot-guns.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._