@elevasis/sdk 1.44.3 → 1.46.0

package/reference/packages/core/src/organization-model/readiness/README.md

@@ -0,0 +1,42 @@
+# System Interface Readiness
+
+The readiness engine answers one question: is a given System's declared interface actually usable, or is something in the tenant's organization model missing or malformed? `computeInterfaceReadiness` produces a structured result rather than a boolean, so a caller can report which family of issue blocked the interface instead of failing opaquely.
+
+Use this module when gating an API surface on a System's adoption state, or when registering a readiness profile that carries real structural validation logic.
+
+## Two registration functions, and only one of them validates
+
+This is the distinction that most often gets it wrong, so it is worth stating plainly:
+
+- **`registerBuiltInReadinessProfile`** (this module) registers a profile **with a validator**. It is the extension point that makes `isBuiltInReadinessProfile` return true.
+- **`registerReadinessProfile`** (in `../domains/systems`) only acknowledges a custom profile id. It registers no validator, writes `kind: 'custom'`, and can **never** make a profile resolve as built-in.
+
+Calling the second one and expecting the first one's effect is a silent no-op — declaring a readiness contract on the System remains mandatory. Only `registerBuiltInReadinessProfile` changes what validation runs.
+
+## Published Exports
+
+```ts
+import {
+  computeInterfaceReadiness,
+  registerBuiltInReadinessProfile,
+  getBuiltInReadinessProfile,
+  registerReadinessInterfaceMarker,
+  resolveReadinessInterfaceMarker,
+  SystemInterfaceReadinessError,
+  type SystemInterfaceReadinessIssue,
+  type SystemInterfaceReadinessIssueFamily,
+  type SystemInterfaceReadinessRequest,
+  type SystemInterfaceReadinessResult,
+  type ReadinessProfileRegistration,
+  type ReadinessProfileValidator,
+  type ReadinessOntologyIndex,
+  type ReadinessInterfaceMarkerResolver,
+  type SystemInterfaceMarker
+} from '@elevasis/core/organization-model/readiness'
+```
+
+This subpath exists so the extension point can be reached without pulling in the rest of `@elevasis/core`. It points at the same module workspace consumers import, deliberately — the two surfaces cannot drift apart.
+
+## Layering constraint
+
+Nothing under `readiness/` may import from `business/**`. The engine is generic; the lead-gen and CRM profile validators are registered **into** it by `business/acquisition` at module load, never the other way around. Adding a `business/` import here inverts the dependency the extraction exists to enforce.

package/reference/packages/ui/src/features/README.md

@@ -1,28 +1,28 @@
-# Features
-
-Feature subpaths package complete shell-level UI flows for downstream apps.
-
-## Published Feature Surfaces
-
-- `./features/auth`
-- `./features/crm`
-- `./features/dashboard`
-- `./features/delivery`
-- `./features/lead-gen`
-- `./features/operations`
-- `./features/monitoring`
-- `./features/seo`
-- `./features/settings`
-
-## What They Contain
-
-- Route shells and page-level components
-- Sidebars and feature-specific navigation
-- Feature manifests for registry consumers
-- Feature-specific hooks and shared constants
-
-## Notes
-
-- These surfaces are meant for app composition, not for low-level design-system primitives.
-- Some feature exports are also re-exported through `./components` for convenience in legacy or mixed consumers.
-
+# Features
+
+Feature subpaths package complete shell-level UI flows for downstream apps.
+
+## Published Feature Surfaces
+
+- `./features/auth`
+- `./features/content`
+- `./features/crm`
+- `./features/dashboard`
+- `./features/delivery`
+- `./features/lead-gen`
+- `./features/operations`
+- `./features/monitoring`
+- `./features/seo`
+- `./features/settings`
+
+## What They Contain
+
+- Route shells and page-level components
+- Sidebars and feature-specific navigation
+- Feature manifests for registry consumers
+- Feature-specific hooks and shared constants
+
+## Notes
+
+- These surfaces are meant for app composition, not for low-level design-system primitives.
+- Some feature exports are also re-exported through `./components` for convenience in legacy or mixed consumers.

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