The volumes describe a layered framework with strict naming conventions. Read Orientation first — ten minutes — and every signature in the volumes becomes a location rather than a free-floating function.

Ports and adapters over a strict downward dependency rule. If you have worked in a hexagonal, clean or onion architecture, this is that — the vocabulary is deliberately the conventional one rather than anything invented here.

  runtime      container, configuration, bootstrap, middleware
     │            the ONLY layer that knows which adapter satisfies which port
  surfaces  admin  evaluation      delivery, screens, measurement
     │
  services     TurnService, RetrievalService, IndexingService …
     │            orchestration. Composes domain decisions with the engine
  adapters     PgVectorStoreAdapter, OpenAIResponsesAdapter …
     │            the only place a vendor name may appear
  ports        VectorStorePort, ModelPort, ConnectorPort …
     │            abstract outbound interfaces — the hexagon edge
  domain       Principal, Grant, Scope, Profile, Proposal, Citation
     │            entities and policies. Knows the business, not the wiring
  engine  channel   Assistant, Thread, RunLoop, Tool::Base │ Broadcaster, Marker
     │            the LLM + tool engine, and server-driven UI
  kernel       Identifier, Result, Error, Usage, Text
                  primitives. Depends on nothing

A.1 Which volume describes which layer

Applied without exception, so a class name predicts its role and the layer it lives in. Every signature block in the volumes now names a class and a method rather than a bare function, and carries the source file it corresponds to.

B.1 Method prefixes

Every data-carrying type in the volumes is exactly one of these. If you cannot decide which of the five something is, it is probably two things.

Nothing here is novel. Each piece is a pattern you have used elsewhere, named the way that ecosystem names it.

Nobody should read every section front to back. Five routes through, by what you are trying to decide.

These volumes were originally written with free-function signatures and the word “capability”. Both changed when the framework took shape. If you read an earlier version, this is the map.

What adopting COGNI.BUILD actually looks like, from an empty integration to a product with assistants in six places. Each step is independently useful — nobody has to finish the sequence to get value from it.

Nine components. Five of them an integrator touches directly; four are internals that exist so the other five can stay simple.

  YOUR PRODUCT                 COGNI BUILD                        BACKGROUND
  ────────────                 ───────────                        ──────────

  Surface UI ──request──▶ Entry Point ──┐
  (Client Core)                          │
                                       ├──▶ Profile Registry   instructions,
      ▲                                │                        tools,
      │                                │                        channel identity
      │                                │
      │                                └──▶ Orchestrator ──┬──▶ inline
      │                                                     │
      │                                                     └──▶ queue ──▶ Worker
      │                                                                      │
      │                                       Agent Runtime ◀──────────────┘
      │                                            │
      │                                            ├──▶ Model Gateway ──▶ vendor
      │                                            │
      │                                            └──▶ Tool Registry
      │                                                        │
      │                                                        ├──▶ your tools
      │                                                        └──▶ artifact producers
      │                                                                   │
      └──── delivery channel ◀── Envelope Publisher ◀─────────────────────┘

The one thing to internalise

The response to the originating request is not the answer. It is an acknowledgement. The answer — and every chart, table, document and progress update along the way — arrives later on the delivery channel as a sequence of Envelopes.

Every Surface is built to expect this, including the ones that look synchronous. A machine endpoint that must return a single value still publishes through the same path and simply waits for the terminal Envelope. There is no second code path for "the simple case", because the simple case is the one that later grows tools and starts taking twenty seconds.

The same architecture, delivered two ways. Everything in the request path is shared; the managed service adds the parts a customer would otherwise have to build and operate themselves. Nothing in the managed layer may be required for the core to function.

Eleven terms carry the design. Fixing them before implementation prevents most of the confusion that follows — and every signature in this document is written against them.

Signatures below use conceptual types, not language types. Identifier is whatever your system uses for stable ids. A trailing ? marks an optional argument. -> introduces the result.

A Profile is data describing one Surface. This is the abstraction that decides whether the platform scales to many Surfaces or collapses into a pile of near-identical code paths — so its edges matter more than its size.

Fields

Signatures

