1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

# COGNI.BUILD

A framework for putting a tool-using assistant inside a product that already
has users, content and permissions.

## Layers, lowest first

  kernel      primitives. Value objects, errors, ids. Depends on NOTHING
  engine      the LLM + tool execution engine. Assistant, Thread, Message,
              RunLoop, Tool::Base, provider adapters. Knows nothing about
              tenants, permissions or profiles — that is what makes it reusable
  channel     server-driven UI. Broadcaster, Marker, ReferenceStore. How a tool
              pushes a rendered widget to a surface and hands the model a token
  domain      entities and policies. Principal, Grant, Scope, Profile, Corpus,
              Citation, Proposal
  ports       abstract outbound interfaces. The hexagon edge
  adapters    concrete implementations of ports. Vendors live here and ONLY here
  services    application services. Orchestration; composes domain + engine
  surfaces    delivery. Chat, ambient, machine, and their host handshake
  admin       the admin-view framework the console is built from
  evaluation  the measurement harness
  testing     harness, fixtures, doubles, assertions
  runtime     the composition root. Container, configuration, bootstrap

  platform/   PRIVATE. The hosted control plane and deployed services
  infra/      PRIVATE. Terraform, manifests, migrations, runbooks

## The dependency rule

Dependencies point DOWN, never up or sideways across a layer boundary.

    runtime -> surfaces -> services -> adapters -> ports -> domain -> engine -> kernel

`engine` importing `domain` is a build error. That is deliberate: the moment the
engine knows what a Tenant is, it stops being extractable.

Adapters depend on ports. Ports never depend on adapters. `runtime/container`
is the only place that knows which adapter satisfies which port.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

# Conventions

## Class suffixes

  *Base        abstract, meant to be SUBCLASSED by an integrator
               Tool::Base, Surface::Base, Admin::ViewBase, Adapters::Base
  *Port        an abstract OUTBOUND interface. Lives in ports/. Named for the
               capability, not the vendor: ModelPort, VectorStorePort
  *Adapter     a concrete implementation of exactly one Port. Named for the
               vendor or technology: PgVectorAdapter, OpenAIResponsesAdapter
  *Service     an application service. Orchestrates; holds no request state
               beyond a call. TurnService, RetrievalService
  *Registry    composition and lookup. ToolRegistry, SubsystemRegistry
  *Policy      an isolated decision, injectable and testable alone
               ScopePolicy, RoutingPolicy, ThrottlePolicy
  *Definition  a DECLARATIVE description of an extension, supplied by an author
               ToolDefinition, SurfaceDefinition, ConnectorDefinition
  *Result      a return value carrying success data
  *Outcome     a return value that may be one of several terminal states
  *Record      something written for audit or later inspection. RunRecord
  *Store       persistence for one entity family
  *Error       a failure type. All descend from kernel Error

## Data class categories

  Value object  immutable, equality by VALUE, no identity.
                Grant, Marker, Usage, Citation, TokenCount, Scope
  Entity        has identity and a lifecycle. Conversation, Profile, Corpus,
                Tenant, Principal
  Definition    declarative registration data, validated once at define time
  DTO           crosses a boundary. TurnRequest, ModelResponse, Envelope
  Record        append-only, for audit. RunRecord, AuditEntry, ReviewRecord

Value objects are constructed, never mutated. Entities are loaded and saved.
If you cannot say which of the five a new class is, it is probably two classes.

## Method naming

  build_*   pure construction, no side effects
  resolve_* look something up and fail closed if it cannot be found
  compose_* assemble from parts, upstream of any content being read
  emit_*    push to a channel; returns a Marker, not the payload
  propose_* create something a PERSON must accept before it takes effect
  on_*      an event handler
  *?        a predicate returning a boolean

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# One turn, through the layers

  surfaces::ChatSurface           holds identity, never authority
    -> services::TurnService
         domain::ScopePolicy.resolve(principal)      scope, server-derived
         domain::ToolRegistry.compose(principal)     FROM GRANTS ALONE
         domain::ProfileRepository.elected(tenant)   instructions
    -> engine::Assistant.new(adapter:, thread:, tools:)
    -> engine::RunLoop.execute(auto_tool_execution: true)
         adapter.complete(...)  ->  Adapters::Response
         tool_call ->  Tool::Registry.fetch  ->  Tool::Base#call
                       tool may  emit(payload) -> channel -> Marker
         answer    ->  services::GroundingService.verify(citations)
    -> channel::Broadcaster.publish(envelope)
    -> domain::RunRecord sealed

## Why the engine sits below the domain

`engine::Assistant` takes an already-composed `Tool::Registry`. It never asks
who the principal is, because by the time it runs the question is settled. That
single constraint is what lets the engine be extracted, tested without a
database, and reused by a product with a completely different permission model.

## Invariants, and the class that enforces each

  capabilities come from grants, before content   domain::ToolRegistry.compose
  mutations are proposed, never executed inline   engine::RunLoop + Tool::Base
  retrieval scope is server-derived, fails closed domain::ScopePolicy
  tenant partitioning is below extensions         platform::TenantRepository
  provenance and the label are surface-rendered   surfaces::Renderer

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

