@elevasis/sdk 1.44.2 → 1.45.0

package/reference/examples/organization-model.ts

@@ -4,7 +4,13 @@
 // Pure reference file -- NOT imported anywhere.
 // Copy individual examples into core/config/organization-model.ts or resource definitions as needed.
 
-import { defineOrganizationModel, defineResources } from '@elevasis/core/organization-model'
+import {
+  defineOrganizationModel,
+  defineResources,
+  defineTopology,
+  topologyRef,
+  topologyRelationship
+} from '@elevasis/core/organization-model'
 
 // ---------------------------------------------------------------------------
 // Identity and branding override
@@ -206,36 +212,36 @@ export const identityExample = defineOrganizationModel({
 // Customers and offerings
 // ---------------------------------------------------------------------------
 export const customersAndOfferingsExample = defineOrganizationModel({
+  // Both domains are id-keyed records, not arrays. The map key must equal the entry's `id`,
+  // and `order` is required on every entry.
   customers: {
-    segments: [
-      {
-        id: 'segment-smb-agencies',
-        name: 'SMB Marketing Agencies',
-        description: 'Growth-oriented digital agencies with 5-50 staff.',
-        jobsToBeDone: 'Run more client campaigns without growing headcount.',
-        pains: ['Manual data entry', 'Slow lead qualification'],
-        gains: ['Automated pipelines', 'Structured human review'],
-        firmographics: {
-          industry: 'Marketing / Digital Agency',
-          companySize: '5-50',
-          region: 'North America'
-        },
-        valueProp: 'Automate agency operations so the team focuses on strategy and clients.'
-      }
-    ]
+    'segment-smb-agencies': {
+      id: 'segment-smb-agencies',
+      order: 10,
+      name: 'SMB Marketing Agencies',
+      description: 'Growth-oriented digital agencies with 5-50 staff.',
+      jobsToBeDone: 'Run more client campaigns without growing headcount.',
+      pains: ['Manual data entry', 'Slow lead qualification'],
+      gains: ['Automated pipelines', 'Structured human review'],
+      firmographics: {
+        industry: 'Marketing / Digital Agency',
+        companySize: '5-50',
+        region: 'North America'
+      },
+      valueProp: 'Automate agency operations so the team focuses on strategy and clients.'
+    }
   },
   offerings: {
-    products: [
-      {
-        id: 'product-starter',
-        name: 'Starter Automation Pack',
-        description: 'Workflow bundle for lead enrichment, CRM follow-up, and project delivery automation.',
-        pricingModel: 'subscription',
-        price: 299,
-        currency: 'USD',
-        targetSegmentIds: ['segment-smb-agencies']
-      }
-    ]
+    'product-starter': {
+      id: 'product-starter',
+      order: 10,
+      name: 'Starter Automation Pack',
+      description: 'Workflow bundle for lead enrichment, CRM follow-up, and project delivery automation.',
+      pricingModel: 'subscription',
+      price: 299,
+      currency: 'USD',
+      targetSegmentIds: ['segment-smb-agencies']
+    }
   }
 })
 
@@ -245,6 +251,7 @@ export const customersAndOfferingsExample = defineOrganizationModel({
 export const workflowResourceDescriptorsExample = defineResources({
   leadEnrichment: {
     id: 'lead-enrichment-workflow',
+    order: 10,
     title: 'Lead Enrichment',
     description: 'Enriches lead records and writes qualified opportunities into CRM.',
     kind: 'workflow',
@@ -286,67 +293,66 @@ export const compatibilityGraphLinksExample = {
   ]
 }
 
+// `topology.relationships` is an id-keyed record, and each relationship uses `from`/`to`.
+// Author it through `defineTopology` so the refs are compiled and validated for you.
 export const topologyRelationshipsExample = defineOrganizationModel({
-  topology: {
-    relationships: [
-      {
-        source: { kind: 'trigger', id: 'daily-lead-enrichment' },
-        target: { kind: 'resource', id: workflowResourceDescriptorsExample.leadEnrichment.id },
-        kind: 'triggers'
-      },
-      {
-        source: { kind: 'resource', id: workflowResourceDescriptorsExample.leadEnrichment.id },
-        target: { kind: 'externalResource', id: 'apollo' },
-        kind: 'uses'
-      },
-      {
-        source: { kind: 'resource', id: workflowResourceDescriptorsExample.leadEnrichment.id },
-        target: { kind: 'role', id: 'role-ops-lead' },
-        kind: 'approval'
-      }
-    ]
-  }
+  topology: defineTopology({
+    dailyEnrichmentTrigger: topologyRelationship.triggers(
+      topologyRef.trigger('daily-lead-enrichment'),
+      topologyRef.resource(workflowResourceDescriptorsExample.leadEnrichment.id)
+    ),
+    enrichmentUsesApollo: topologyRelationship.uses(
+      topologyRef.resource(workflowResourceDescriptorsExample.leadEnrichment.id),
+      topologyRef.externalResource('apollo')
+    ),
+    enrichmentApprovedByOpsLead: topologyRelationship.approval(
+      topologyRef.resource(workflowResourceDescriptorsExample.leadEnrichment.id),
+      topologyRef.role('role-ops-lead')
+    )
+  })
 })
 
 // ---------------------------------------------------------------------------
 // Roles and goals
 // ---------------------------------------------------------------------------
 export const rolesAndGoalsExample = defineOrganizationModel({
+  // Both domains are id-keyed records with a required `order`.
+  // `heldBy` is a discriminated union on `kind`, not a display name.
   roles: {
-    roles: [
-      {
-        id: 'role-ceo',
-        title: 'CEO',
-        responsibilities: ['Set company direction', 'Approve strategic initiatives'],
-        heldBy: 'Alex Johnson'
-      },
-      {
-        id: 'role-head-of-ops',
-        title: 'Head of Operations',
-        responsibilities: ['Manage workflow deployments', 'Review human-in-the-loop queue'],
-        reportsToId: 'role-ceo',
-        heldBy: 'Jordan Lee'
-      }
-    ]
+    'role-ceo': {
+      id: 'role-ceo',
+      order: 10,
+      title: 'CEO',
+      responsibilities: ['Set company direction', 'Approve strategic initiatives'],
+      heldBy: { kind: 'human', userId: 'user-alex-johnson' }
+    },
+    'role-head-of-ops': {
+      id: 'role-head-of-ops',
+      order: 20,
+      title: 'Head of Operations',
+      responsibilities: ['Manage workflow deployments', 'Review human-in-the-loop queue'],
+      reportsToId: 'role-ceo',
+      heldBy: { kind: 'human', userId: 'user-jordan-lee' }
+    }
   },
   goals: {
-    objectives: [
-      {
-        id: 'goal-grow-arr-q2-2026',
-        description: 'Grow monthly recurring revenue by end of Q2 2026.',
-        periodStart: '2026-04-01',
-        periodEnd: '2026-06-30',
-        keyResults: [
-          {
-            id: 'kr-mrr-10k',
-            description: 'Reach $10K MRR',
-            targetMetric: 'Monthly recurring revenue',
-            currentValue: 2800,
-            targetValue: 10000
-          }
-        ]
-      }
-    ]
+    'goal-grow-arr-q2-2026': {
+      id: 'goal-grow-arr-q2-2026',
+      order: 10,
+      description: 'Grow monthly recurring revenue by end of Q2 2026.',
+      periodStart: '2026-04-01',
+      periodEnd: '2026-06-30',
+      // `keyResults` genuinely is an array — it is nested inside the entry, not a domain map.
+      keyResults: [
+        {
+          id: 'kr-mrr-10k',
+          description: 'Reach $10K MRR',
+          targetMetric: 'Monthly recurring revenue',
+          currentValue: 2800,
+          targetValue: 10000
+        }
+      ]
+    }
   }
 })
 
@@ -354,38 +360,38 @@ export const rolesAndGoalsExample = defineOrganizationModel({
 // Knowledge nodes
 // ---------------------------------------------------------------------------
 export const knowledgeExample = defineOrganizationModel({
+  // `knowledge` is a flat id-keyed record. The old `{ version, lastModified, nodes[] }`
+  // wrapper was removed in the Phase 4 cut.
   knowledge: {
-    nodes: [
-      {
-        id: 'knowledge.example-outreach-playbook',
-        kind: 'playbook',
-        title: 'Example Outreach Playbook',
-        summary: 'Step-by-step runbook for launching a cold outreach campaign.',
-        body: '## Overview\n\nThis playbook walks through prospect sourcing, message templates, scheduling, and reply triage.\n\n## Steps\n\n1. Source prospects from the lead-gen list.\n2. Personalize the cold email template.\n3. Schedule the sending campaign.\n4. Triage replies in the CRM.',
-        links: [{ nodeId: 'system:sales.crm' }, { nodeId: 'system:sales.lead-gen' }],
-        ownerIds: [],
-        updatedAt: '2026-05-01'
-      },
-      {
-        id: 'knowledge.example-icp-strategy',
-        kind: 'strategy',
-        title: 'Example ICP Strategy',
-        summary: 'Describes the ideal customer profile and qualification thresholds.',
-        body: '## ICP Profile\n\n- **Industry:** SMB marketing agencies\n- **Size:** 5-50 employees\n- **Region:** North America\n\nProspects scoring \\<60 are excluded from outreach.',
-        links: [{ nodeId: 'system:sales' }],
-        ownerIds: [],
-        updatedAt: '2026-05-01'
-      },
-      {
-        id: 'knowledge.example-org-model-reference',
-        kind: 'reference',
-        title: 'Example Organization Model Reference',
-        summary: 'Glossary of OM domains and how they relate to systems and resources.',
-        body: '## Domains\n\nThe organization model separates semantic contracts in ontology, system-local settings in config, executable governance in resources, and explanatory material in knowledge. Secrets and runtime state stay outside the Organization Model.',
-        links: [],
-        ownerIds: [],
-        updatedAt: '2026-05-01'
-      }
-    ]
+    'knowledge.example-outreach-playbook': {
+      id: 'knowledge.example-outreach-playbook',
+      kind: 'playbook',
+      title: 'Example Outreach Playbook',
+      summary: 'Step-by-step runbook for launching a cold outreach campaign.',
+      body: '## Overview\n\nThis playbook walks through prospect sourcing, message templates, scheduling, and reply triage.\n\n## Steps\n\n1. Source prospects from the lead-gen list.\n2. Personalize the cold email template.\n3. Schedule the sending campaign.\n4. Triage replies in the CRM.',
+      links: [{ nodeId: 'system:sales.crm' }, { nodeId: 'system:sales.lead-gen' }],
+      ownerIds: [],
+      updatedAt: '2026-05-01'
+    },
+    'knowledge.example-icp-strategy': {
+      id: 'knowledge.example-icp-strategy',
+      kind: 'strategy',
+      title: 'Example ICP Strategy',
+      summary: 'Describes the ideal customer profile and qualification thresholds.',
+      body: '## ICP Profile\n\n- **Industry:** SMB marketing agencies\n- **Size:** 5-50 employees\n- **Region:** North America\n\nProspects scoring \\<60 are excluded from outreach.',
+      links: [{ nodeId: 'system:sales' }],
+      ownerIds: [],
+      updatedAt: '2026-05-01'
+    },
+    'knowledge.example-org-model-reference': {
+      id: 'knowledge.example-org-model-reference',
+      kind: 'reference',
+      title: 'Example Organization Model Reference',
+      summary: 'Glossary of OM domains and how they relate to systems and resources.',
+      body: '## Domains\n\nThe organization model separates semantic contracts in ontology, system-local settings in config, executable governance in resources, and explanatory material in knowledge. Secrets and runtime state stay outside the Organization Model.',
+      links: [],
+      ownerIds: [],
+      updatedAt: '2026-05-01'
+    }
   }
 })

package/reference/index.mdx

@@ -31,7 +31,7 @@ You do not need all three packages. A pure automation project needs only `@eleva
 
 ## Packages
 
-### @elevasis/sdk (v1.30.2)
+### @elevasis/sdk (v1.45.0)
 
 The primary developer package. Provides the TypeScript API for defining workflows and agents, the `elevasis-sdk` CLI for validation and deployment, and typed worker adapters for 25 platform and integration tools.
 
@@ -41,7 +41,7 @@ The primary developer package. Provides the TypeScript API for defining workflow
 
 See [@elevasis/sdk](sdk/index.mdx) for the full group overview, getting started guide, CLI reference, adapter catalog, and more.
 
-### @elevasis/core (v0.39.0)
+### @elevasis/core (v0.60.0)
 
 The shared contract layer. Exports Zod schemas and TypeScript types that are shared between the SDK, the UI, and the platform API. Useful when you need the typed contracts (organization model, entities, knowledge, auth) in a package that does not pull in the full SDK runtime.
 
@@ -51,9 +51,9 @@ The shared contract layer. Exports Zod schemas and TypeScript types that are sha
 
 See [@elevasis/core](core/index.mdx) for subpath details, browser/server split, and when to use it.
 
-### @elevasis/ui (v2.42.0)
+### @elevasis/ui (v2.68.0)
 
-The shared React feature-shell. Provides an `ElevasisProvider` and manifest-backed feature modules that a host UI embeds. Many peer dependencies are optional -- pull only what the features you use require.
+The shared React feature-shell. Provides `ElevasisCoreProvider` / `ElevasisSystemsProvider` and manifest-backed feature modules that a host UI embeds. Many peer dependencies are optional -- pull only what the features you use require.
 
 **Install:** `pnpm add @elevasis/ui`
 

package/reference/rules/active-change-index.md

@@ -1,5 +1,5 @@
 ---
-description: Bridge between stable scaffold docs and higher-volatility in-progress architecture work that may override assumptions for agents working in the template
+description: Which bundled references to load for platform areas under active change, and how to resolve drift between the bundled snapshot and live platform behavior
 ---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
@@ -7,77 +7,63 @@ description: Bridge between stable scaffold docs and higher-volatility in-progre
 
 # Active Change Index
 
-Use this rule to decide whether stable scaffold docs are enough, or whether you also need to load in-progress platform architecture docs from the monorepo.
+The reference bundle at `operations/node_modules/@elevasis/sdk/reference/` is a snapshot pinned to your installed `@elevasis/sdk` version. It does not move when the platform does. For the areas below -- the ones under active change -- read the bundled doc as the best written source, but let observed platform behavior and project source win when they disagree, and flag the drift instead of silently trusting prose.
 
-> **Note:** Paths prefixed with `apps/` or `packages/` are monorepo-internal and unavailable in standalone projects. For those areas, use the stable scaffold docs under `operations/node_modules/@elevasis/sdk/reference/scaffold/` as the primary reference. The monorepo paths are retained for contributors working within the monorepo.
+Only two locations are readable from this project: your own tree (`ui/`, `core/`, `operations/`) and the installed bundle above. Paths quoted in older docs that begin with a monorepo-internal prefix (`packages`, `apps`, `scripts`) will not resolve here.
 
-## Current Watch Areas
+## Watch Areas
 
-### Organization OS
+### Organization Model, Systems, and UI Composition
 
-Use when the task touches:
+Load when the task touches org-model semantics, System readiness, feature or provider runtime, feature manifests, shell composition, or graph and command-view concepts:
 
-- organization model semantics
-- feature/provider runtime
-- feature manifests or shell composition
-- graph or command-view concepts
-- downstream propagation of scaffold contract changes
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/core/organization-model.mdx` -- org-model semantics
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/core/organization-graph.mdx` -- graph and command-view concepts
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-shell.mdx` -- shell composition
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/composition-extensibility.mdx` -- extension points
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md` -- System API surface and derived readiness
 
-Load:
+Do not assume right now:
 
-- `apps/docs/content/docs/technical/architecture/core/organization-model/index.mdx`
-- `apps/docs/content/docs/technical/architecture/core/organization-model/graph.mdx`
-- `apps/docs/content/docs/technical/architecture/ui/feature-shell.mdx`
-- `apps/docs/content/docs/technical/architecture/ui/composition-extensibility.mdx`
+- That a System declares its API surface through a contract object. The marker is the flat `system.apiInterface`, and readiness is derived from it. `SystemContract`, `BridgeContract`, `System.contracts`, `bridgeContracts`, versioned `*@v1` IDs, and a generic `system.interfaces` map are retired -- never reintroduce them, and never add aliases or compatibility shims for them.
+- That a System without `apiInterface` is broken. Omitting it is the designed opt-out for a System this project does not expose.
 
-Stable scaffold docs affected:
+### Published Package Surfaces
 
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
-- `.claude/rules/ui.md`
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md`
+Load when the task touches the published `@elevasis/core`, `@elevasis/ui`, or `@elevasis/sdk` surfaces, or when scaffold prose disagrees with what your installed packages export:
 
-### Package Surface / Reference System
+- `operations/node_modules/@elevasis/sdk/reference/packages/core/src/organization-model/README.md` -- core org-model source notes
+- `operations/node_modules/@elevasis/sdk/reference/packages/ui/src/provider/README.md` -- provider runtime
+- `operations/node_modules/@elevasis/sdk/reference/packages/ui/src/features/README.md` -- feature manifests
+- `operations/node_modules/@elevasis/sdk/reference/_navigation.md` -- index of everything in the bundle
 
-Use when the task touches:
+Do not assume right now that a symbol named in prose still exports. Check `operations/node_modules/@elevasis/sdk/reference/core/exports.mdx` and `operations/node_modules/@elevasis/sdk/reference/ui/exports.mdx`, or the installed type declarations, before writing against a name you only read in a doc.
 
-- published `@elevasis/core`, `@elevasis/ui`, or `@elevasis/sdk` surfaces
-- generated package maps
-- contract drift between source and scaffold docs
+### Resource Registration and Topology
 
-Load:
+Load when the task touches resource registration, triggers, integrations, relationships, or human checkpoints:
 
-- `packages/core/src/organization-model/README.md`
-- `packages/ui/src/provider/README.md`
-- `packages/ui/src/features/README.md`
-- `packages/sdk/reference/_navigation.md`
+- `operations/src/index.ts` -- the registry itself; authoritative over any doc
+- `operations/src/README.md` -- what this project registers
+- `operations/node_modules/@elevasis/sdk/reference/rules/operations.md` -- stable authoring conventions
 
-Stable scaffold docs affected:
+Do not assume right now that a resource ID quoted in a doc matches the deployed one. Confirm against `operations/src/index.ts`.
 
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
-
-### Resource / Topology Mapping
-
-Use when the task touches:
-
-- resource registration
-- triggers, integrations, relationships, human checkpoints
-- topology-aware navigation or impact analysis
-
-Load:
-
-- `operations/src/README.md`
-- `operations/src/index.ts`
+## Working Rule
 
-Stable scaffold docs affected:
+1. Read the stable rule or scaffold doc first.
+2. Read the project-owned source in `operations/src/` or `core/config/` -- source beats prose.
+3. On disagreement, follow the source and report the drift rather than editing around it.
 
-- `.claude/rules/operations.md`
+## Related Rules
 
-## Working Rule
+- `operations/node_modules/@elevasis/sdk/reference/rules/organization-model.md` -- org-model authoring and System declarations
+- `operations/node_modules/@elevasis/sdk/reference/rules/ui.md` -- access model, guards, shared UI surfaces
+- `operations/node_modules/@elevasis/sdk/reference/rules/operations.md` -- resource registration conventions
+- `operations/node_modules/@elevasis/sdk/reference/rules/package-taxonomy.md` -- which package families are importable here
 
-When a task touches one of the watch areas above:
+## References
 
-1. Read the stable scaffold doc.
-2. Read the listed in-progress or package-local source-of-truth docs.
-3. Prefer source and in-progress architecture docs if they disagree with scaffold prose.
-4. Flag drift instead of silently trusting the scaffold doc.
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx` -- stable scaffold reference root
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- contract surface between project and platform
+- `operations/node_modules/@elevasis/sdk/reference/_navigation.md` -- full bundle index

package/reference/rules/agent-runtime.md

@@ -0,0 +1,81 @@
+---
+description: Agent runtime behavior -- iteration response shape, session memory and replay, prose normalization, and why a redeploy is what makes a platform fix live
+paths:
+  - operations/**
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Agent Runtime
+
+What the platform does to an agent's input and output at run time. None of it is configured in an agent definition -- it lives in the runtime your deployed bundle carries, which is why **a redeploy is what makes any of it change**.
+
+## The Redeploy Rule (read this first)
+
+The agent loop is inlined into the bundle `elevasis-sdk deploy` produces. A platform-side fix does not reach a deployed agent, and neither does a `pnpm install` in `operations/` on its own. The sequence is always: take the `@elevasis/sdk` baseline bump, reinstall, then redeploy. Until the redeploy, your agents keep running the loop they were built with.
+
+Verify against the installed bundle, never the version number -- a bumped pin in `package.json` is a claim, `operations/node_modules/@elevasis/sdk/` is ground truth.
+
+## Iteration Response Shape
+
+An agent iteration returns three top-level fields, **in this declaration order**:
+
+| Field         | Purpose                                                        |
+| ------------- | -------------------------------------------------------------- |
+| `nextActions` | what the agent does next                                       |
+| `message`     | the reply the user sees -- the only field rendered to the user |
+| `reasoning`   | the agent's own account of the turn                            |
+
+The order is load-bearing, not cosmetic. Under grammar-constrained sampling the model fills keys in declaration order, so the actions and the reply are committed to the wire before any mid-response drift can begin. `reasoning` stays last for that reason, which also means it reads as a summary of the answer rather than a lead-up to it -- if you parse or display it, expect that shape.
+
+**`message` is required for session-capable agents.** When it shipped as optional the model skipped it entirely and those turns produced no user-facing reply at all: `nextActions` is chosen before the model has reasoned about the answer, `complete` is the cheapest legal action, and a skippable field then gets skipped. Requiring it costs nothing -- an empty or whitespace-only value is suppressed and renders no message bubble.
+
+**`message` is a flat top-level field, not an entry in the actions array.** It used to be one variant of an `anyOf` union nested inside `nextActions`, and text in that position was silently corrupted: the model would emit a JSON escape for an em-dash and complete it with the next letter of the sentence, so `Hold on — red-line for me` arrived as `Hold on \red-line for me`. That parses, satisfies the schema, and passes validation -- there is no error state to catch it. Flattening the field fixed it. Do not reintroduce a nested reply.
+
+## Structured Output Is Enforced
+
+Iteration calls go out with `strict: true`, which compiles the response schema into a sampling grammar. Without it the schema is guidance and required fields are best-effort.
+
+Strict mode accepts only a subset of JSON Schema, and a schema outside that subset makes the platform fall back to the unenforced path **silently**. The observable signal is `strictRefusalReasons` on the call's `ai_calls` observability row: **absence of that field is the healthy state.** If you see a value there -- `["freeFormObject"]`, say -- that agent is running a bundle whose schema the grammar could not compile.
+
+Memory writes are declared as a list of `{ key, value }` pairs for exactly this reason; a free-form map (`additionalProperties: true`) has no strict equivalent.
+
+## Sessions and Replay
+
+For an agent with `sessionCapable: true`, turn N is handed the agent's restored memory plus the earlier user and assistant messages, token-budgeted. Both are on by default and need no agent definition change.
+
+Two consequences worth holding when you write `memoryPreferences`:
+
+- **The conversation genuinely is available to the model.** Guidance of the form _"do not store the transcript in memory -- the transcript is the source of truth"_ is now correct. It was not always: the messages were stored for display but never read by the execution path, so an agent following that instruction remembered nothing.
+- **Stored memory is re-sent on every iteration of every later turn and never ages out.** One bad value there is one the model re-reads for the life of the session. Memory is the highest-leverage surface in a long conversation, and the one least visible in a smoke test.
+
+Session defects scale with accumulated context. A single turn is not a test -- run a long enough conversation for the failure class to appear, and probe recall with an unguessable token planted in turn 1 and asked for verbatim in turn 2.
+
+## Prose Normalization
+
+Model output is repaired deterministically at the single point where it is validated -- upstream of persist, stream, render, and replay. `\n`, `\r\n`, `\t`, and `\"` are converted to the characters they denote, in `message`, in `reasoning`, and in session-memory values, on **every** agent rather than only session-capable ones.
+
+This exists because the model chooses the wrong characters, not the wrong encoding: a single reply has been observed carrying one paragraph break as real newlines and another as the two characters `\n`, inside the same string. No serialization layer produces that, so there was nothing to wait for upstream.
+
+Two behaviors to know:
+
+1. **The normalizer is not markdown-aware.** A literal `\n` inside a fenced code block or an inline span **is** converted. This was a deliberate trade -- a reply whose line breaks are all literal has no line structure for a fence to start on, so the replies most in need of repair are exactly the ones a fence scan cannot parse. If your agent discusses escape sequences or regexes in its user-facing prose, this is the case to check.
+2. **A doubled backslash is left alone, and JSON-shaped memory values are skipped entirely**, so a stored JSON blob keeps its internal escaping and still parses.
+
+No backfill is performed. Replies and memory snapshots written before your redeploy keep whatever literal escapes they already have -- do not treat old transcripts as clean.
+
+## Related Rules
+
+Sibling rule bodies live at `operations/node_modules/@elevasis/sdk/reference/rules/`.
+
+- **platform.md** -- authoring the agent definition this runtime executes
+- **execution.md** -- worker lifecycle, timeouts, and the constraints an agent turn runs inside
+- **observability.md** -- reading the execution and `ai_calls` rows the signals above appear on
+- **deployment.md** -- the deploy that makes a runtime change live, and which environment it targets
+
+## References
+
+- `operations/node_modules/@elevasis/sdk/reference/sdk/runtime.mdx` -- worker runtime model in full
+- `operations/node_modules/@elevasis/sdk/reference/sdk/resources/index.mdx` -- agent resource shape, `sessionCapable`, and `memoryPreferences`
+- `operations/node_modules/@elevasis/sdk/reference/sdk/deployment/execution-reference.mdx` -- execution, step, and iteration record shapes