How an integrator teaches the assistant to do something in their product. This is the largest surface area of the platform and the one most exposed to getting authorisation wrong, so its contract is deliberately narrow.

The trust rule

Declaring a tool

Producing artifacts

When a tool produces something visual or bulky, it must not return it to the model.

  tool computes a result
     ├──▶ publishArtifact   full fidelity, to the Channel
     ├──▶ storeArtifact     against the Transcript, for reload and export
     └──▶ returns to the model:  a short Reference token + one line of instruction

  model writes prose containing the token
  client replaces the token with the rendered Artifact

Everything that reaches a Surface is a typed message. The set of types is a versioned contract between server and client, declared in exactly one place — because the failure mode when it isn't declared is silence.

The declared vocabulary

The HTTP surface an integrator exposes. Deliberately thin — an entry point authenticates, resolves, hands off and returns. Business logic here is the beginning of a second orchestration path.

One browser-side module, used by every Surface. Its existence is the difference between fixing a chat bug once and fixing it in each place chat appears.

Summarised rather than specified in full — an integrator should not need to reach into these, and a platform that requires it has drawn its boundary in the wrong place.

Orchestrator

Turns a request plus a resolved Profile into a Run. Owns transcript append, execution-mode selection, run identity and usage attribution. Chooses inline or queued through the single shared predicate and records which it chose, so a support question about a slow turn has an answer.

Agent Runtime

The model loop: send the conversation, execute returned tool calls, append results, repeat until the model stops. Bounded by iteration count and wall time. Emits incremental output to an optional consumer without altering the final result. Interruptible from outside its own process.

Model Gateway

Isolates every vendor specific — authentication, request shape, content-part encoding for multimodal input, streaming chunk format, usage accounting. Nothing above this layer names a vendor. Error handling here must be exercised by forcing real vendor failures; a mis-scoped error class silently swallowing every fault is a failure mode this layer is prone to.

Persistence

Optional, and the heaviest thing here. Turn it on when users need artefacts they take away — files that outlive the conversation and get forwarded to people who were never in it. That last property drives every requirement below.

  intent ──▶ PLAN ──▶ (person approves) ──▶ BUILD ──▶ INSPECT ──▶ revise? ──▶ RENDER
                    ▲                                                   │
                    └───────────────────────────────────────────────────┘

Provenance

Two kinds of figure can appear: computed (the system queried it) and transcribed (the model read it from a source). They must not look alike.

Assistant privileges are not one switch, and prompts change far more often than code. Both need to be operable by people who are not deploying.

Grants

Prompt operations

The reference implementation was built for a legal news organisation. Several of its features look domain-specific and are not — they are general shapes wearing newsroom clothes. Each row below names the shape, and where else it earns its keep.

Eight deployments chosen to be as unlike each other as possible. In every one the orchestration, delivery and client are unchanged — only the tool pack, the grants and the artefact templates differ. Where a scenario has a constraint the platform must respect, it is named.

Nine phases. Each is usable on its own, and each surfaces requirements the next depends on — which is why they are ordered rather than parallelised.

Managed-mode phases

The managed service is built after phase 6, never before — it configures things the core must already read. In order: tenancy and isolation, then the configuration console over Profiles and prompts, then connectors, then metering derived from the phase-7 event stream, then operational telemetry.

Sixteen constraints. Each exists because its absence produced a specific defect in the system this is modelled on — none is theoretical.

A tool is the unit of everything the assistant can actually do. Its declaration is read by three audiences that never meet: the model deciding whether to call it, the registry deciding whether it exists, and the operator deciding whether to grant it.

A.1 Anatomy

A.2 Descriptions are behaviour, not prose

The most common tool defect is not a broken handler — it is a description that failed to say something the model needed to know. The model has no other source of truth about how to use the function.

A.3 Result shapes

Four kinds, deliberately distinguished. A tool returns exactly one.

A.4 Signatures

A.5 Composition and re-entrancy

Tools that call other tools' logic are the most common source of authorisation holes, because the registry gate ran once — for the outer one.

A.6 Anti-patterns

The unit of vertical packaging. A pack is a cohesive set of tools over one corpus, shipped, versioned and granted together — the thing that differs between a hospital and a freight desk while everything else stays identical.