workspace cogni-build

  layer kernel      { depends_on: [] }
  layer engine      { depends_on: [kernel] }
  layer channel     { depends_on: [kernel] }
  layer domain      { depends_on: [kernel, engine, channel] }
  layer ports       { depends_on: [kernel, domain] }
  layer adapters    { depends_on: [kernel, domain, ports] }
  layer services    { depends_on: [kernel, engine, channel, domain, ports] }
  layer surfaces    { depends_on: [services, domain, channel, kernel] }
  layer admin       { depends_on: [services, domain, kernel] }
  layer evaluation  { depends_on: [services, domain, kernel] }
  layer testing     { depends_on: [*] }
  layer runtime     { depends_on: [*] }

  # Enforced in CI. An upward or sideways import fails the build.
  rule no_upward_dependency
  rule adapters_implement_exactly_one_port
  rule vendors_appear_only_in_adapters

  publish packages/*   registry: public    cadence: minor monthly
  deploy  platform/*   registry: internal  cadence: continuous

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

package kernel
module Kernel

# Opaque, typed ids. Distinct classes rather than bare strings, so a TenantId
# can never be passed where a RunRef belongs — the mistake that produces
# cross-tenant bugs no test catches.
abstract class Identifier            # value object
  attr_reader :value  String
  fn initialize(value); freeze
  fn ==(other) -> Bool               # equality by value AND by class
  fn to_s() -> String

class TenantId    < Identifier
class PrincipalId < Identifier
class RunRef      < Identifier
class ConversationId < Identifier
class CorpusId    < Identifier
class DocumentId  < Identifier
class ChunkId     < Identifier
class ProposalId  < Identifier
class ToolName    < Identifier
class GrantKey    < Identifier

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

package kernel
module Kernel

# Every fallible call returns one of these. Nothing in this framework throws
# across a layer boundary — an exception into the run loop becomes an
# unexplainable stall, where a described failure lets the model tell the person
# what happened.
class Result<T>                       # value object
  fn self.ok(value: T)   -> Result<T>
  fn self.err(e: Error)  -> Result<T>
  fn ok?()    -> Bool
  fn value()  -> T                    # raises if err — call ok? first
  fn error()  -> Error
  fn map(&block)     -> Result
  fn or_else(&block) -> Result

# Outcome is for calls with more than two terminal states, where `err` would
# flatten a meaningful distinction.
class Outcome                         # value object
  variants: Completed | Refused | Halted | Proposed | Failed

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

package kernel
module Kernel

class Error                           # value object; never raised across layers
  attr_reader :message      HumanText        # written for the PERSON
  attr_reader :model_hint   ModelFacingText? # what the model should do next
  attr_reader :retryable    Bool
  attr_reader :detail       Map              # run record only, never rendered

class NotFoundError        < Error
class NotPermittedError    < Error    # see masking below
class InvalidArgumentError < Error    # model_hint carries the fix
class UpstreamError        < Error    # retryable
class TimeoutError         < Error
class BudgetExceededError  < Error    # must read as a LIMIT, not a fault
class ConflictError        < Error
class DefinitionError      < Error    # raised at DEFINE time, not run time

# Where the existence of a thing is itself sensitive, NotFound and NotPermitted
# must be indistinguishable to the caller. The run record keeps the truth.
class ErrorMasker                     # policy
  fn mask(e: Error, policy: OutputPolicy) -> Error

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package kernel
module Kernel

# The distinction is load-bearing. HumanText is rendered to a person and may be
# localised. ModelFacingText goes into a prompt, is never localised, and is
# evaluated by the selection suites. Mixing them is how a translated tool
# description silently changes selection accuracy in one locale.
class HumanText       < Text          # value object
  attr_reader :locale
class ModelFacingText < Text          # value object
  fn token_estimate() -> TokenCount

class Text                            # abstract value object
  fn to_s() -> String
  fn blank?() -> Bool

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

package kernel
module Kernel

# Immutable and additive. Accumulated across every model call in a run and
# attributed PER TURN and PER PRINCIPAL — not per background job, which leaves
# every inline turn invisible in the cost data.
class Usage                           # value object
  attr_reader :input, :output, :total  TokenCount
  attr_reader :calls                   Int
  attr_reader :task_class              TaskClass

  fn self.zero() -> Usage
  fn self.from_provider(raw: Map, task_class:) -> Usage
    # Normalises both provider shapes: input_tokens/output_tokens and
    # prompt_tokens/completion_tokens. Never lets accounting break a run.
  fn +(other: Usage) -> Usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14

package kernel
module Kernel

class SemVer                          # value object
  attr_reader :major, :minor, :patch
  fn satisfies?(range: VersionRange) -> Bool

enum Stability { STABLE, EVOLVING, INTERNAL }
annotation @stability(Stability)

class Deprecation                     # value object
  attr_reader :symbol, :declared_in, :replacement, :remove_after
  # declared_in is the release where the REPLACEMENT ships, not where removal
  # is planned. Extenders need the overlap; the overlap is the point.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

package engine
module Engine

# The reusable core. Owns one conversation against one model adapter, and knows
# NOTHING about tenants, permissions, profiles or surfaces. Those live in
# domain/ and services/, above it.
#
# That ignorance is the feature: it is what lets this be extracted into a
# library and reused by a product with a completely different permission model.
class Assistant
  attr_reader   :adapter      Adapters::Base
  attr_reader   :thread       Thread
  attr_reader   :tools        Tool::Registry     # ALREADY composed upstream
  attr_reader   :usage        Kernel::Usage
  attr_accessor :emitter      Streaming::Emitter?

  fn initialize(adapter:, thread: Thread.new, tools: Tool::Registry.empty,
                instructions: ModelFacingText?, emitter: nil)
    @usage = Usage.zero
    thread.add(Message.system(instructions)) if instructions

  fn add_message(content:, role: "user", tool_call_id: nil) -> Message
  fn run(auto_tool_execution: Bool, bounds: RunBounds) -> RunOutcome
    RunLoop.new(assistant: self, bounds: bounds).execute(auto_tool_execution:)

  # ── called by RunLoop ─────────────────────────────────────────────────────
  fn complete() -> Adapters::Response
    response = adapter.complete(thread.to_wire, tools.to_wire, emitter)
    @usage = usage + Usage.from_provider(response.raw_usage, adapter.task_class)
    response
  fn submit_tool_output(tool_call_id:, output:) -> void

  # Every URL a tool actually returned this run. GroundingService intersects
  # generated citations against this set, so a link the model invented cannot
  # be rendered as a source.
  fn retrieved_urls() -> Set<Url>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

package engine
module Engine

class Thread
  attr_reader :messages  [Message]

  fn add(m: Message) -> Thread
  fn last() -> Message?
  fn to_wire() -> [Map]              # adapter-neutral; adapters reshape it
  fn token_estimate() -> TokenCount
  fn tool_messages() -> [Message]    # role == "tool"; the evidence set

  # Trimming order when over budget, most expendable first: history, then
  # older tool observations, then subject detail. NEVER the system message,
  # NEVER the tool descriptions, NEVER the user's actual message.
  fn trim_to(limit: TokenCount) -> Thread

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package engine
module Engine

class Message                        # value object
  ROLES = [system, user, assistant, tool]

  attr_reader :role, :content, :tool_calls, :tool_call_id, :model

  fn self.system(t: ModelFacingText) -> Message
  fn self.user(t: Text)              -> Message
  fn self.assistant(content:, tool_calls: []) -> Message
  fn self.tool(output:, tool_call_id:)        -> Message

  fn to_wire() -> Map
  fn content_kind() -> TEXT | PARTS  # parts carry attachments and images

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

package engine
module Engine

# Where the engine-level invariants are enforced. Instructions are advisory;
# this class is not.
class RunLoop
  fn initialize(assistant:, bounds: RunBounds)

  fn execute(auto_tool_execution: Bool) -> RunOutcome
    loop:
      guard = bounds.check(state)     else return Outcome::Halted(guard.reason)
      response = assistant.complete()

      case response.kind
      when TOOL_CALLS then
        for call in response.tool_calls:
          tool = assistant.tools.fetch(call.name)
          #    ^ NOT OFFERED is a REFUSAL, never a lookup against the full
          #      catalogue. The error-recovery path resolves here too — a
          #      failing turn must not reach a tool the principal lacks.
          return Outcome::Refused(NOT_OFFERED) if tool.nil?

          if tool.effect == MUTATE then
            proposal = tool.propose(call.arguments)
            return Outcome::Proposed(proposal)     # DOES NOT EXECUTE
          end

          result = tool.call(call.arguments)
          assistant.submit_tool_output(call.id, result.for_model)
      when ANSWER then return Outcome::Completed(response.text, response.citations)
      end

  # Retry discipline: jittered backoff, bounded attempts, NEVER on a mutation
  # whose result is unknown. Retries against a rate-limited provider are the
  # classic self-inflicted outage.
  private fn with_retry(&block) -> Result

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

package engine
module Engine

# A confused model spends without limit. The loop needs a ceiling that is not
# a suggestion.
class RunBounds                      # value object
  attr_reader :max_tool_calls   Int
  attr_reader :max_context      TokenCount
  attr_reader :max_wall_clock   Duration
  attr_reader :deadline         Timestamp

  fn check(state: RunState) -> Continue | Halt

# Halting is a real answer, not an error: the assistant reports what it found
# and that it stopped. A silent stall is the worst outcome, because to the
# person it is indistinguishable from a hang.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

package engine
module Engine

class RunOutcome                     # value object
  variants:
    Completed { text: Text, citations: [Citation], usage: Usage }
    Refused   { reason: RefusalReason }
    Halted    { reason: HaltReason, partial: Text }
    Proposed  { proposal: Proposal }
    Failed    { error: Error }

enum RefusalReason { NOT_OFFERED, NOTHING_FOUND, OUT_OF_SCOPE, PROHIBITED,
                     BUDGET_EXCEEDED, PROVIDER_DOWN }
enum HaltReason    { CALL_CEILING, CONTEXT_CEILING, DEADLINE }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

package engine
module Engine::Tool

# ONE TOOL, ONE CLASS. The unit an author actually writes.
abstract class Base
  # ── declaration ───────────────────────────────────────────────────────────
  class_attribute :definition  Tool::Definition
  class_attribute :grant       GrantKey
  class_attribute :effect      READ | MUTATE      # declared, never inferred
  class_attribute :cost_band   CHEAP | MODERATE | EXPENSIVE

  class fn describe(&block) -> void
    # DSL. Builds the Definition and REFUSES a description with no do_not_use
    # clause — the negative clause is what stops the plausible wrong selection,
    # and it is the part every author omits.
    @definition = Tool::Definition.build(&block)
    raise DefinitionError unless @definition.states_when_not_to_use?

  # ── instance ──────────────────────────────────────────────────────────────
  attr_reader :context   InvocationContext   # principal, scope, run_ref, log
  attr_reader :channel   Channel::Broadcaster?

  fn initialize(context:, channel: nil)
    # No ambient credentials. A tool cannot construct a client or read an
    # environment. Everything it may touch arrives here, or via an injected port.

  abstract fn call(args: Args) -> Tool::Result | Error

  # ── inherited helpers ─────────────────────────────────────────────────────
  protected fn scope() -> Scope              # already resolved; never widen it
  protected fn emit(payload: Renderable) -> Channel::Marker
    channel.publish(payload)                 # -> Marker("[[CHART:c3]]")
  protected fn propose(m: Mutation) -> Proposal
  protected fn fail(error_class, message:, model_hint:) -> Error

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

package engine
module Engine::Tool

class Definition                     # definition object, validated once
  attr_reader :name, :version, :description, :parameters, :result_shape

  fn self.build(&block) -> Definition
    # describe do
    #   does        "Look up the status of a filed request by reference number."
    #   use_when    "the person names or implies a specific request"
    #   do_not_use  "for questions about the process itself"
    #   instead     "answer those from the handbook"
    #   param :reference, String, required: true,
    #         describe: "The request reference, like REQ-4471"
    #   returns model: :compact, surface: :request_card
    # end

  fn states_when_not_to_use?() -> Bool
  fn to_wire() -> Map                # provider-neutral tool schema
  fn for_external_caller(ctx) -> Definition
    # Descriptions written in-product assume a caller who knows the product.
    # External agents do not. This rewrites for that reader.

1
2
3
4
5
6
7
8
9
10
11
12
13

package engine
module Engine::Tool

class Parameter                      # value object
  attr_reader :name, :type, :required, :description  ModelFacingText
  attr_reader :vocabulary  VocabularyId?

  # Where a parameter is drawn from a CLOSED SET of internal identifiers, do
  # not ask the model to transcribe them. Attach a vocabulary: the model is
  # told which human NAMES exist, and the service resolves them server-side.
  # Removes a class of wrong-parameter failure no description tuning fixes.

  fn validate(value) -> Result<Value>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

package engine
module Engine::Tool

# TWO SHAPES FROM ONE CALL. A compact form the model reasons over, and a
# structured form the surface renders. Returning only prose forces the surface
# to parse language, which fails the day the wording changes.
class Result                         # value object
  attr_reader :for_model    ModelFacingText   # often just a Marker
  attr_reader :for_surface  Renderable?
  attr_reader :citations    [Citation]

  fn self.marker(m: Channel::Marker, summary:) -> Result
    # The common case for anything large: the payload went to the surface over
    # the channel; the model receives a short token and never re-ingests it.
  fn self.data(compact:, renderable:) -> Result
  fn self.empty(explanation:) -> Result
    # NEVER return empty success where an Error belongs. An empty result reads
    # to the model as "nothing exists", and it will confidently say so.

1
2
3
4
5
6
7
8
9
10
11
12
13

package engine
module Engine::Tool

# An immutable, already-composed set. The engine receives this; it never builds
# it, because building it requires knowing about grants — a domain concern.
class Registry
  attr_reader :entries   [Class<Tool::Base>]
  attr_reader :snapshot  RegistrySnapshot     # recorded verbatim in RunRecord

  fn self.empty() -> Registry
  fn fetch(name: ToolName) -> Class<Tool::Base>?   # nil means NOT OFFERED
  fn to_wire() -> [Map]
  fn without(name:) -> Registry     # health-driven withdrawal

1
2
3
4
5
6
7
8
9
10
11
12

package engine
module Engine::Streaming

# Perceived latency is dominated by whether anything is happening on screen,
# not by total duration. Phase events exist so a slow turn shows its work.
class Emitter
  fn on_token(&block) -> void
  fn on_phase(&block) -> void
  fn emit_token(delta: String) -> void
  fn emit_phase(p: Phase, detail: HumanText) -> void

enum Phase { RETRIEVING, CALLING_TOOL, RENDERING, COMPOSING }

1
2
3
4
5
6
7
8
9
10
11
12

package engine
module Engine::Streaming

# Providers disagree about chunk shape. This is the ONLY place that knows,
# so adapters stay thin and the Assistant sees one delta type.
class ChunkParser
  fn parse(raw: Map) -> Delta?
  # Responses API:        delta as a String, or delta.content
  # Chat Completions:     choices[0].delta.content
  # Tool-call fragments arrive incrementally and are reassembled here, not by
  # the adapter and not by the loop.
  fn accumulate_tool_call(fragment: Map) -> ToolCall?

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

package engine
module Engine::Adapters

# The one place a vendor may appear. Everything above this line is written
# against Response, never against a provider's JSON.
abstract class Base
  attr_reader :model_version  ModelVersion    # PINNED. Never a floating alias
  attr_reader :task_class     TaskClass

  abstract fn complete(messages: [Map], tools: [Map],
                       emitter: Streaming::Emitter?) -> Response
  abstract fn supports_streaming?() -> Bool
  abstract fn supports_tools?()     -> Bool
  fn health() -> Healthy | Degraded | Down

class Response                       # DTO
  attr_reader :kind        TOOL_CALLS | ANSWER
  attr_reader :text, :tool_calls, :citations, :raw_usage, :model_used

1
2
3
4
5
6
7
8
9
10
11
12
13

package engine
module Engine::Adapters

class OpenAIResponsesAdapter < Base
  fn complete(messages:, tools:, emitter:) -> Response
    payload = { model:, input: build_input(messages), tools:,
                stream: emitter.present? }
    # Responses-shaped input differs from chat-shaped: tool outputs are
    # function_call_output items keyed by call_id, not role:"tool" messages.
    stream_or_post(payload) -> Response

  private fn build_input(messages) -> [Map]
  private fn normalise_usage(raw) -> Map    # input_tokens / output_tokens

1
2
3
4
5
6
7
8
9
10
11
12
13

package engine
module Engine::Adapters

class OpenAIChatAdapter < Base
  fn complete(messages:, tools:, emitter:) -> Response
    payload = { model:, messages:, tools:, stream: emitter.present? }
    stream_or_post(payload) -> Response

  private fn normalise_usage(raw) -> Map    # prompt_tokens / completion_tokens

# Kept alongside the Responses adapter rather than replaced by it: providers
# deprecate on their own schedule, and a second shape in the same interface is
# cheap insurance.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

package engine
module Engine::Adapters

class AnthropicAdapter < Base
  fn complete(messages:, tools:, emitter:) -> Response
    # System text is a top-level parameter here, not a message with role
    # "system". The Thread stays provider-neutral; this adapter lifts it out.
    system, rest = partition_system(messages)
    payload = { model:, system:, messages: rest, tools: to_input_schema(tools) }
    stream_or_post(payload) -> Response

# Instructions tuned on one provider degrade on another, and tool-calling
# conventions differ in ways that change SELECTION accuracy. A provider switch
# clears the evaluation gate; it is not a configuration edit.

1
2
3
4
5
6
7
8
9
10

package engine
module Engine::Adapters

# Replays fixed responses in order, so a test asserts on the LOOP rather than
# on the provider's mood.
class RecordedAdapter < Base
  fn initialize(script: [Response])
  fn complete(messages:, tools:, emitter:) -> Response
    script.shift or raise "RecordedAdapter exhausted"
  fn calls() -> [RecordedCall]       # assert on what the loop actually sent

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

package channel
module Channel

# THE PATTERN THIS LAYER EXISTS FOR.
#
# Not every tool returns data. Many produce a rendered artefact — a chart, a
# timeline, a report, a highlight — that belongs on the SURFACE, not in the
# model's context window. Such a tool pushes the payload over a channel keyed
# to the conversation, stores it under a reference, and hands the model a short
# MARKER. The model then places the marker in its prose; the client swaps the
# marker for the rendered widget.
#
# Two things fall out of this that matter:
#   the payload never re-enters the context window, so a 400-row table costs
#   the model nothing beyond "[[CHART:c3]]"
#   the surface renders structure, so the model is not asked to spell a table
#   out in prose and get the arithmetic wrong on the way
abstract class Broadcaster
  attr_reader :channel_key  ChannelKey   # derived from the conversation and
                                         # principal — NEVER chosen by a tool

  fn publish(payload: Renderable) -> Marker
    ref    = reference_store.put(payload)
    marker = Marker.for(payload.kind, ref)
    deliver(Envelope.new(marker:, payload:, channel_key:))
    marker

  abstract fn deliver(e: Envelope) -> DeliveryOutcome
  fn health() -> Healthy | Degraded | Down

# An injected instruction cannot cause publication to another person's channel,
# because channel_key is derived, not passed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

package channel
module Channel

# The token the model receives and places in its answer: "[[CHART:c3]]".
# Short by design — the model reproduces it verbatim, and every extra character
# is a chance to corrupt it.
class Marker                         # value object
  attr_reader :kind  CHART | TIMELINE | REPORT | PLAN | THEME | TABLE | IMAGE
  attr_reader :ref   String          # short: c3, r1, t2

  fn self.for(kind:, ref:) -> Marker
  fn to_s() -> String                # "[[CHART:c3]]"
  fn self.scan(text: Text) -> [Marker]
  fn self.strip_unresolved(text:, store:) -> Text
    # A marker the store cannot resolve is REMOVED and recorded. The model
    # inventing "[[CHART:c9]]" must not render as a broken widget.

1
2
3
4
5
6
7
8
9
10
11
12
13

package channel
module Channel

# Keeps the payload, hands out the reference. Two wants that turn out to be one
# want: anything broadcast to the page is gone once the reader navigates away,
# and anything a LATER tool needs — a report builder reading back an approved
# plan — has to outlive the turn.
class ReferenceStore
  MAX_PER_BUCKET = 40                # oldest evicted; a long conversation
                                     # cannot grow the row without bound
  fn put(payload: Renderable, bucket: Symbol) -> String
  fn get(ref: String, bucket: Symbol) -> Renderable?
  fn resolve_all(text: Text) -> Map<Marker, Renderable>

1
2
3
4
5
6
7
8
9
10
11
12

package channel
module Channel

class Envelope                       # DTO
  attr_reader :channel_key, :marker, :payload, :target, :issued_at

  # target names the region of the surface to update. Surfaces declare their
  # own targets; the channel does not assume a DOM.
class DeliveryOutcome                # value object
  variants: Delivered | NoListener | Failed(Error)
  # NoListener is NOT an error. The reader navigated away; the payload stays in
  # the reference store and renders when they return.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package channel
module Channel

# What a tool may push. Structured, never HTML — surfaces render, the channel
# transports, and a tool that emits markup has bound itself to one client.
abstract class Renderable            # value object
  abstract fn kind() -> MarkerKind
  abstract fn to_payload() -> Map
  abstract fn summary_for_model() -> ModelFacingText   # one line, no data

class ChartPayload    < Renderable
class TimelinePayload < Renderable
class ReportPayload   < Renderable
class TablePayload    < Renderable
class HighlightPayload< Renderable

1
2
3
4
5
6
7
8
9
10
11

package channel
module Channel::Adapters

class TurboStreamAdapter < Broadcaster
  fn deliver(e: Envelope) -> DeliveryOutcome
    StreamsChannel.broadcast_update_to(e.channel_key,
      partial: "assistant/response", locals: { payload: e.payload },
      target:  e.target)
    Delivered
# Client side: the partial renders a hidden trigger element; a MutationObserver
# picks it up and mounts the widget. The marker in the prose is replaced in place.

1
2
3
4
5
6
7
8

package channel
module Channel::Adapters

class WebSocketAdapter < Broadcaster
  fn deliver(e: Envelope) -> DeliveryOutcome
    socket = registry.for(e.channel_key)  or return NoListener
    socket.send(json(e))
    Delivered

1
2
3
4
5
6
7
8
9
10
11

package channel
module Channel::Adapters

# For the machine interface and for evaluation runs, where there is no surface.
# Tools still call emit(); the payload is captured and returned inline instead
# of being pushed, so a tool needs no branch for "am I headless".
class NullAdapter < Broadcaster
  fn deliver(e: Envelope) -> DeliveryOutcome
    captured << e
    Delivered
  fn captured() -> [Envelope]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

package domain
module Domain

# WHO, resolved by the host's own auth and verified independently. Never
# constructed from anything a model produced or a document contained.
class Principal                      # entity
  attr_reader :id, :tenant_id, :grants, :attributes, :kind
  enum Kind { HUMAN, MACHINE, DELEGATED }

  fn has_grant?(g: GrantKey) -> Bool
  fn machine?() -> Bool

class PrincipalResolver              # service-ish policy
  fn resolve(token: HostToken) -> Result<Principal>
    claims = verify_signature(token)          else return err(NotPermitted)
    grants = grant_repository.for(claims.subject, claims.tenant)
    # Grants are resolved PER REQUEST. Caching them across requests is how a
    # revoked permission keeps working for an hour.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package domain
module Domain

class Grant                          # value object
  attr_reader :key, :name, :description  # name/description are what an
                                         # ADMINISTRATOR reads when granting it
  attr_reader :implies      [GrantKey]
  attr_reader :sensitivity  ORDINARY | ELEVATED | RESTRICTED

class GrantCatalogue                 # registry
  fn declare(g: Grant) -> void
  fn resolve_implied(keys: Set<GrantKey>) -> Set<GrantKey>
  fn known?(k: GrantKey) -> Bool
  # A tool referencing an unregistered grant fails to DEFINE. Otherwise a typo
  # silently produces a tool nobody can ever be given.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

package domain
module Domain

# Everything the assistant can see funnels through here: search, single fetch,
# ambient reads, artifact sources. Scope decided at each call site is how
# divergence starts, and divergence in this particular thing is a breach.
class Scope                          # value object
  attr_reader :tenant_id, :principal, :corpora, :predicate

class ScopePolicy                    # policy
  fn resolve(p: Principal, request: ScopeRequest) -> Result<Scope>
    # FAILS CLOSED. An unresolvable tenant is a refusal, not a default. A
    # default tenant here is a cross-tenant disclosure with a comment
    # explaining that it was intentional.
    return err(NotPermitted) if p.tenant_id.nil?
    Scope.new(tenant_id: p.tenant_id,
              predicate: Predicate.all([eq(:tenant, p.tenant_id),
                                        grant_predicates(p.grants),
                                        attribute_predicates(p.attributes)]))

  fn apply(query: Query, s: Scope) -> Query
    # INSIDE the query, never a post-filter. A post-filter both leaks — a
    # near-miss reveals a document exists — and silently reduces k.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package domain
module Domain

# The bridge from domain (who may do what) to engine (what may be called).
# Composition happens BEFORE any content is read, which is the defence that
# holds when every other one fails: no passage, uploaded file or subject record
# can add a tool, because the set was fixed before they reached the model.
class ToolRegistryComposer           # service
  fn compose(p: Principal, ctx: CompositionContext) -> Tool::Registry
    offered = catalogue.all.select { |t|
      p.has_grant?(t.grant) and
      tenant_enabled?(p.tenant_id, t) and
      health.ok?(t) and                       # withdraw what is broken
      ctx.surface.supports?(t.effect) }       # READ_ONLY surfaces drop MUTATE
    Tool::Registry.new(offered, snapshot_of: p)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

package domain
module Domain

# The configurable identity of one assistant.
class AssistantProfile               # entity
  attr_reader :id, :tenant_id, :name
  attr_reader :instructions  VersionedText      # never edited in place
  attr_reader :routing       RoutingPolicy
  attr_reader :packs, :surfaces, :vocabularies
  attr_reader :current_version_id                # THE ELECTED ONE

class ProfileVersion                 # entity
  attr_reader :version_number, :content, :created_by, :created_at
  fn current?() -> Bool

class ProfileRepository              # store
  fn elected(tenant:, surface:) -> AssistantProfile
  fn draft(id:, changes:, by:) -> ProfileVersion
  fn elect(version:, by:) -> Result<Elected>     # runs the change gate
  fn rollback(id:, to:, by:) -> Elected
  # Election is a pointer move; rollback is the same move backwards. Every
  # level-2 incident lever depends on that being true.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

package domain
module Domain

# A handle is issued when a chunk is RETURNED to the model, and resolves only
# within the run that issued it. Opaque and internal, so injected content
# cannot address anything outside the run.
class CitationHandle                 # value object
  attr_reader :token   String        # short: s1, s2
class Citation                       # value object
  attr_reader :handle, :label, :locator, :source_ref

class CitationIssuer                 # service
  fn issue(chunk: Chunk, run: RunRef) -> CitationHandle
  fn resolve(h: CitationHandle, run: RunRef) -> Source | UNISSUED
  # An UNISSUED handle is STRIPPED from the answer and RECORDED. It is never
  # rendered as a link. That single rule is what stops a fabricated source
  # looking exactly like a real one.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

package domain
module Domain

# effect == MUTATE never executes inside the loop. It becomes a proposal a
# person accepts or declines. Injection then costs an attacker a
# suspicious-looking proposal rather than an action.
class Proposal                       # entity
  attr_reader :id, :tool_name, :arguments, :proposed_to, :expires_at
  attr_reader :rendering  Renderable    # what the person READS before saying yes

class ProposalService                # service
  fn propose(tool:, args:, ctx:) -> Proposal
  fn accept(p: Proposal, by: Principal) -> Result
    ensure by.id == p.proposed_to.id    # the person who SAW it, not any person
    ensure Clock.now < p.expires_at
    ensure by.has_grant?(tool.grant)    # re-checked AT EXECUTION time
  fn decline(p: Proposal, by: Principal) -> void

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

package domain
module Domain

class Corpus                         # entity
  attr_reader :id, :tenant_id, :connector_id, :chunk_policy, :freshness
class Document                       # entity
  attr_reader :id, :source_id, :corpus_id, :metadata, :predicate
class Chunk                          # value object
  attr_reader :id, :document_id, :text, :ordinal, :heading, :predicate
  # A chunk is never orphaned from its document, and carries the document's
  # predicate WITH it so scope can be applied inside the vector query.

class ChunkPolicy                    # policy
  attr_reader :strategy STRUCTURAL|FIXED|SEMANTIC, :target, :overlap, :preserve
  fn chunk(d: Document) -> [Chunk]
  # STRUCTURAL first: split on the document's own boundaries, falling back to
  # size only inside an oversized unit. Fixed windows sever the sentence that
  # carried the qualifier, and the qualifier is usually what made it correct.

1
2
3
4
5
6
7
8
9
10
11
12
13

package domain
module Domain

# Accept the human word, resolve it server-side against reviewable
# configuration, and tell the model only which words EXIST.
class Term                           # value object
  attr_reader :key, :name, :aliases, :expands_to
class Vocabulary                     # entity
  attr_reader :id, :terms, :source_path
  fn resolve(spoken: Text) -> Term | Ambiguous | Unknown
    # exact key, then name, then alias, then a loose contains-match. People
    # abbreviate; the loose pass is what makes this usable rather than clever.
  fn prompt_fragment() -> ModelFacingText

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

package domain
module Domain

# Every incident begins with "what actually happened in that conversation".
# Without this the answer is reconstructed from a transcript plus a guess about
# which permissions the person held — and permissions change.
class RunRecord                      # record, append-only then sealed
  attr_reader :id, :tenant_id, :principal_ref, :surface_id
  attr_reader :profile_version        # WHICH instructions
  attr_reader :model_version          # pinned, not an alias
  attr_reader :registry_snapshot      # what was OFFERED, not just called
  attr_reader :steps, :retrieval_decisions, :delivery, :usage

class Step                           # value object
  variants: ModelCall | ToolCall | Refusal | Confirmation | Broadcast

class RunRecorder                    # service
  fn open(ctx) -> RunRecord
  fn append(r:, step:) -> void
  fn seal(r:, outcome:) -> void

1
2
3
4
5
6
7
8
9
10
11
12
13
14

package domain
module Domain

class Allowance                      # value object
  attr_reader :reservation_id, :ceiling
class BudgetPolicy                   # policy
  fn enforce(p: Principal, req: BudgetRequest) -> Result<Allowance>
    # Reserves up front, reconciles after. A turn that runs unbounded because
    # reconciliation happens at the end is not a budget.
    for window in [PER_TURN, PER_PRINCIPAL_DAY, PER_TENANT_MONTH]:
      return err(BudgetExceeded, message: "You've reached today's limit.") if over
  fn reconcile(id:, actual: Usage) -> void
  # A budget refusal is a message a person can act on, not an error. Cost
  # controls that read as faults get escalated as bugs.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

package domain
module Domain

class RoutingPolicy                  # policy
  attr_reader :by_class  Map<TaskClass, ModelBinding>
  attr_reader :fallback  Map<TaskClass, ModelBinding?>
  attr_reader :residency ResidencyRequirement

  fn binding_for(t: TaskClass) -> ModelBinding
    ensure binding.version.explicit?   # a silently-updated alias means quality
                                       # changed with no change record — the
                                       # most disorienting failure in the system
  fn fallback_for(t: TaskClass) -> ModelBinding?
    ensure fallback.satisfies?(residency)   # availability does NOT outrank a
                                            # data commitment

enum TaskClass { CONVERSATIONAL, AMBIENT, CLASSIFICATION, JUDGING, EMBEDDING }
# AMBIENT against a frontier model is how a pilot's economics come apart, and
# nobody notices the difference in an inline suggestion. This is the single
# highest-leverage cost decision available.

1
2
3
4
5
6
7
8
9
10

package domain
module Domain

# Structural, not tunable to zero. Ambient cost approaches conversational cost
# while producing a fraction of the recognised value, because nobody attributes
# spend to suggestions they never requested.
class ThrottlePolicy                 # policy
  attr_reader :debounce, :per_document_cooldown, :dedupe_window, :daily_ceiling
  fn admits?(subject: SubjectRef, p: Principal) -> Bool
  ensure debounce >= MIN_DEBOUNCE    # cannot be configured away

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

package domain
module Domain

# Prefer constraints the model CANNOT violate. Wherever a requirement can be
# moved out of the model's discretion, move it: the surface renders the
# disclosure, retrieval enforces the scope, the loop enforces the effect flag.
# This class is for what genuinely remains.
class OutputPolicy                   # policy
  attr_reader :prohibitions, :redaction, :disclosure
  fn evaluate(a: Answer) -> Allowed | Blocked(Prohibition)
  # A backstop, never the mechanism. Output checking catches obvious cases and
  # is easily evaded.

class Prohibition                    # value object
  attr_reader :id, :description, :detector
  # no individualised advice; no pricing commitments; no diagnosis. Stated in
  # instructions AND checked by the answer suite via must_not_contain.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

package domain
module Domain

class RetentionPolicy                # policy
  attr_reader :transcripts, :run_records, :artifacts, :review_records

  fn purge(principal_ref) -> PurgeReport
    # Deletion means: transcript, artifacts, generated files, AND the review
    # records that quoted them. Events are PSEUDONYMISED rather than deleted,
    # or adoption history vanishes.

# Transcripts are more sensitive than the corpus they read. A question reveals
# what someone does not know, what they are working on, and sometimes what they
# are worried about.

1
2
3
4
5
6
7
8
9

package ports
module Ports

# Satisfied by engine::Adapters::Base. Declared here so services depend on the
# port, not on the engine's adapter hierarchy.
interface ModelPort
  fn complete(messages:, tools:, emitter:) -> Adapters::Response
  fn model_version() -> ModelVersion       # explicit, never a floating alias
  fn health() -> HealthState

1
2
3
4
5
6
7
8
9

package ports
module Ports

interface EmbedderPort
  fn embed(texts: [Text]) -> [Vector]
  fn dimension() -> Int
  fn version() -> ModelVersion
# Changing version() invalidates the ENTIRE index. Pinned hard, changed almost
# never, and the swap is refused by SubsystemRegistry — see runtime/container.

1
2
3
4
5
6
7
8
9

package ports
module Ports

interface VectorStorePort
  fn upsert(index: IndexId, chunks: [Chunk]) -> void
  fn knn(index:, vector:, predicate: Predicate, k: Int) -> [ScoredChunk]
  fn delete(index:, document_id:) -> void
  fn alias(name: AliasName) -> IndexAlias
# predicate is passed INTO knn, never applied to its results.

1
2
3
4
5
6
7
8

package ports
module Ports

interface KeywordSearchPort
  fn search(query: Text, predicate: Predicate, k: Int) -> [ScoredChunk]
# Hybrid retrieval needs both. The two fail differently: vector search misses
# an exact docket number, keyword search misses "what if I leave mid-year".
# A system with only one fails in a way its own metrics will not show.

1
2
3
4
5
6
7

package ports
module Ports

interface DocumentStorePort
  fn put(tenant:, document:) -> Ref
  fn get(ref:, scope: Scope) -> Result<Document>
  fn delete(ref:) -> void

1
2
3
4
5
6
7
8
9
10

package ports
module Ports

interface TranscriptStorePort
  fn append(run: RunRef, step: Step) -> void
  fn seal(run: RunRef, outcome:) -> void
  fn read(run: RunRef, by: Principal, reason: HumanText) -> Result<RunRecord>
    # reason is REQUIRED and is itself recorded. Transcript access is
    # privileged even for platform staff.
  fn purge(principal_ref) -> PurgeReport

1
2
3
4
5
6
7

package ports
module Ports

interface RerankerPort
  fn rank(chunks: [Chunk], question: Text) -> [ScoredChunk]
# The highest quality-per-cost step available, and the easiest to skip because
# retrieval "works" without it. Overfetch wide, rerank narrow.

1
2
3
4
5
6
7
8
9

package ports
module Ports

interface RendererPort
  fn render(request: ArtifactRequest) -> Result<ArtifactRef>
  fn inspect(ref: ArtifactRef) -> LayoutReport
# inspect exists because a model cannot see its own layout. Without a
# measurement pass it cannot know a table overflowed or a legend collided.
# compose -> inspect -> revise is a loop, not a single shot.

1
2
3
4
5
6
7
8
9
10
11

package ports
module Ports

interface QueuePort
  fn enqueue(job: Job, lane: Lane) -> JobRef
  fn dequeue(lane: Lane) -> Job?
  fn checkpoint(job:, cursor:) -> void
enum Lane { CONVERSATIONAL, AMBIENT, INDEXING, RENDERING, MACHINE }
# Separate lanes are the mechanism behind "a reindex cannot slow a
# conversation". Bundling indexing with the request path makes quality appear
# to collapse at exactly the moment the corpus improves.

1
2
3
4
5
6
7
8

package ports
module Ports

interface TelemetryPort
  fn metric(name:, value:, dimensions: Map) -> void
  fn attribute_cost(usage: Usage, tenant:, principal:, task_class:) -> void
# NEVER accepts question or answer text. Content stays in the run record,
# behind the controls the run record has.

1
2
3
4
5
6
7
8
9
10
11
12

package ports
module Ports

interface ConnectorPort
  fn enumerate(cursor: Cursor) -> Page<SourceDocument>
  fn changes() -> Stream<ChangeEvent>
  fn map_permissions(acl: SourceAcl) -> Predicate | UNMAPPABLE
  fn extract(doc: SourceDocument) -> ExtractedDocument
  fn signal_deletion() -> Stream<SourceId>
  fn freshness() -> FreshnessCharacteristic
# THE HIGHEST-STAKES PORT. map_permissions decides who may see what. See
# adapters/connector/* and the connector guide.

1
2
3
4
5
6
7

package ports
module Ports

interface ClockPort
  fn now() -> Timestamp
# Injected rather than called statically, so proposal expiry, throttle windows
# and budget windows are testable without sleeping.

1
2
3
4
5
6
7
8

package ports
module Ports

interface SecretsPort
  fn fetch(ref: SecretRef) -> Secret
  fn rotate(ref: SecretRef, value: Secret) -> void
# There is no read-back. An admin field shows whether a secret is set and when
# it was rotated, and accepts a replacement. No reveal, for anyone.

1
2
3
4
5
6
7
8

package adapters
module Adapters

class OpenAIEmbedderAdapter implements EmbedderPort
  fn initialize(model:, api: HttpClient)
  fn embed(texts) -> [Vector]        # batched; retries with jitter
  fn dimension() -> Int
  fn version() -> ModelVersion       # recorded on every chunk written

1
2
3
4
5
6
7
8
9
10
11
12
13

package adapters
module Adapters

class PgVectorStoreAdapter implements VectorStorePort
  fn knn(index:, vector:, predicate:, k:) -> [ScoredChunk]
    SELECT id, text, 1 - (embedding <=> :vector) AS score
      FROM chunks
     WHERE index_id = :index
       AND <predicate compiled to SQL>          -- INSIDE the query
     ORDER BY embedding <=> :vector
     LIMIT :k
  fn upsert(index:, chunks:) -> void
  fn alias(name:) -> IndexAlias      # a row, so cutover is an UPDATE

1
2
3
4
5
6
7
8
9
10

package adapters
module Adapters

class ElasticsearchStoreAdapter implements VectorStorePort, KeywordSearchPort
  fn knn(index:, vector:, predicate:, k:) -> [ScoredChunk]
    { knn: { field: "embedding", query_vector:, k:, filter: predicate } }
  fn search(query:, predicate:, k:) -> [ScoredChunk]
    { query: { bool: { must: match(query), filter: predicate } } }
# Satisfies both ports, which is legitimate: one technology, two capabilities.
# The container still binds them separately, so either can be swapped alone.

1
2
3
4
5
6

package adapters
module Adapters

class MemoryStoreAdapter implements VectorStorePort
  # Exact brute-force knn over an array. Deterministic, no service required,
  # and fast enough for a fixture corpus.

1
2
3
4
5
6
7

package adapters
module Adapters

class PostgresFtsAdapter implements KeywordSearchPort
  fn search(query:, predicate:, k:) -> [ScoredChunk]
    WHERE tsv @@ plainto_tsquery(:query) AND <predicate>
    ORDER BY ts_rank(tsv, ...) DESC

1
2
3
4
5
6
7
8

package adapters
module Adapters

class CrossEncoderRerankerAdapter implements RerankerPort
  fn rank(chunks, question) -> [ScoredChunk]
    # Scores each (question, chunk) pair directly rather than comparing
    # independent embeddings. Slow per pair, so it runs on the overfetched
    # shortlist only — never on the corpus.

1
2
3
4
5
6
7
8
9
10
11
12
13

package adapters
module Adapters

class HeadlessBrowserRendererAdapter implements RendererPort
  fn render(request) -> Result<ArtifactRef>
    html = compose(request.plan, request.brand)
    # Set the document content DIRECTLY over the debug protocol rather than
    # writing a temp file: a sandboxed browser may not share the host
    # filesystem, and the failure looks like a rendering timeout.
    page.set_document_content(html)
    page.print_to_pdf(...)
  fn inspect(ref) -> LayoutReport
    # measures overflow, collision, page count IN THE RENDERED OUTPUT

1
2
3
4
5
6
7
8
9

package adapters
module Adapters

class OoxmlRendererAdapter implements RendererPort
  fn render(request) -> Result<ArtifactRef>
    # Presentation parts, one embedded workbook per chart, notes slides.
    # Every relationship id must resolve, and every notes slide must have a
    # matching placeholder in the notes master or the client silently drops
    # the notes and reports the file as damaged.

1
2
3
4
5
6
7
8
9

package adapters
module Adapters

class DatabaseQueueAdapter implements QueuePort
  # Rows with a lane column and a lease. Survives a restart, gives an audit
  # trail for free, and needs no extra infrastructure — the right default until
  # throughput says otherwise.
  fn enqueue(job, lane) -> JobRef
  fn dequeue(lane) -> Job?           # SELECT ... FOR UPDATE SKIP LOCKED

1
2
3
4
5
6

package adapters
module Adapters

class SqsQueueAdapter implements QueuePort
  # One queue per lane, so lane isolation is enforced by the broker rather than
  # by a WHERE clause.

1
2
3
4
5
6
7
8

package adapters
module Adapters

class OpenTelemetryAdapter implements TelemetryPort
  fn metric(name, value, dimensions) -> void
  fn attribute_cost(usage, tenant:, principal:, task_class:) -> void
  private fn assert_no_content!(dimensions)
    raise if any dimension value looks like free text

1
2
3
4
5
6
7
8

package adapters
module Adapters

class FilesystemConnectorAdapter implements ConnectorPort
  fn map_permissions(acl) -> Predicate | UNMAPPABLE
    # POSIX modes map cleanly only when directories mirror groups. Where they
    # do not, return UNMAPPABLE and index nothing.
  fn signal_deletion() -> Stream<SourceId>   # watch, or diff the enumeration

1
2
3
4
5
6
7
8
9
10
11

package adapters
module Adapters

class WikiConnectorAdapter implements ConnectorPort
  fn map_permissions(acl) -> Predicate | UNMAPPABLE
    # Space permissions, page restrictions, and inherited defaults. Page
    # restrictions are usually DENY rules; dropping them because they are
    # awkward inverts the intent of the entire mapping.
  fn on_move(event) -> void
    # RE-EVALUATE the predicate. A page that moves into a restricted space and
    # keeps its old predicate is now readable by the wrong people.

1
2
3
4
5
6
7
8

package adapters
module Adapters

class TicketingConnectorAdapter implements ConnectorPort
  fn map_permissions(acl) -> Predicate | UNMAPPABLE
    # Project role plus per-issue security level. Comments frequently carry a
    # narrower level than the issue; a mapping that indexes the issue's level
    # exposes the comments.

1
2
3
4
5
6
7
8
9
10

package services
module Services

# Application services orchestrate. They hold collaborators, not request state,
# so one instance serves many turns and every dependency is visible in the
# constructor rather than reached for.
abstract class Base
  fn initialize(**dependencies)      # injected by runtime/container
  protected fn telemetry() -> TelemetryPort
  protected fn clock() -> ClockPort

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

package services
module Services

# The layer your application actually calls. Composes domain decisions with the
# engine, and is the only place that knows all three.
class TurnService < Base
  fn initialize(scope_policy:, composer:, profiles:, model_port:,
                channel:, grounding:, recorder:, budget:)

  fn execute(request: TurnRequest, principal: Principal) -> RunOutcome
    record  = recorder.open(request, principal)

    scope   = scope_policy.resolve(principal, request)   else return refuse
    tools   = composer.compose(principal, ctx)           # FROM GRANTS ALONE
    profile = profiles.elected(principal.tenant_id, request.surface)
    budget.enforce(principal, estimate(request))         else return refuse

    assistant = Engine::Assistant.new(
      adapter:      model_port.for(profile.routing, CONVERSATIONAL),
      tools:        tools,
      instructions: assemble(profile, scope, request),
      emitter:      request.emitter)

    outcome = assistant.run(auto_tool_execution: true, bounds: profile.bounds)
    outcome = grounding.verify(outcome, run: record.ref)
    recorder.seal(record, outcome)
    outcome

  # Assembly order is INTERNAL, and written down because getting it wrong is a
  # safety bug: platform instructions, tenant instructions, vocabulary, tool
  # descriptions, history, retrieved passages LABELLED AS CONTENT, subject
  # record, user message, then SAFETY CONSTRAINTS LAST so nothing displaces them.
  private fn assemble(profile, scope, request) -> ModelFacingText

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

package services
module Services

class RetrievalService < Base
  fn initialize(vector_store:, keyword_search:, embedder:, reranker:, issuer:)

  fn retrieve(request: RetrievalRequest) -> RetrievalResult
    ensure request.scope.tenant_id.present?        # fails CLOSED
    predicate = request.scope.predicate
    lexical   = keyword_search.search(request.question, predicate, OVERFETCH)
    semantic  = vector_store.knn(embedder.embed(request.question),
                                 predicate, OVERFETCH)
    fused     = ReciprocalRankFusion.fuse(lexical, semantic)
    ranked    = reranker.rank(fused, request.question)
    chosen    = diversify(ranked, max_per_document: 3).take(request.k)
    handles   = chosen.map { |c| issuer.issue(c, request.run) }

    telemetry.metric("retrieval.empty", chosen.empty?, dims)
    RetrievalResult.new(chosen, handles, decision, empty: chosen.empty?)

  # A top-k full of near-identical chunks from one document answers narrowly
  # and confidently, which is worse than answering broadly and hedging.
  private fn diversify(chunks, max_per_document:) -> [ScoredChunk]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

package services
module Services

class GroundingService < Base
  fn verify(outcome: RunOutcome, run: RunRef) -> RunOutcome
    for citation in outcome.citations:
      if issuer.resolve(citation.handle, run) == UNISSUED:
         strip(citation); telemetry.metric("citation.fabricated", 1, dims)
    outcome.with(citations: surviving)

  # Where a system scrapes links out of generated prose as a fallback, it
  # PROMOTES anything URL-shaped to the status of a source, and fires exactly
  # when the structured path failed — which is when output is least
  # trustworthy. Intersect with what retrieval actually returned this run:
  fn reconcile_scraped(urls: [Url], run: RunRef) -> [Citation]
    urls.select { |u| assistant.retrieved_urls.include?(canonical(u)) }

  # THE RUNG THAT MUST NEVER BE IMPROVISED.
  fn on_empty_retrieval(ctx) -> Refusal
    # A model asked a grounded question with no passages answers anyway,
    # fluently, from parametric memory. Closed in CODE — an instruction is
    # advisory, and this is the most common route to a confident fabrication.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

package services
module Services

class IndexingService < Base
  fn ingest(connector: ConnectorPort, cursor: Cursor) -> Progress
    for page in connector.enumerate(cursor):
      for doc in page:
        predicate = connector.map_permissions(doc.acl)
        next skip(doc, UNMAPPABLE) if predicate == UNMAPPABLE
        #    ^ INDEX NOTHING when the mapping is uncertain. The cost is a gap
        #      someone reports. The alternative is a synthesised answer built
        #      from something the reader was never entitled to see — which
        #      nobody reports, because it looks like the product working.
        chunks = corpus.chunk_policy.chunk(connector.extract(doc))
        vector_store.upsert(alias, chunks.with(predicate))
      queue.checkpoint(page.cursor)

  fn on_change(event) -> void
    case event when MOVED then reingest(event)   # RE-EVALUATE inherited perms
                when DELETED then vector_store.delete(...)   # incident priority
                when ACL_CHANGED then remap_predicate(...)   # no re-embed

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

package services
module Services

class RebuildService < Base
  fn rebuild(corpus: CorpusId, spec: IndexSpec) -> RebuildHandle
    shadow = vector_store.create(spec)
    alias.dual_write = shadow        # FROM NOW, not from completion, or the
                                     # new index is stale before it is ready
    queue.enqueue(FullReingest(corpus, into: shadow), lane: INDEXING)
    RebuildHandle.new(shadow, progress:, projected:, cost_accrued:)

  fn cutover(h: RebuildHandle) -> Cutover | Blocked
    before = RetrievalSuite.run(frozen_slice, alias.points)
    after  = RetrievalSuite.run(frozen_slice, h.shadow)
    return Blocked(comparison) if after.recall < before.recall - TOLERANCE
    alias.points = h.shadow          # a pointer move
    retain(previous, until: next_evaluation_cycle)

1
2
3
4
5
6
7
8
9
10
11
12
13
14

package services
module Services

class ArtifactService < Base
  fn request(r: ArtifactRequest, ctx) -> Result<ArtifactRef>
    validate(r.plan)
    ensure every transcribed figure has a resolvable citation handle
    #      ^ a figure with no provenance is NOT rendered. Reports that quietly
    #        restate numbers with no origin are how a model's arithmetic
    #        becomes someone's board slide.
    queue.enqueue(RenderJob(r), lane: RENDERING)

  # compose -> inspect -> revise. The model cannot see its own layout.
  fn inspect(ref) -> LayoutReport

1
2
3
4
5
6
7
8
9
10
11

package services
module Services

class ProposalService < Base
  fn accept(id: ProposalId, by: Principal) -> Result
    p = store.fetch(id)
    ensure by.id == p.proposed_to.id      # the person who SAW it
    ensure clock.now < p.expires_at
    ensure by.has_grant?(p.tool.grant)    # re-checked AT EXECUTION
    result = p.tool.new(context:, channel:).call(p.arguments)
    recorder.append(Confirmation(ACCEPTED)); result

1
2
3
4
5
6
7
8
9

package services
module Services

class VocabularyService < Base
  fn resolve(vocabulary_id:, spoken: Text) -> Term | Ambiguous | Unknown
  fn expand(term:, bucket:) -> [String]
  fn prompt_fragment(ids: [VocabularyId]) -> ModelFacingText
  # Injected into instructions so the model learns which words exist — never
  # what they expand to.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package services
module Services

class AmbientService < Base
  fn on_trigger(t: Trigger, subject: SubjectRef, p: Principal) -> Scheduled | Suppressed
    return Suppressed(DEBOUNCE) unless throttle.admits?(subject, p)
    return Cached(cache.get(fp)) if cache.has?(fp = fingerprint(subject))
    queue.enqueue(SuggestionJob(subject, p), lane: AMBIENT)

  fn run(job) -> [Suggestion]
    scope = scope_policy.resolve(job.principal, ...)   # THE VIEWER'S scope,
                                                       # not the record owner's
    producer.produce(job.subject, scope) using routing(AMBIENT)
    # AMBIENT class: fast and cheap. Nobody notices in an inline suggestion,
    # and it is the difference between a rounding error and broken economics.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

package surfaces
module Surfaces

# What a channel must provide to BE a surface. A channel that can neither show
# provenance nor obtain confirmation is not a surface — it is a notification
# target.
abstract class Base
  class_attribute :capabilities  SurfaceCapabilities

  abstract fn deliver(turn: Turn, envelope: Envelope) -> DeliveryOutcome
  abstract fn render_provenance(citations: [Citation]) -> void   # REQUIRED
  abstract fn render_generated_label() -> void                   # REQUIRED
  fn stream(delta: Delta) -> void | DECLINED
  fn confirm(p: Proposal) -> ACCEPTED | DECLINED | UNSUPPORTED

  fn self.inherited(subclass) -> void
    raise DefinitionError unless subclass implements render_provenance
    subclass.read_only! unless subclass.capabilities.confirmation_ui
    # A READ_ONLY surface has MUTATE tools dropped at composition. Voice
    # forces this honestly: spoken attribution and an explicit spoken
    # confirmation step, or run read-only. Both are legitimate; silently
    # dropping the affordances is not.

class SurfaceCapabilities            # value object
  attr_reader :streaming, :rich_artifacts, :inline_suggestion,
              :attachments, :confirmation_ui, :max_output_length

1
2
3
4
5
6
7
8
9
10

package surfaces
module Surfaces

class ChatSurface < Base
  capabilities streaming: true, rich_artifacts: true, confirmation_ui: true

  fn deliver(turn, envelope) -> DeliveryOutcome
    broadcaster.publish(envelope)
  fn render_provenance(citations) -> void
  fn render_generated_label() -> void

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

package surfaces
module Surfaces

# Reads records its user did not write and fires without anyone asking. The
# highest-risk input path, and the cost line that scales with activity you do
# not control.
class AmbientSurface < Base
  capabilities inline_suggestion: true, confirmation_ui: false   # READ_ONLY

  class_attribute :trigger    OnOpen | OnIdle | OnDemand | OnTransition
  class_attribute :throttle   ThrottlePolicy

  abstract fn produce(subject: Subject, scope: Scope) -> [Suggestion] | NOTHING
  fn apply(s: Suggestion, subject) -> Proposal    # still a MUTATE

  # Instrument all four or adoption is unmeasurable and the cost unjustifiable.
  enum Event { VIEWED, INTERACTED, APPLIED, DISMISSED }
  # Leaving out INTERACTED badly undercounts anything reloaded more often than
  # it is first opened.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

package surfaces
module Surfaces

# The assistant as a callable service for other software.
class MachineSurface < Base
  capabilities streaming: true, confirmation_ui: false

  fn expose(credential: Credential, tools: [ToolName]) -> void
    reject tools where effect == MUTATE unless credential.grants.machine_mutate?
    # Nobody is present to confirm. Enabling mutations needs an explicit grant
    # plus an out-of-band approval path, and that obstacle is deliberate.
    @descriptions = tools.map { |t| t.definition.for_external_caller(ctx) }

  fn handle(call: MachineCall) -> StructuredResult | Error
    # EACH CALL IS INDEPENDENT. No conversation is retained between calls; the
    # caller holds continuity and hands back what matters. Say this in the
    # interface docs AND in every tool description — callers assume otherwise
    # and the resulting behaviour looks like memory loss.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

package surfaces
module Surfaces

class SurfaceMount
  fn self.mount(target: HostElement, config: SurfaceConfig) -> SurfaceHandle
    reject if config.responds_to?(:grants)      # the host supplies IDENTITY,
    reject if config.responds_to?(:scope)       # never AUTHORITY. This
    reject if config.responds_to?(:tools)       # rejection is the entire
                                                # security model of embedding
    reject if config.subject.is_a?(RecordBody)  # references, not contents
    principal = PrincipalResolver.resolve(config.principal_token)

class SurfaceConfig                  # DTO
  attr_reader :surface_id, :principal_token, :subject_ref, :brand, :placement
class SurfaceHandle
  fn open(); fn close(); fn set_context(ref); fn on(event, &block)

1
2
3
4
5
6
7
8
9
10
11
12
13
14

package surfaces
module Surfaces

class SubjectRef                     # value object
  attr_reader :kind, :id, :tenant_id
  # A host handing over the record BODY is asserting the person may see it. A
  # host handing over an identifier lets the platform CHECK. The second costs a
  # lookup and removes a class of cross-user disclosure that is otherwise
  # undetectable from inside the platform.

class VisibleContext                 # value object
  attr_reader :items, :removable
  # What the assistant can currently see, shown and removable. The absence of
  # this is the top cause of "why didn't it know that".

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

package surfaces
module Surfaces

class Renderer
  fn render_answer(a: Answer, opts) -> Rendered
    body      = markdown(a.text)
    body      = swap_markers(body, reference_store)   # [[CHART:c3]] -> widget
    citations = render_citations(a.citations)         # NOT optional
    freshness = render_freshness(a.indexed_through)   # NOT optional
    label     = render_generated_label()              # NOT optional
    compose(body, citations, freshness, label)

# Themeable: colour, type, radius, density, iconography, placement, naming.
# NOT themeable: the generated-content label, provenance, the confirmation
# step, freshness. Rendered HERE precisely so no tool, extension or injected
# instruction can omit them.
class BrandTokens                    # value object

1
2
3
4
5
6
7

package surfaces
module Surfaces

class Delta                          # DTO
  variants: Token | Phase | Marker | Proposal | Citation | Done | Failed
# Phase deltas exist because perceived latency is dominated by whether anything
# is happening on screen: "searching the handbook", "checking request 4471".

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

package admin
module Admin

# The console is built on this and nothing else. No private back door: the
# moment the console reaches past the SDK, the SDK stops being sufficient and
# nobody notices until a partner tries the same screen.
abstract class ViewBase
  class_attribute :title, :section, :grant
  class_attribute :resource  ResourceBinding
  class_attribute :audit     AuditPolicy       # REQUIRED

  class fn columns(&block); class fn fields(&block); class fn actions(&block)

  fn self.inherited(subclass)
    raise DefinitionError if subclass.audit.nil?
    raise DefinitionError unless GrantCatalogue.known?(subclass.grant)
    raise DefinitionError if subclass.actions.any? { |x|
      x.effect != READ and not subclass.audit.covers?(x) }

1
2
3
4
5
6
7
8
9
10
11

package admin
module Admin

class ResourceBinding
  attr_reader :kind
  attr_reader :scope   TENANT | PLATFORM
  fn list(query:, scope: Scope) -> Page<Record>
  fn fetch(id:, scope: Scope) -> Result<Record>
  fn write(change:, scope: Scope) -> Applied | Rejected
# PLATFORM-scoped views are filtered OUT of a tenant session entirely — absent
# from the resolved view set, not hidden in the UI.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

package admin
module Admin

class Field                          # definition object
  attr_reader :name, :label, :type, :help, :required, :redaction, :validator
  # label is written from the ADMINISTRATOR's side of the screen:
  # "Notifications", not "webhook config".

enum FieldType { TEXT, LONGTEXT, NUMBER, BOOL, ENUM, DURATION, MONEY,
                 REFERENCE, SECRET, VOCABULARY, CODE }
enum Redaction { NONE, MASKED, WRITE_ONLY }

class SecretField < Field
  redaction WRITE_ONLY
  fn render(record) -> "Set — last rotated {t}" | "Not set"
  # There is no reveal. Not as a permission, not for operators.

1
2
3
4
5

package admin
module Admin

class Column                         # definition object
  attr_reader :field, :label, :sortable, :formatter, :width

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

package admin
module Admin

class Action                         # definition object
  attr_reader :id, :label, :effect, :grant, :confirm, :handler
  # label says exactly what happens: "Publish". Then a toast that says
  # "Published".

class ConfirmPolicy                  # policy
  variants: None | Simple(prompt) | Typed(must_type) | SecondParty(grant)

fn validate(a: Action)
  raise DefinitionError if a.effect == DESTRUCTIVE and
                           a.confirm not in [Typed, SecondParty]
  # Standing configuration — subscriptions, forwarding rules, integrations —
  # defaults to SecondParty: the damage from one is silent and long-lived.

1
2
3
4
5
6
7
8
9
10
11
12

package admin
module Admin

class AuditPolicy                    # policy
  attr_reader :record ALL_WRITES|ALL_ACCESS, :retain, :diff, :reversible
class AuditEntry                     # record
  attr_reader :at, :actor, :tenant_id, :view, :action, :target,
              :before, :after, :reversal_ref

fn access_transcript(ref:, by:, reason: HumanText) -> Result<RunRecord>
  ensure reason.present?             # required, and itself recorded
# Transcript access is privileged even for platform staff.

1
2
3
4
5
6
7
8
9
10
11
12

package admin
module Admin

class Console
  fn self.mount(target:, config: ConsoleConfig) -> ConsoleHandle
    reject if config.responds_to?(:grants)          # same rule as SurfaceMount
    views = config.views.select { |v| v.resource.scope == TENANT }

  fn self.mount_operator(target:, config: OperatorConfig) -> ConsoleHandle
    # A SEPARATE mount with PLATFORM scope and its own grants. Sharing one
    # console between operators and tenants is how a cross-tenant view
    # eventually ships — and it ships looking like a permissions bug.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

package admin
module Admin

# Conventional service telemetry answers none of the questions anyone has.
enum Dashboard { HEALTH, QUALITY, COST, ADOPTION }
#   HEALTH    provider error rate and FALLBACK FREQUENCY, not just own 5xx
#   QUALITY   EMPTY-RETRIEVAL RATE, refusal rate, citation-strip, corrections
#   COST      per-tenant outliers, and the AMBIENT SHARE of total
#   ADOPTION  RETURNING USERS, not total turns

class Panel                          # definition object
  attr_reader :metric, :breakdown, :alert

fn empty_retrieval_rate(window, dims) -> Series
# If exactly one metric gets an alert, this one: it rises before complaints,
# has an unambiguous cause, and separates a corpus problem from a model
# problem with no labelling work at all.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

package admin
module Admin

class ProfileView < ViewBase
  title    "Assistants"
  section  NAV.configuration
  grant    :profiles_manage
  resource ResourceBinding.new(kind: :profile, scope: TENANT)
  audit    AuditPolicy.new(record: ALL_WRITES, diff: true, reversible: true)

  columns { column :name; column :current_version; column :updated_at }
  fields  { field :name, TEXT
            field :instructions, CODE(markdown), help: "Versioned; electing
                  runs the change gate"
            field :routing, REFERENCE(:routing_policy) }
  actions { action :elect,    effect: WRITE, confirm: Simple("Elect this version?")
            action :rollback, effect: WRITE, confirm: Simple("Roll back?") }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

package admin
module Admin

# The screen every incident starts on.
class RunInspectorView < ViewBase
  grant :runs_inspect
  audit AuditPolicy.new(record: ALL_ACCESS, retain: 2.years)

  # Answers three questions without anyone opening a log:
  #   was this tool even OFFERED to that person?   -> registry_snapshot
  #   did retrieval return nothing, or the wrong thing?  -> decisions
  #   which instruction version produced this?     -> profile_version + diff
  fn render(run: RunRecord) -> Rendered
    timeline(run.steps); offered(run.registry_snapshot)
    retrieval(run.decisions, showing what was CUT and why)
    citations(issued vs rendered vs STRIPPED); usage(by task class)

1
2
3
4
5
6
7
8
9
10

package evaluation
module Evaluation

class Case                           # value object
  attr_reader :id, :question, :context, :scope_fixture
  attr_reader :must_retrieve  [DocumentId]     # scored with NO model call
  attr_reader :must_contain, :must_not_contain
  attr_reader :expect_refusal Bool
  attr_reader :stratum, :notes
# scope_fixture matters: WHICH principal is asking changes the right answer.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

package evaluation
module Evaluation

class CaseSet
  enum Stratum { COMMON, LONG_TAIL, MULTI_STEP, UNANSWERABLE, ADVERSARIAL, AMBIGUOUS }
  # target shares: 35 / 20 / 15 / 15 / 10 / 5

  fn validate() -> Result
    ensure share(UNANSWERABLE) > 0.10
    # Without a refusal stratum a set REWARDS confident fabrication and calls
    # it accuracy.
    ensure every case has a scope_fixture
    warn if median_age > 6.months     # sets rot as the corpus moves

  fn freeze_slice(n: Int) -> FrozenSlice
    # Never updated. The baseline that makes "did this change help" answerable
    # across a year of corpus drift.

1
2
3
4
5
6
7
8
9
10

package evaluation
module Evaluation

abstract class SuiteBase
  abstract fn run(cases: CaseSet, target) -> SuiteResult
  fn with_variance(samples: Int, &block) -> ScoreWithVariance
    # Run each case more than once. A single-sample score on a stochastic
    # system is a number with no error bar, and every comparison built on it
    # is noise.
  fn report() -> SuiteResult    # ALWAYS per stratum, never one aggregate

1
2
3
4
5
6
7
8
9
10
11
12
13

package evaluation
module Evaluation

class RetrievalSuite < SuiteBase
  # Separable from everything else, which is what makes it the right FIRST
  # thing to build: no model call, no judging, no labelling beyond marking
  # which documents should have come back.
  fn run(cases, index) -> RetrievalReport
class RetrievalReport
  attr_reader :recall_at_k, :precision_at_k, :mrr, :empty_rate, :per_stratum
  attr_reader :scope_violations   # MUST BE ZERO
  # Not a quality metric. One is a disclosure bug, and the run fails
  # regardless of every other number.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package evaluation
module Evaluation

class SelectionSuite < SuiteBase
  fn run(cases, registry: RegistrySnapshot) -> SelectionReport
    ensure cases.negatives.any?      # a probe with only positives measures
                                     # nothing: an always-selected tool passes
    ensure registry.entries.size > 1 # ambiguity between NEIGHBOURS is the
                                     # actual failure
class SelectionReport
  attr_reader :correct_selection, :spurious_call, :missed_call
  attr_reader :wrong_neighbour  Map<Pair<Name,Name>, Int>
  attr_reader :parameter_accuracy
  # wrong_neighbour is the actionable output: it names the two descriptions
  # that need telling apart, which is a five-minute fix once you know the pair.

1
2
3
4
5
6
7
8
9

package evaluation
module Evaluation

class AnswerSuite < SuiteBase
  fn run(cases, profile_version) -> AnswerReport
class AnswerReport
  attr_reader :grounded, :correct, :refused_when_right, :citation_valid
  attr_reader :over_refused        # THE FAILURE THAT ENDS PILOTS QUIETLY
  attr_reader :variance            # report it or the exercise is theatre

1
2
3
4
5
6
7
8
9
10

package evaluation
module Evaluation

class Judge
  # 1  a DIFFERENT model from the one under test
  # 2  sees the retrieved passages, not just the answer
  # 3  scores ONE property per call — grounded, or correct, never both
  # 4  rubrics are written down and versioned like any other prompt
  # 5  a sample of judgements is checked by a person, every cycle
  fn score(answer:, case:, rubric: Rubric) -> Score

1
2
3
4
5
6
7
8
9
10
11
12
13
14

package evaluation
module Evaluation

class AdversarialSuite < SuiteBase
  # Scores CONTAINMENT, not answer quality. Never "was the answer good" but
  # "did anything escape".
  fn run(cases, config) -> AdversarialReport
    corpus = plant_payloads(corpus_fixture, payloads)
    # CORPUS injection, not just question injection. Passage-borne injection
    # is the realistic vector; testing only the question misses it entirely.
class AdversarialReport
  attr_reader :tool_outside_registry     # MUST be 0
  attr_reader :mutation_without_confirm  # MUST be 0 — if nonzero, THE defect
  attr_reader :restricted_content, :scope_widened   # MUST be 0

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

package evaluation
module Evaluation

class ChangeGate
  enum ChangeKind { EMBEDDING, CHUNKING, INSTRUCTION, DESCRIPTION, MODEL,
                    ROUTING, CORPUS, TOOL_CODE }
  # non-obvious couplings:
  #   chunking    -> index AND every retrieval baseline
  #   instruction -> ANSWER baselines, not retrieval ones
  #   description -> SELECTION baselines only
  #   model       -> everything, including refusal behaviour
  #   corpus growth -> retrieval precision, WITH NO DEPLOY

  fn evaluate(change) -> Verdict
class Verdict
  attr_reader :blocked, :comparison, :overridable_by  GrantKey
  # The gate must be able to say NO. A gate that only advises is a report.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package evaluation
module Evaluation

class ReviewSampler
  # Stratified, not random. Random sampling of a system that is right most of
  # the time spends nearly all the reviewer's attention confirming that.
  fn sample(window, policy) -> [RunRef]
class SamplePolicy
  attr_reader :refusals, :low_confidence, :corrections, :empty_retrieval, :random
  # refusals over-sampled: over-refusal is invisible otherwise

class ReviewRecord                   # record
  attr_reader :run_ref, :reviewer, :verdict, :notes, :became_case
  # THE POINT is became_case. A reviewed failure that does not enter the set
  # will recur after the next model change.

1
2
3
4
5
6
7
8
9

package testing
module Testing

class Harness
  fn self.build(**overrides) -> Harness
    # Every port bound to a double. Deterministic, no network, no database.
  fn turn(input: Text) -> RunRecord
  fn with_empty_retrieval() -> Harness
  fn with_injected_corpus(payload) -> Harness

1
2
3
4
5
6
7
8
9

package testing
module Testing

class RecordedModel     implements ModelPort        # replays a script
class MemoryVectorStore implements VectorStorePort  # brute-force knn
class HashEmbedder      implements EmbedderPort     # deterministic vectors
class FrozenClock       implements ClockPort
class CapturingChannel  < Channel::Adapters::NullAdapter
class NullTelemetry     implements TelemetryPort

1
2
3
4
5
6
7
8

package testing
module Testing

fn fake_principal(grants:, tenant:) -> Principal
fn fake_scope(principal:, corpora:) -> Scope
fn fake_registry(tools:) -> Tool::Registry
fn corpus_fixture(docs:, acls:) -> CorpusFixture   # carries ACLs, so
                                                   # permission mapping is testable

1
2
3
4
5
6
7
8
9
10
11
12
13
14

package testing
module Testing

fn assert_never_called(record, tool_name)
fn assert_proposed_not_executed(record, tool_name)
fn assert_no_scope_widening(record, baseline)
fn assert_refused(record, reason)
fn assert_no_content_in_telemetry(sink)

# The four tests every tool author should write, in the order they catch things:
#   turn("...")                      -> assert_never_called(:other_tool)
#   turn("...")                      -> assert_proposed_not_executed(:write_tool)
#   with_empty_retrieval.turn("...") -> assert_refused(NOTHING_FOUND)
#   with_injected_corpus(p).turn("") -> assert_no_scope_widening(base)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

package runtime
module Runtime

# THE ONLY place that knows which adapter satisfies which port. Everything else
# receives its collaborators. This file is where a self-hosted deployment
# differs from the managed one, and it is the whole of the difference.
class Container
  fn bind(port: PortClass, adapter: AdapterInstance, scope: PLATFORM|TENANT)
  fn resolve(port: PortClass, tenant: TenantId?) -> AdapterInstance
    tenant_binding(port, tenant) or platform_binding(port) or raise NotConfigured

  fn swap(port:, tenant:, to:) -> Swapped | RequiresRebuild
    if port in [EmbedderPort, VectorStorePort] and index_exists?(tenant)
      return RequiresRebuild(procedure: "services/rebuild_service")
    # Allowing this silently produces an index whose vectors were written by
    # one model and queried by another. It does not error — it just quietly
    # returns worse results, and no health check shows it.

  fn validate!() -> void
    ensure every Port has a binding
    ensure every adapter's config validates AT STARTUP, not at first use

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

package runtime
module Runtime

class Configuration
  # Precedence, highest first. Written down because every argument about
  # configuration is really an argument about this order.
  #   1  incident override   operator-set, time-boxed, audited, EXPIRES
  #   2  tenant setting      what an administrator chose
  #   3  profile setting     what this assistant needs
  #   4  platform default    what we think is right
  #   5  compiled default    what keeps it from crashing
  fn resolve(key, ctx) -> Value
  fn effective(tenant) -> Map<Key, ResolvedValue>
    # Returns the value AND the layer that supplied it. A console showing only
    # the value produces a support ticket every time someone edits the wrong
    # layer.
  fn override(key:, value:, ttl:, by:, reason:) -> Override
    ensure ttl <= MAX_OVERRIDE_TTL   # a permanent override is a config change
                                     # that skipped review, and it is forgotten

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

package runtime
module Runtime

class Bootstrap
  fn self.call(env: Environment) -> Container
    c = Container.new
    c.bind ModelPort,        OpenAIResponsesAdapter.new(...)
    c.bind EmbedderPort,     OpenAIEmbedderAdapter.new(...)
    c.bind VectorStorePort,  PgVectorStoreAdapter.new(...)
    c.bind KeywordSearchPort,PostgresFtsAdapter.new(...)
    c.bind RendererPort,     HeadlessBrowserRendererAdapter.new(...)
    c.bind QueuePort,        DatabaseQueueAdapter.new(...)
    c.bind TelemetryPort,    OpenTelemetryAdapter.new(...)
    Channel::Adapters::TurboStreamAdapter.register
    c.validate!
    c
# Self-hosted, hybrid and managed differ ONLY in this file's bindings. A
# topology that needs a different build is a second product, and it falls
# behind within two releases.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

package runtime
module Runtime

abstract class Middleware
  abstract fn call(request, next) -> Response

class AuthenticationMiddleware < Middleware   # resolves the Principal
class TenancyMiddleware        < Middleware   # resolves tenant, FAILS CLOSED
class AdmissionMiddleware      < Middleware   # sheds before the retry storm
class RateLimitMiddleware      < Middleware   # per principal AND per credential
class BudgetMiddleware         < Middleware   # reserve before work starts
class TelemetryMiddleware      < Middleware   # outermost, so it sees failures
class RunRecordMiddleware      < Middleware   # opens and seals the record

# Order matters and is asserted in a test: authentication before tenancy before
# admission. Admission that runs before authentication sheds by IP, which
# punishes shared egress.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

package platform
module Platform

# PRIVATE. Everything below this line trusts the principal is real and the
# tenant is resolved; nothing above it may assume so.
class EdgeService < Services::Base
  fn handle(req) -> Response
    principal = PrincipalResolver.resolve(req.token)  else 401
    ensure tenant_enabled?(principal.tenant_id)       else 403   # kill switch
    ensure not shedding?(principal, req.lane)         else 429
    pipeline.call(req)

  fn shedding?(p, lane) -> Bool
    return true if provider.saturation > SHED_THRESHOLD and lane != CONVERSATIONAL
    return true if lane_depth(lane) > max_depth(lane)
    rate_limiter.exceeded?(p)
  # Refuse AT THE EDGE. Queuing turns that will time out anyway converts a
  # degraded service into an unavailable one.

1
2
3
4
5
6
7
8
9
10
11
12
13

package platform
module Platform

class RateLimiter
  fn check(p: Principal) -> Allowed | Throttled
    # Volume alone is a poor extraction signal. BREADTH is better: a principal
    # touching an unusual number of DISTINCT documents is the shape of
    # systematic extraction, where volume alone is an enthusiastic user.
    flag(POSSIBLE_EXTRACTION, p) if distinct_documents(p, window) > ceiling
  fn limits_for(p) -> Limit
    p.machine? ? MACHINE_LIMITS : HUMAN_LIMITS
# The realistic cost incident is not an attacker. It is a well-meaning
# integration looping, an ambient surface firing on keystroke, or a team of 40.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

package platform
module Platform

class StreamService < Services::Base
  fn stream(req, principal) -> EventStream
    run = turn_service.execute_async(req, principal)
    emit Phase(RETRIEVING)          # something on screen immediately
    for delta in run.deltas: emit delta; run.detach if client.disconnected?
    emit Done(run.ref)
  fn resume(run_ref, principal) -> EventStream | Expired
    ensure owned_by?(run_ref, principal)
    replay(run_ref) then live(run_ref)
# A dropped connection must not lose what was typed or produced. The run
# completes server-side and is replayable by reference.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package platform
module Platform

class PackService < Services::Base
  fn install(pack, by) -> Result
    ensure pack.compatible.satisfied_by?(core_version)   # AT INSTALL
    # An extension loading against a core it was never tested on fails in the
    # least debuggable way available: intermittently, inside a model turn, with
    # a plausible answer covering for it.
    ensure reviewed?(pack)
  fn publish(pack) -> Available      # to tenants, active in NONE
  fn enable(pack, tenant, grants, by) -> Enabled     # reversible in ONE action
  fn disable(pack, tenant, by) -> Disabled
# Publish and enable are different events, or a marketplace update silently
# changes behaviour in production.

1
2
3
4
5
6
7
8
9

package platform
module Platform

class HealthMonitor
  fn probe(tool) -> HealthState
  # Hysteresis: a tool that appears and disappears between turns is worse than
  # one consistently absent, because the person cannot form a model of what
  # the assistant can do.
  attr_reader :failures_to_open, :successes_to_close, :min_open

1
2
3
4
5
6
7
8
9
10
11
12
13
14

package platform
module Platform

class TenantRepository
  fn create(spec) -> Tenant
    index = vector_store.create_partition(spec.id)   # NEVER a shared index
    # The storage saving from sharing is real and small. The failure mode is a
    # fabricated answer citing another organisation's document — not a bug
    # report, a breach notification. This cannot be revisited later.
  fn disable(tenant, by, reason) -> Disabled
    # THE KILL SWITCH — widest lever. No deploy, and exercised in a DRILL
    # before it is needed.
  fn allowed_providers(tenant) -> [ProviderId]   # residency is a HARD routing
                                                 # constraint outranking uptime

1
2
3
4
5
6
7
8
9
10
11
12
13
14

package platform
module Platform

class ExportService < Services::Base
  fn export(tenant, scope) -> ExportBundle
    { configuration, profiles WITH FULL VERSION HISTORY, grants,
      corpus_source_mappings, labelled_sets, review_records, vocabularies }
    # EXCLUDED by default: transcripts (privacy, explicit request only) and
    # derived indexes (rebuildable).
  fn import(bundle, into) -> Imported | Incompatible
    # Must import into ANY topology. An export that only restores into the same
    # deployment is a backup, not portability.
# Exportability is a continuity control AND a commercial one: a customer who
# CAN leave is a customer who will commit further.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package platform
module Platform

class SignalService < Services::Base
  enum Signal { EMPTY_RETRIEVAL_RATE, REFUSAL_RATE, CITATION_STRIP_RATE,
                FOLLOW_UP_IMMEDIACY, CONVERSATION_ABANDON, CORRECTION_RATE,
                SUGGESTION_APPLIED, RETURNING_USERS }
  # each lies in a specific way:
  #   ABANDON        satisfied-and-done looks identical to gave-up
  #   CORRECTION     honest but sparse; only motivated people submit
  #   RETURNING      THE adoption number. Turn volume can rise while the same
  #                  twelve people generate all of it
  fn compare_variants(a, b, signal) -> Comparison
    # Assistant experiments are slower than product experiments: smaller
    # effect, higher variance, self-selected heavy users. Budget more time.

1
2
3
4
5
6
7
8
9
10
11
12

package platform
module Platform

# PRIVATE deployment, built ENTIRELY on packages/admin. If the console can do
# it, an integrator can build it.
class ConsoleApp
  fn boot(session) -> ConsoleHandle
    Admin::Console.mount(root, ConsoleConfig.new(
      tenant: session.tenant, principal: session.token,
      views: [ProfileView, CorpusView, ToolView, GrantView,
              BudgetView, DashboardView, RunInspectorView]))
  fn boot_operator(session) -> ConsoleHandle   # PLATFORM scope, own grants

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

variable topology { SELF_HOSTED | HYBRID | MANAGED }

module data_plane    { present in ALL topologies; inside the customer boundary
                       for SELF_HOSTED and HYBRID }
module control_plane { count = topology == SELF_HOSTED ? 0 : 1 }
module model_route   { providers = allowed_providers(residency) }

output crosses_boundary = {
  corpus_at_rest     = topology == MANAGED
  transcripts        = topology == MANAGED
  labelled_sets      = topology == MANAGED ? true : "opt-in"
  # ^ THE ROW PEOPLE MISS. A golden set is built from real questions against
  #   real content, so it inherits the sensitivity of both. Classify it with
  #   the corpus, not with the configuration.
}

1
2
3
4
5
6
7

module request_path   { scales_with = "concurrent conversations" }
module index_pipeline { scales_with = "corpus CHURN"
                        isolation   = separate_node_pool }
module ambient        { scales_with = "editing activity"; ceiling = hard }
module render_workers { node_type = high_memory; isolation = sandboxed
                        filesystem = writable_scratch }
# Size independently or you over-provision one and starve another.

1
2
3
4
5
6
7
8
9

priorityClasses:
  conversational { value: 1000, preemption: never }
  machine        { value:  700 }
  ambient        { value:  400, preemptible: true }
  indexing       { value:  200, preemptible: true }
  rendering      { value:  200, preemptible: true, nodeSelector: high_memory }

# An indexer killed mid-page resumes from its checkpoint. A renderer killed
# mid-job loses the job, so it drains before upgrade.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

LEVEL 1  withdraw one tool       PackService.disable(pack, tenant)
LEVEL 2  roll back a profile     ProfileRepository.rollback(...)
LEVEL 3  disable a surface       requires surfaces independently switchable
LEVEL 4  disable a tenant        THE KILL SWITCH. No deploy. Drill it.

# If the only lever is the widest one, you do not have incident response — you
# have an off switch.

classification -> first response
  disclosure      retract from index at incident priority; audit who saw what.
                  Root cause is in the PREDICATE, not the model
  fabrication     CHECK RETRIEVAL BEFORE BLAMING THE MODEL. Usually an empty
                  result path with no refusal
  injection       withdraw the abused tool; verify invariants held. A mutation
                  executed unconfirmed IS the defect
  cost runaway    tenant budget cap. Nearly always a loop or an ambient
                  trigger, not an attack

# ALWAYS post-incident: add the case to the labelled set. An incident fixed but
# not encoded recurs after the next model change.

1
2
3
4
5
6
7
8
9
10
11

1  IS IT UP?         gateway 5xx, provider error rate, FALLBACK FREQUENCY
                     (fallback frequency is the one people forget: the service
                     looks healthy while quality has quietly dropped)
2  IS IT GOOD?       EMPTY-RETRIEVAL RATE first, then refusal, citation-strip
3  WHAT CHANGED?     elections, pack enablement, model version, CORPUS SIZE
                     (corpus growth changes precision with NO DEPLOY)
4  WHO IS AFFECTED?  per-tenant breakdown before touching anything
5  NARROWEST LEVER   start at LEVEL 1

# Do NOT start by rolling back the deploy. The most common cause of a quality
# complaint here is a change that was not a deploy at all.

1
2
3
4
5
6
7
8
9
10
11

REBUILDABLE       index (from corpus), aggregate telemetry, artifacts
NOT REBUILDABLE   configuration and profiles, transcripts and run records,
                  LABELLED SETS AND REVIEW RECORDS

# The last is the trap: it looks like test data, it is the most valuable thing
# the deployment accumulates, and losing it means every future change is argued
# rather than measured.

objectives   config restore: minutes | request path: <1h
             index: hours FROM SNAPSHOT (days if rebuilt — snapshot it)
drills       quarterly restore from export bundle; quarterly kill-switch

1
2
3
4
5

expand -> migrate -> contract, always. Never a destructive change in one
deploy, because rollback then means data loss rather than a redeploy.

NEVER run migrations automatically on boot. A replica starting during an
incident must not alter schema. Migrations are an explicit, gated step.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

package domain
module Domain

# Events about WHAT HAPPENED, never about what was said. Payloads carry handles
# and metadata; a subscriber entitled to the content fetches it under their own
# credentials. A payload full of answer text turns every subscriber endpoint
# into an unmanaged copy of the transcript store.
class Event                          # value object
  variants:
    ConversationStarted { tenant_id, surface_id, principal_ref }
    ConversationEnded   { tenant_id, run_ref, turn_count }
    MutationProposed    { tenant_id, run_ref, tool_name, proposal_id }
    MutationExecuted    { tenant_id, run_ref, tool_name, proposal_id }
    ArtifactProduced    { tenant_id, run_ref, artifact_ref, kind }
    CorrectionSubmitted { tenant_id, run_ref, review_ref }
    BudgetThreshold     { tenant_id, window, pct_of_limit }
    ToolFailed          { tenant_id, run_ref, tool_name, code }

  fn to_payload() -> Map
  fn idempotency_key() -> String     # subscribers MUST expect duplicates

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package ports
module Ports

interface EventSinkPort
  fn subscribe(tenant: TenantId, filter: EventFilter, endpoint: Endpoint) -> Subscription
  fn deliver(subscription: Subscription, event: Event) -> DeliveryOutcome
  fn unsubscribe(subscription: Subscription) -> void

# Delivery is AT LEAST ONCE, with an idempotency key per event, bounded retry
# and a dead-letter path.
#
# Creating a subscription is a STANDING, security-relevant configuration change:
# administrator-only, audited, visible in the console, defaulting to
# SecondParty confirmation — and never creatable by anything the model produced.
# The damage from a wrong subscription is silent and long-lived.