Six surface archetypes, and the feature set each one actually needs. The mistake to avoid is building the richest surface first and then trying to strip it down — the archetypes differ in kind, not in degree.

C.1 Archetypes

C.2 Feature matrix

What each archetype needs from the client core. Blank means the feature is not merely optional but actively wrong for that archetype.

C.3 Composer features

C.4 Transcript features

C.5 Surface tool negotiation

A Profile declares which envelope types its surface can render. This is not documentation — it is enforced at publication.

Assistant privileges are not one switch. This section specifies the grant model, how grants compose, what partial authorisation must do, and where gates have to be applied simultaneously to avoid inviting people into walls.

D.1 Grant kinds

D.2 Resolution

  1  authenticate       → Principal, or reject
  2  tenant gate        → is the assistant enabled for this tenant at all?
  3  surface gate       → may this Principal use this Surface?
  4  derive scope       → visibility, partition, corpus — fails closed on anything unrecognised
  5  collect grants     → role grants ∪ direct grants ∪ pack grants
  6  build registry     → ungated tools + each gated group whose grant is held
  7  intersect          → with the Profile's declared tool list
  8  negotiate          → withhold anything this Surface cannot render

D.3 Composition

Grants compose; they do not nest. Two grants that sound hierarchical usually are not.

D.4 The three-place rule

D.5 Telling the model what it cannot do

A withheld tool is simply absent from the function list — the model is not told it exists and is unavailable, which would invite it to explain restrictions it cannot see. But when a tool degrades rather than disappearing, the model must know.

D.6 Custom grants

Customers will need grants the platform did not ship. The extension point is deliberately narrow.

Configuration is where this platform either scales to many surfaces or quietly turns back into code. The whole design rests on one claim: everything that varies between surfaces is data. This section specifies what that means precisely enough to hold.

E.1 The layers

Five layers, resolved in order, each narrower than the last. A value set at a lower layer wins — subject to the immutability rules in §E.3.

E.2 Merge semantics

E.3 What may never be overridden

E.4 Template resolution

Instructions are templates. Placeholder substitution is the most direct path from configuration into the model's context, so it is the most constrained.

E.5 Configuration as data

E.6 Drift detection

Assistance nobody asked for, on work in progress. The most valuable surface archetype and the easiest to make hostile — the entire design problem is earning attention you were not given.

F.1 What makes it different

F.2 Trigger model

F.3 Lifecycle

  trigger ──▶ eligible? ──▶ compute ──▶ publish ──▶ displayed ──┬──▶ accepted  ──▶ applied + signal
                 │                                                 ├──▶ rejected  ──▶ dismissed + signal
                 │                                                 ├──▶ ignored   ──▶ expires + signal
                 └──▶ suppressed: throttled · stale · duplicate · not granted

F.4 Presentation rules

Eleven logical structures. Whether they become tables, collections or documents is an implementation choice; the fields, the invariants and the access patterns are not.

G.1 Transcript

G.2 Message

G.3 Artifact

G.4 Interaction event

G.5 Run

G.6 Queued job

G.7 The remaining five

G.8 Retention

Nine screens. In managed mode they are the product's console; in self-hosted mode the same screens ship as an operator area. Both read and write the same configuration, validated by the same validator — a console that could produce configuration a file could not would be a second source of truth.

H.1 Profile editor

The screen that decides whether configuration stays data. It must make the right thing easy and the duplicating thing visible.

H.2 Prompt operations

H.3 Grants and access

H.4 Adoption

H.5 Run inspector

The support screen. Given a conversation, show what happened.

H.6 Audit

Every change to assistant behaviour is recorded: profile edits, prompt elections, grant assignments, model changes, enablement toggles, and any revelation of conversation content in the run inspector. Immutable, exportable, and queryable by principal and by object.

Almost every complaint about an assistant's quality is a retrieval complaint wearing a reasoning costume. Before tuning a prompt, establish whether the passage that would have answered the question was in the context at all.

A.1 Two query shapes, one system

A single retrieval configuration cannot serve both well. The two options are to expose both behaviours as distinct tools with descriptions that steer the model between them, or to classify the query and switch strategy internally. The first is more predictable and easier to evaluate; the second is less work for the model. Prefer the first.

Four levels, each with a distinct job. Collapsing any two of them is a decision that becomes expensive to reverse once an index exists.

B.1 Document record

The chunk does three jobs that pull in opposite directions: it is what gets matched, what gets permissioned, and what gets cited. Every chunking decision is a trade between those three, and every one of them is expensive to revisit.

C.1 The three jobs in tension

C.2 Strategies

C.3 Chunk record

C.4 Chunking is a versioned decision

Two indexes over the same chunks, plus the machinery that keeps both current. Freshness failures are the quietest defect class here — nothing errors, answers are simply wrong in a way that looks authoritative.

D.1 Two indexes, one corpus

D.2 Lifecycle

  host content changes
        │
        ├──▶ ingest        normalise, extract text, resolve structure
        ├──▶ chunk         per strategy, deterministic, hash each chunk
        ├──▶ diff          compare hashes: unchanged chunks are skipped entirely
        ├──▶ embed         changed chunks only, stamped with embedding version
        ├──▶ index         write to both lexical and semantic
        └──▶ publish       atomically visible; partial states are never queryable

  deletion / permission change ──▶ propagates on the same path, at higher priority

D.3 Freshness contract

The section to read twice. Retrieval is where access control is most often implemented incorrectly, because the correct implementation costs index design and the incorrect one works in every test written by someone with full access.

E.1 Why document-level control fails

The intuitive design attaches an access list to the document and filters retrieved results against it. It fails the moment a document has mixed visibility inside it — a report with a restricted annexe, a record with a redacted section, a case file with sealed exhibits.

E.2 Filter before rank, never after

E.3 Existence is itself disclosure

In some domains, revealing that a document exists is the leak — a sealed filing, an unannounced acquisition, an HR case. This changes what an empty result may say.

E.4 Permission changes are index events

Combining two indexes whose scores mean different things, then spending a limited context budget on the result. The budget constraint is what makes this hard — retrieval is not "find relevant things", it is "choose the best fifteen thousand tokens".

F.1 Fusion

F.2 Signals beyond similarity

F.3 Reranking

F.4 Context budgeting

The final step, and the one most often left implicit. A budget is not a chunk count — it is a token allowance shared with instructions, transcript history and tool results.

  total window
    ├── instructions        fixed, known in advance
    ├── transcript          elastic — the first thing to compress
    ├── retrieved passages  elastic — the second
    ├── tool results  variable, arrives mid-run
    └── response headroom       reserved, never borrowed against

The model drives retrieval through the tool contract from Volume II. What makes retrieval tools distinctive is that the model writes the query — so the description is doing more work here than anywhere else in the system.

G.1 Shape the tool set to the query shapes

G.2 What a retrieval result returns

G.3 Empty results are a first-class outcome

G.4 Multi-step retrieval

Real questions often need more than one pass — find the policy, then find what superseded it, then find the exception that applies to this department. The runtime already loops, so this needs governance rather than new mechanism.

Grounded and cited are different properties, and conflating them is why so many assistants produce citations that do not support the sentence they are attached to. Grounding is whether the claim came from the evidence; citation is whether the reader can check.

H.1 Three levels

H.2 Binding, not appending

H.3 The citation contract

What the instructions must say, in every profile that retrieves. This is configuration, not code, and it belongs in the platform layer so a tenant cannot remove it.

H.4 Verification

Most deployments end up with more than one corpus — a published library and an internal wiki, a records system and a document store, a customer's content and a licensed feed. They differ in freshness, permission model, quality and score scale.

Retrieval degrades quietly. Content grows, embeddings age, queries shift, and nothing errors. These are the instruments that make the degradation visible.

J.1 What to record per retrieval

J.2 Drift

J.3 Cost

J.4 What Volume IV will build on this

Everything above produces measurements without labels — rank of cited passages, empty-result rates, grounding samples, filter ratios. That is enough to detect regression but not enough to judge quality. The next volume adds labelled evaluation: golden question sets, retrieval recall against known-correct passages, tool-selection regression, and staged comparison when a prompt, model or chunking strategy changes.

"The assistant is bad" is not actionable, and it is what you will receive. Quality here is at least eight independent properties, each failing differently, each measured differently, and each fixable by a different team.

A.1 The two-sided errors

Three of these properties fail in both directions, and most teams measure only one side.

Three tiers, each answering a question the others cannot. Build them in order — the cheapest tier catches most regressions, and the expensive tiers are only worth their cost once the cheap one is running.

B.1 What each tier costs to maintain

A curated set of cases with known-good outcomes. Smaller and honest beats larger and invented — a hundred real questions with carefully established answers is worth more than a thousand generated ones.

C.1 Composition

C.2 A case record

C.3 Rot, and the frozen slice

Two mitigations, used together:

• Pin a corpus snapshot for the labelled tier. Evaluation runs against a frozen slice, so a score change means a system change rather than a content change.
• Re-validate on a cadence against live content, and treat divergence between frozen and live scores as its own signal — it measures how much the corpus has moved.

The cheapest evaluation in the system and the one to build first, because it requires no model call at all. Given a question and its expected passages, ask whether retrieval found them. Seconds to run, and it catches the majority of quality regressions.

Did the model call the right tool, with sensible arguments? Independent of whether the final answer was good, cheap to check, and the thing that silently breaks whenever someone edits a tool description.

The expensive tier, and the one with the most room for self-deception. Judge properties that can be judged; resist collapsing them into a score out of ten.

F.1 Using a model as judge, carefully

Which evaluation to run when. The value of this table is that it names the non-obvious couplings — the changes whose blast radius is wider than it looks.

The only tier that can find a failure nobody anticipated. Its output is not a score — it is new cases for the labelled set and new categories for the rubric.

H.1 Sampling

H.2 The rubric

Reviewers score the same properties as §F, using the same vocabulary. Divergence between human and automated judgment is itself the measurement — it is how the judge gets calibrated, and how you learn the rubric has drifted from what the domain actually cares about.

What production tells you for free, if the surfaces are built to record it. These are the tier-0 instruments, and they are the ones that catch the failure you did not predict.

I.1 Comparing configurations in production

Where an experiment is warranted, hold everything else constant — model, prompts, retrieval configuration and corpus version — and change one. A comparison across two configurations that differ in three ways produces a result nobody can act on.

This architecture deliberately places untrusted content into model context — retrieved passages, uploaded files, and the host records a panel or ambient surface is reading. That is not an incidental risk; it is the design. Treat it accordingly.

J.1 Where untrusted content enters

J.2 Defences, in order of effectiveness

J.3 The exfiltration path worth naming

The specific attack this architecture must close: injected content instructs the model to take data it legitimately retrieved and put it somewhere the attacker can read — into a mutation, an outbound tool, a generated artifact, or a citation handle pointing outward.

J.4 Testing it

What must never be emitted, what must never be stored, and who decides. Most of this is tenant configuration over platform-enforced primitives.

K.1 Output constraints

K.2 Sensitive data

Two distinct threats sharing one control surface: someone extracting more than they should, and someone — often no one in particular — spending more than you can afford.

What people are owed in order to rely on it: knowing what it can see, being able to correct it, and being able to stop it. This is also the half of safety that shows up in adoption numbers rather than incident reports.

M.1 Memory and personalisation

Retaining anything about a person across conversations is a trust decision before it is a feature. If the platform offers it, it must offer the controls alongside — not later.

It will. The measure of the platform is how quickly a specific behaviour can be stopped without taking everything else down with it.

N.1 Levels of intervention

N.2 Classification

N.3 What the run record must support

Every incident begins with "what actually happened in that conversation". Volume II's run inspector answers it if — and only if — the run recorded resolved instructions, the registry snapshot, tool calls with outcomes, retrieval decisions, and envelope delivery results.

An assistant is not a service with one failure mode and one cost line. It is a request path that spans a datastore, an index, a set of tools and a probabilistic model priced per token — each with its own operational character.

A.1 What is actually running

A.2 Who owns what

Three shapes, distinguished by where the boundary falls — and the boundary that matters is almost never the one procurement asks about first.

B.1 What crosses which boundary

B.2 The invariant across all three

The same platform runs in every topology, with the same interfaces. What varies is where processes sit and who holds the keys — never what the code does. A topology that requires a different build is not a topology; it is a second product, and it will fall behind within two releases.

The single external dependency that is metered, rate-limited, versioned on someone else's schedule, and non-deterministic. Everything about operating this platform is shaped by that.

C.1 Task classes want different models

C.2 Provider abstraction, honestly

Abstract the transport, the retry behaviour, the token accounting and the streaming shape — those genuinely normalise. Do not pretend the models themselves are interchangeable: instructions tuned on one provider degrade on another, tool-calling conventions differ in ways that change selection accuracy, and context limits are not fungible. A provider switch is a change that must clear the evaluation gate, not a configuration edit.

The failure that matters is not being slow; it is being slow in the shared, correlated way that turns provider pressure into a full outage.

D.1 Latency is bimodal, and users notice the shape

A turn that answers from context is fast; a turn that retrieves and calls two tools is several times slower. Averages describe neither. Report percentiles split by turn shape, and give the surface something honest to show while the slow shape runs — the first token, the retrieval step, the tool being called. Perceived latency is dominated by whether anything is happening on screen, not by total duration.

Model inference dominates, but not in the proportion most teams assume — and the cost that surprises people is never the one on the conversational path.

Proportions vary widely by deployment; the shape is the point. Two observations survive across every deployment worth studying:

E.1 The unit that actually matters

Ordered by effect. The first three are close to free; the rest trade quality for money and should be made deliberately, with the evaluation set open.

Conventional service telemetry answers none of the questions you will actually have. The run record from Volume II is the primitive; everything else aggregates it.

G.1 The four views that matter

Promise availability and latency, which you control. Do not promise accuracy, which you do not — and be direct about why rather than burying it.

Every dependency here can fail independently. Design the ladder in advance, or the system chooses the bottom rung on your behalf.

Four kinds of change, with sharply different blast radii. The ones that touch the index are the ones to plan for years ahead.

J.1 Rebuilding an index without an outage

1  Build the new index alongside the live one, at throttled throughput
   weeks, for a large corpus — budget for it as a project
2  Dual-write source changes to both indexes from the moment the build starts
   otherwise the new index is stale before it is ready
3  Evaluate retrieval against both, on the same frozen slice
   Volume IV §D — no model call needed, so this is fast and cheap
4  Shift read traffic per tenant, watching empty-retrieval rate
5  Retain the old index until the next evaluation cycle closes
   the rollback path, and the reason step 2 was worth the trouble

Multi-tenancy here carries a risk ordinary applications do not have: a boundary failure does not leak a record, it leaks a synthesised answer built from records.

The useful question is not what to back up but what is rebuildable — the answer splits this system cleanly in two.

The question every prospective operator asks, answered without the vendor's thumb on the scale.

A sequence that has survived contact with reality, ordered so each phase produces the evidence the next one needs.

Five roles reach into this platform, and they are not equally dangerous. Ranking the extension points by blast radius is the first design decision, because it determines which ones get a review process and which get a form.

Extensions outlive the release they were written against, or nobody writes them. That requires declaring, in advance, which surfaces are promises and which are implementation.

B.1 Deprecation, stated as a policy rather than an intention

A tool is a described, permissioned, invocable unit of behaviour. The code is the easy half; the description is the interface that actually determines whether it ever runs.

C.1 The description is the product surface

Selection accuracy is set almost entirely by how tools are described, and descriptions are edited by whoever last touched the code. Volume IV §E made the measurement point; the authoring point is narrower:

C.2 Composition

Tools that are only ever used together should usually be one tool. Two calls mean two chances to select wrongly, two round trips, and a partial state in between if the second fails. Split them only when either is genuinely useful alone — the unit is a task a person would name, not an endpoint your API happens to have.

Three tests, of which the second is the one nobody runs and the one that breaks.

The common integration: an existing product wants an assistant inside it, with its own users, its own records, and its own visual language.

E.1 The context handshake

Principal   a short-lived token the platform verifies independently
            not a user id the host merely asserts
Subject     a reference to the record in view, resolved by the platform
            not the record's contents — the platform re-reads it under the
            principal's grants, which is how an ambient surface stays scoped
Visibility  what the person can currently see, so the assistant can say so
            Volume II §C.3 — the affordance, not a permission input
Brand       tokens only: colour, type, radius, density
            §J — structure and safety affordances are not themeable

When the built-in surfaces do not fit — a voice channel, a chat platform, a terminal, a kiosk — the surface contract defines what any surface must provide to be one.

The highest-stakes extension point. A connector decides what enters the corpus and — far more consequentially — who is allowed to retrieve it.

G.1 The permission-mapping problem

Source systems express access in their own vocabulary — groups, roles, sharing links, inheritance, per-item exceptions. The platform expresses it as grant predicates evaluated at retrieval. Mapping between them is lossy in a direction that matters.

Exposing the assistant's tools to other software — an external agent, an automation, another vendor's assistant. Structurally different from a surface, and the differences bite.

The other direction: letting the host react to what the assistant did, without polling and without reading the transcript.

The platform is meant to disappear into someone else's product. The line is between appearance, which is fully theirs, and the affordances that make the thing trustworthy, which are not negotiable.

The list that makes an extension ecosystem survivable. Each is enforced structurally — an extension that tries has no path, rather than a policy telling it not to.

How an extension ships, gets checked, and gets turned on — deliberately three separate steps.

The common starting position is not a blank slate — it is a homegrown assistant that works well enough to be politically difficult to replace and badly enough to need replacing.

Extension mistakes that look entirely reasonable at the time.

This is a conformance check, not a code review. The question is whether a concept the reference treats as load-bearing exists here, not whether the code implementing it is good.

Checked against a single commit of that codebase. Line references are to that state and will drift.

The nine that hold up. Worth stating plainly, because the rest of this document is about gaps and that gives a misleading impression of the whole.

C.1 The registry is composed from grants, before anything else happens

The reference calls this the defence that holds when the others fail, and it is implemented here exactly as described. Fifteen tools are unconditional; usage analytics, business metrics and report building are each added only when the corresponding permission answers true, read from the user and not from anything in the conversation.

750  def self.tool_registry(ctx)
770    usage_allowed   = usage_user&.can_view_ai_chat_usage_tools? || false
776    reports_allowed = usage_user&.can_build_ai_reports?         || false
780    metrics_allowed = usage_user&.can_view_business_metrics?    || false
782    registry = { … 15 unconditional tools … }
806    if usage_allowed   then registry["ai_usage_query"] = …
821    if metrics_allowed then registry["stat_query"]     = …
836    if reports_allowed then registry["report_builder"] = …

The detail that shows this was understood rather than copied: the error-recovery path resolves through the same registry rather than a separate default list, with a comment saying why — a failing turn must not be able to reach a tool the principal lacks. That is the invariant in Volume VI §K, enforced in the place it is easiest to forget.

C.2 Everything visible funnels through one definition

ContentScope is the single answer to "what may this caller see", used by result lists, single fetches and search alike. Volume II §D asks for exactly this and warns against the alternative — scope decided at each call site — which is how divergence starts.

C.3 Prompts are versioned with an elected current

ChatAssistantPromptVersion holds monotonic versions scoped per prompt, with the parent naming a current_version_id. Election is a pointer move and rollback is the same move backwards — the property Volume IV §G requires of the change gate and Volume V §J requires of incident response. It is in place without the gate that would use it, which makes it the cheapest of the remaining gaps to close.

C.4 Ambient assistance is real, and instrumented better than most

Seventeen named features, the majority of them passive suggestion surfaces — headlines, tags, photos, subject lines, summaries, newsletter ordering, clarity, bias, ledes, pitches. Events are bucketed into viewed, applied, submitted and interacted, and the registry file explains why the fourth bucket matters: leaving out interacted undercounts features that are reloaded more often than first opened. That is an adoption-measurement insight most teams reach after a year of arguing about a dashboard, written down in a config file comment.

Two patterns the codebase arrived at independently, for reasons unrelated to the ones the reference gives. Both are cases where the implementation is ahead of the abstraction.

D.1 Reference handles, invented for a rendering problem

Volume III derives opaque handles from a safety argument: a claim must resolve to a source, and the resolution must be internal so injected content cannot address anything outside the run. This codebase has the same structure — ConversationStore keeps the payload and hands the model a short reference — but reached it from an entirely different direction:

It bounds itself at forty entries per bucket, oldest evicted, so a long conversation cannot grow the row without limit. The safety property Volume III argues for comes along free, which is usually how the durable patterns arrive.

D.2 A vocabulary the model is never asked to transcribe

config/ai_feature_registry.yml maps what people say onto what is actually logged: "Bias" resolves to neutral_voice_assessment_suggestion_submitted. Tools take a feature key and resolve it server-side; the list of valid keys is injected into the system prompt. The model never types an event name.

Right in structure, with one soft edge that is defensible today and would not survive a second tenant.

58  @brand ||= (Brand.find_by(id: @brand_id) if @brand_id.present?) || Brand.default_brand

Scope resolves from context rather than model output, which is the property that matters. But an absent or unresolvable brand falls back to a default brand rather than to nothing. Volume V §K asks for the tenant identifier to be part of the retrieval predicate and for failure to close rather than open.

Both half-built, and in the same shape: the mechanism exists, the dimension the reference cares about does not.

F.1 Model selection is per assistant, not per task class

AssistantSetting carries a chat_model and a vision_model, selected from managed ChatModel records, with an admin screen that lists what the provider currently offers. That is real routing infrastructure — better than a constant in a config file, and it makes a provider change a data change.

What it does not do is distinguish task classes. Volume V §C.1 calls routing by task class the highest-leverage cost decision available, because ambient volume against a conversational-grade model is how the economics come apart. With seventeen features, most of them passive suggestion surfaces firing on editing activity, this is the deployment that lever was described for.

F.2 Token accounting exists but misses the turns that matter

Usage normalisation is careful — both provider response shapes handled, accumulation across every call in a job, and a stated rule that accounting must never break a run. It accumulates onto a thread-local armed for the duration of an async job.

117  def self.record_usage(tokens)
118    meta = job_metadata
119    return unless meta.is_a?(Hash)  ← no job armed: silent no-op

Chat turns that run inline rather than through the queue therefore record nothing. The instrumentation is sound; the attribution dimension is the job, where Volume V §E needs it per turn, per principal and per tenant. Cost per active user — the only unit that composes with a commercial model — is not currently derivable, and reconstructing it after the fact never comes out clean.

Sources are carried through the pipeline properly. The failure path is where the reference's objection lands.

The overview path asks for a structured source list and parses it. When that parse fails, it falls back to scanning the model's prose for markdown links and treating whatever it finds as citations:

663  # Fallback: pull [label](url) markdown links out of the body as sources.
664  sources = text.scan(/\[([^\]]+)\]\((https?:\/\/[^\s)]+)\)/)…

The fix does not require the full handle machinery: validating scraped URLs against what retrieval actually returned this turn, and dropping the rest, would close most of it.

Absent entirely. Low consequence today, and that is exactly why it is worth fixing now.

Four tools write: conversation_store, define_theme, feedback_capturer and feedback_updater. There is no confirmation concept in the chat service, in the tools, or in the client — the word does not appear.

The largest gap, and the one that compounds. There is no way to know whether any change to this assistant made it better.

There are 15 spec files under spec/, covering models including content_scope_spec.rb and chat_configs_spec.rb. None of them can run: rspec is not in the Gemfile. The intent was there; the harness never landed.

Conversation state is persisted. What happened during a turn is not.

Conversation.metadata holds tool payloads under the handle scheme from §D.1, so the artifacts of a turn survive. What is missing is the turn itself: which instructions resolved, which registry was composed, which tools were called with what arguments and what outcome, what retrieval returned, and what was delivered.

Built correctly, scoped narrowly. The narrowness looks deliberate.

The MCP server speaks Streamable HTTP with an SSE path for streamed calls and a JSON fallback, reports itself at version 0.2.0, and exposes exactly one tool — search_overview, brand-scoped, returning a synthesised overview. Volume VI §H's independence point is handled: the tool description tells callers each call stands alone and that context must be handed back.

Ordered by value per unit of effort, which is not the order of severity.

Running the comparison in the other direction is the part that actually tests the reference, and it did not come out clean.