insika 0.2.0 → 0.7.0

data/lib/insika/wiring/graph.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "graph_chat"
+
 module Insika
   module Wiring
     # SHARED composition core for both roots: the minimal wiring
@@ -45,6 +47,10 @@ module Insika
         pending_action_store = Insika::PendingActionStore.new(store: backend)
         delegation_store     = Insika::DelegationStore.new(store: backend)
         memory_store         = Insika::MemoryStore.new(store: backend)
+        # the append-only, content-free audit of OPERATOR memory
+        # mutations. Built unconditionally (empty and free when nothing writes)
+        # so a deployment that turns it on later finds its audit already durable.
+        memory_audit_store  = Insika::MemoryAuditStore.new(store: backend)
         token_store          = Insika::TokenStore.new(store: backend)
         budget_ledger        = Insika::BudgetLedger.new(store: backend)
         circuit_state        = Insika::CircuitState.new(store: backend)
@@ -54,11 +60,56 @@ module Insika
         # (they are empty and free when no channel is registered) so a deployment
         # that turns a channel on later finds its state already durable.
         outbox_store         = Insika::OutboxStore.new(store: backend)
+        # the shadow pair store — one durable record per mirrored
+        # exchange, written by our half and the incumbent's. Built unconditionally
+        # (empty and free when shadow is off) so turning it on later finds the
+        # state already durable, beside the outbox on the same runtime backend.
+        shadow_pair_store    = Insika::ShadowPairStore.new(store: backend)
         inbound_log          = Insika::InboundLog.new(store: backend)
+        # WS7: business outcomes per conversation, recorded by the operator or
+        # the integration (POST /v1/outcomes). Built unconditionally (empty and
+        # free when nothing records) so the Studio's scorecard always has a store.
+        outcome_store        = Insika::OutcomeStore.new(store: backend)
+        # the funnel's durable aggregates — per-day stage counts,
+        # fold cursors and baseline snapshots. Built unconditionally (empty and
+        # free when no pack declares a funnel) so the fold, the doctor and the
+        # Studio always have a store to read/write.
+        funnel_store        = Insika::FunnelStore.new(store: backend)
+        # the contact-state cells and the follow-up schedule
+        # records. Built unconditionally (empty and free when no pack declares
+        # followup) so the engine, the tools and the Studio always have stores.
+        contact_store       = Insika::ContactStore.new(store: backend)
+        followup_store      = Insika::FollowupStore.new(store: backend)
+        # the recurring-schedule rows: one row per
+        # declared schedule, declaration + runtime state. Built unconditionally
+        # (empty and free when no pack declares schedules) so the engine, the
+        # doctor and the Studio always have a store.
+        schedule_store      = Insika::ScheduleStore.new(store: backend)
+        # the distilled proposals + the latched dedup ledger +
+        # the per-session markers. Built unconditionally (empty and free when
+        # no pack declares distill) so the wiki, the engine and the LGPD
+        # purges always have a store.
+        proposal_store      = Insika::ProposalStore.new(store: backend)
+        # concepts extracted from finished turns. Built
+        # unconditionally (empty and free when no pack declares knowledge)
+        # so the extractor, the Studio and the LGPD purges always have a
+        # store.
+        knowledge_store      = Insika::KnowledgeStore.new(store: backend)
         # refinement RUNS (reports over real traffic). Runtime data,
         # same backend as sessions/tasks — the collector and the command that write it
         # are the root's business (deployment-only, like the memory commands).
         refinement_store     = Insika::RefinementStore.new(store: backend)
+        # the harvest's durable half — mining runs, the per-
+        # candidate lifecycle, the append-only promotion log, the snapshots
+        # and the per-session markers. Built unconditionally (empty and free
+        # when no pack declares harvest) so the engine, the Studio and the
+        # LGPD purges always have a store.
+        harvest_store        = Insika::HarvestStore.new(store: backend)
+        # the report destination — one record per run, no
+        # versioning. Built unconditionally (empty and free when nothing saves)
+        # so the tool, the routes, the retention sweep and the tenant purge
+        # always have a store.
+        artifact_store       = Insika::ArtifactStore.new(store: backend)
 
         code_tool_registry = Insika::ToolRegistry.new
         workflow_registry  = Insika::WorkflowRegistry.new
@@ -74,9 +125,20 @@ module Insika
           session_store: session_store, task_store: task_store,
           checkpoint_store: checkpoint_store, pending_action_store: pending_action_store,
           delegation_store: delegation_store,
-          memory_store: memory_store, refinement_store: refinement_store,
+          memory_store: memory_store, memory_audit_store: memory_audit_store,
+          refinement_store: refinement_store,
+          harvest_store: harvest_store,
           token_store: token_store, budget_ledger: budget_ledger, circuit_state: circuit_state,
-          outbox_store: outbox_store, inbound_log: inbound_log,
+          outbox_store: outbox_store, shadow_pair_store: shadow_pair_store,
+          inbound_log: inbound_log,
+          outcome_store: outcome_store,
+          funnel_store: funnel_store,
+          contact_store: contact_store,
+          followup_store: followup_store,
+          schedule_store: schedule_store,
+          proposal_store: proposal_store,
+          knowledge_store: knowledge_store,
+          artifact_store: artifact_store,
           code_tool_registry: code_tool_registry,
           workflow_registry: workflow_registry, policy_registry: policy_registry,
           capability_registry: Insika::CapabilityRegistry.new, hooks: Insika::Hooks.new,
@@ -99,6 +161,13 @@ module Insika
       def build(spine:, profiles:, tool_registry:, tool_catalog:, skill_catalog:,
                 prompt_catalog:, guardrails:, context_providers:, edge_limiter: nil,
                 executor_extra: {})
+        # the save_artifact tool: a REGISTRY tool registered OPTIONAL (the
+        # per-agent allowlist is the switch — an agent that did not name it
+        # cannot call it). Registered in the shared code registry, so both
+        # roots (base registry + the deployment's overlay, which composes it)
+        # expose it. The gem's require lives IN the factory block (loaded on
+        # the 1st instance, turn time -> wiring-load stays gem-free).
+        register_artifact_tool(spine)
         spine.hooks.register(:task, after: guardrails.output_validator)
         middleware = Insika::MiddlewareStack.new([edge_limiter, guardrails.input_guardrail].compact)
 
@@ -115,7 +184,8 @@ module Insika
         # only production exercises.
         channel_delivery = Insika::ChannelDelivery.new(
           channels: spine.channel_registry, outbox: spine.outbox_store,
-          session_store: spine.session_store, event_stream: spine.event_stream
+          session_store: spine.session_store, event_stream: spine.event_stream,
+          shadow_pairs: spine.shadow_pair_store
         )
 
 # WS3 provider reliability (retries/backoff/fallback/breaker) is ALWAYS wired —
@@ -135,23 +205,132 @@ module Insika
         delegation_store: spine.delegation_store, # async delegation durability
         channel_delivery: channel_delivery, # out-of-band reply delivery
         reliability: reliability, # WS3: retries/fallback/breaker (data-gated)
+        grounding_enforcer: guardrails.grounding_enforcer, # :enforce cut
+        # the follow-up stores — the ChatBuilder wires the
+        # schedule/cancel_followup tools on them (parity when no pack declares).
+        contact_store: spine.contact_store,
+        followup_store: spine.followup_store,
+        # the model-visible trace rides executor_extra like the
+        # context trace — a module graph that omits it still builds (nil =
+        # parity). The base graph wires it over the same backend the context
+        # trace uses.
+        model_visible_trace_store: Insika::ModelVisibleTraceStore.new(store: spine.backend),
+        # the per-turn extraction hook (nil = the loop is off,
+        # parity). Gated per-agent by `profile.knowledge`.
+        knowledge_store: spine.knowledge_store,
         **executor_extra
       )
 
-        bus = build_core_bus(spine: spine, profiles: profiles, executor: executor)
+        # the ONE path that writes proposals, shared by the
+        # automatic DistillEngine loop and the bus command behind the Studio's
+        # "Run distillation now" button (one code path for both).
+        run_distillation = Insika::Commands::RunDistillation.new(
+          profiles: profiles, proposal_store: spine.proposal_store,
+          session_store: spine.session_store, memory_store: spine.memory_store,
+          settings_store: executor_extra[:settings_store],
+          event_stream: spine.event_stream
+        )
+
+        bus = build_core_bus(spine: spine, profiles: profiles, executor: executor,
+                             executor_extra: executor_extra, skill_catalog: skill_catalog,
+                             run_distillation: run_distillation)
 
         # the periodic tick (outbox drain + stale recovery sweep). Built
         # here, after the bus, because its recovery half dispatches resume_task
         # through it; handed to the Executor, which starts it as a child of the
         # turn supervisor in serving mode. `INSIKA_TICK_INTERVAL=0` disables.
+        # WS8 retention rides the tick: always built, the settings knob
+        # (`retention_days`) gates it — the base graph (no settings_store)
+        # reads as OFF.
         executor.tick = Insika::Tick.new(
           store: spine.backend, channel_delivery: channel_delivery,
           recovery: Insika::Recovery.new(
             task_store: spine.task_store, checkpoint_store: spine.checkpoint_store, command_bus: bus
           ),
+          retention: Insika::Retention.new(
+            store: spine.backend, session_store: spine.session_store,
+            task_store: spine.task_store, checkpoint_store: spine.checkpoint_store,
+            memory_store: spine.memory_store, outcome_store: spine.outcome_store,
+            tool_trace_store: executor_extra[:tool_trace_store],
+            context_trace_store: executor_extra[:context_trace_store],
+            # the model-visible traces die with their checkpoints.
+            model_visible_trace_store: Insika::ModelVisibleTraceStore.new(store: spine.backend),
+            outbox_store: spine.outbox_store,
+            shadow_pair_store: spine.shadow_pair_store,
+            settings_store: executor_extra[:settings_store],
+            budget_ledger: spine.budget_ledger, # WS2 counter GC (retention-independent)
+            funnel_store: spine.funnel_store, # fold dies with its source
+            followup_store: spine.followup_store, # records age out too
+            contact_store: spine.contact_store, # cells age out too
+            proposal_store: spine.proposal_store, # proposals age out too
+            harvest_store: spine.harvest_store, # candidates/log/snapshots too
+            artifact_store: spine.artifact_store # reports expire on their own TTL
+          ),
           interval: tick_env("INSIKA_TICK_INTERVAL") || Insika::Tick::DEFAULT_INTERVAL,
           stale_after: tick_env("INSIKA_TICK_STALE_AFTER") || Insika::Tick::DEFAULT_STALE_AFTER
         )
+        # the tick-driven outcome fold — wired here, after the
+        # Tick, because it reads the outcome/funnel stores of the spine and the
+        # profiles; the per-pair declaration gates it (nil funnel everywhere =
+        # an inert fold). Always built: a pack that declares a funnel later
+        # finds its fold already on the tick.
+        executor.tick.funnel = Insika::FunnelFold.new(
+          outcome_store: spine.outcome_store, funnel_store: spine.funnel_store,
+          profiles: profiles, store: spine.backend
+        )
+        # the tick-driven follow-up firer — the tick's third
+        # duty, wired here after the Tick, gated by its own claim window.
+        # Always built: a pack that declares followup later finds its firer
+        # already on the tick (inert when no profile declares followup).
+        executor.tick.followup = Insika::FollowupEngine.new(
+          store: spine.backend, followup_store: spine.followup_store,
+          contact_store: spine.contact_store, task_store: spine.task_store,
+          profiles: profiles, executor: executor, event_stream: spine.event_stream
+        )
+        # the recurring-schedule firer — the tick's
+        # fourth duty, wired here after the Tick, gated by its own claim
+        # window. Always built: a pack that declares `schedules` later finds
+        # its firer already on the tick (inert when no profile declares one).
+        executor.tick.schedule = Insika::ScheduleEngine.new(
+          store: spine.backend, schedule_store: spine.schedule_store,
+          task_store: spine.task_store, session_store: spine.session_store,
+          profiles: profiles, executor: executor, budget_ledger: spine.budget_ledger,
+          event_stream: spine.event_stream
+        )
+        # the distillation engine — the tick-duty that finds idle
+        # customer sessions and distills them on its own worker fiber (a
+        # supervisor child, started in serving mode next to the tick).
+        # Always built: a pack that declares `distill:` later finds its engine
+        # already wired — and INERT until one does (the engine gates its start
+        # and its passes on a declaring profile).
+        executor.distill_engine = Insika::DistillEngine.new(
+          store: spine.backend, proposal_store: spine.proposal_store,
+          session_store: spine.session_store,
+          runner: run_distillation,
+          profiles: profiles,
+          window: Insika::DistillEngine::DEFAULT_WINDOW
+        )
+        # the harvest engine — the tick-duty that finds idle,
+        # unmined sessions whose agent declares `harvest.enabled` and mines
+        # them on its own worker fiber (a supervisor child, started in serving
+        # mode next to the tick). Always built: INERT until a profile declares
+        # harvest (the engine gates its start and its passes on data). The
+        # runner is the same RunHarvest the bus serves, so the manual CLI and
+        # the automated loop share one code path.
+        run_harvest = Insika::Commands::RunHarvest.new(
+          profiles: profiles, harvest_store: spine.harvest_store,
+          session_store: spine.session_store, task_store: spine.task_store,
+          skill_store: skill_catalog.store, # the harvest's dedup reads the authored skills
+          tool_trace_store: executor_extra[:tool_trace_store],
+          settings_store: executor_extra[:settings_store],
+          negative_list: nil, miner_factory: nil,
+          event_stream: spine.event_stream
+        )
+        executor.harvest_engine = Insika::HarvestEngine.new(
+          store: spine.backend, harvest_store: spine.harvest_store,
+          session_store: spine.session_store, runner: run_harvest,
+          profiles: profiles, window: Insika::HarvestEngine::DEFAULT_WINDOW
+        )
         # WS6 operator alerts: answers budget_warning / breaker_open /
         # delivery_failed per agent (`alerts.webhook`) via the outbox+claim
         # pipeline. Always wired — the per-agent data gates it (parity).
@@ -166,8 +345,19 @@ module Insika
           session_store: spine.session_store, task_store: spine.task_store,
           checkpoint_store: spine.checkpoint_store, pending_action_store: spine.pending_action_store,
           delegation_store: spine.delegation_store,
-          memory_store: spine.memory_store, refinement_store: spine.refinement_store,
-          outbox_store: spine.outbox_store, inbound_log: spine.inbound_log,
+          memory_store: spine.memory_store, memory_audit_store: spine.memory_audit_store,
+          refinement_store: spine.refinement_store,
+          harvest_store: spine.harvest_store,
+          artifact_store: spine.artifact_store,
+          outbox_store: spine.outbox_store, shadow_pair_store: spine.shadow_pair_store,
+          inbound_log: spine.inbound_log,
+          outcome_store: spine.outcome_store,
+          funnel_store: spine.funnel_store,
+          contact_store: spine.contact_store,
+          followup_store: spine.followup_store,
+          schedule_store: spine.schedule_store,
+          proposal_store: spine.proposal_store,
+          knowledge_store: spine.knowledge_store,
           token_store: spine.token_store, budget_ledger: spine.budget_ledger,
           circuit_state: spine.circuit_state,
           channel_registry: spine.channel_registry, channel_delivery: channel_delivery,
@@ -181,10 +371,54 @@ module Insika
         )
       end
 
+      # The boot step behind every root's `load_plugins` (Server::Boot's first
+      # named step). Discovers plugin manifests, validates them, requires the
+      # entries and registers their contributions into the ALREADY-BUILT graph —
+      # which is safe by construction: every seam the Loader touches resolves at
+      # turn time (registries and hooks by name, the middleware stack and the
+      # provider list per call, the catalogs on reload), and the step runs
+      # single-fiber before the server accepts connections.
+      #
+      # Roots, highest precedence first (duplicate id -> first root wins):
+      #   1. workspace  — INSIKA_PLUGIN_DIR (the operator's override spot);
+      #   2. gems       — whatever called Insika::Plugin.announce (default-enabled);
+      #   3. bundled    — `bundled_root` (the repo's plugins/; requires enabling).
+      # INSIKA_PLUGINS enables workspace/bundled ids; INSIKA_PLUGINS_DISABLED is
+      # the absolute veto (deny wins, like every allowlist in the engine).
+      def load_plugins(graph, env: ENV, bundled_root: nil)
+        announced = Insika::Plugin.announced_roots
+        workspace = Insika::EnvSchema.read("INSIKA_PLUGIN_DIR", env)
+        roots = ([workspace] + announced + [bundled_root]).compact.map { |d| File.expand_path(d.to_s) }
+
+        result = Insika::Plugin::Loader.new(
+          roots: roots,
+          registries: {
+            tools: graph.code_tool_registry, workflows: graph.workflow_registry,
+            policies: graph.policy_registry, capabilities: graph.capability_registry,
+            channels: graph.channel_registry, hooks: graph.hooks,
+            middleware: graph.middleware, context_providers: graph.context_providers
+          },
+          enabled: plugin_csv(Insika::EnvSchema.read("INSIKA_PLUGINS", env)),
+          disabled: plugin_csv(Insika::EnvSchema.read("INSIKA_PLUGINS_DISABLED", env)),
+          announced_roots: announced, event_stream: graph.event_stream
+        ).load_all
+
+        # Plugin knowledge joins at the LOWEST precedence: an operator's
+        # workspace/authored skill always beats a same-named plugin one.
+        graph.skill_catalog.add_roots(result[:skill_dirs])
+        graph.prompt_catalog.add_roots(result[:prompt_dirs])
+        result
+      end
+
+      def plugin_csv(value)
+        value.to_s.split(",").map(&:strip).reject(&:empty?)
+      end
+
       # The CORE command surface every root needs — turn essentials + the operator
       # controls (pause/approve) the Studio dispatches. Registering pause_task/
       # approve_action HERE is the crux of: it retires the config.ru:28-34 patch.
-      def build_core_bus(spine:, profiles:, executor:)
+      def build_core_bus(spine:, profiles:, executor:, executor_extra: {}, skill_catalog: nil,
+                         run_distillation: nil)
         bus = Insika::CommandBus.new
         bus.register(:create_session,
                      Insika::Commands::CreateSession.new(session_store: spine.session_store, event_stream: spine.event_stream))
@@ -198,7 +432,10 @@ module Insika
         bus.register(:send_message,
                      Insika::Commands::SendMessage.new(profiles: profiles, session_store: spine.session_store,
                                                         task_store: spine.task_store, executor: executor,
-                                                        inbound_log: spine.inbound_log))
+                                                        inbound_log: spine.inbound_log,
+                                                        contact_store: spine.contact_store,
+                                                        followup_store: spine.followup_store,
+                                                        store: spine.backend))
         bus.register(:resume_task,
                      Insika::Commands::ResumeTask.new(profiles: profiles, task_store: spine.task_store,
                                                        checkpoint_store: spine.checkpoint_store, executor: executor))
@@ -214,6 +451,160 @@ module Insika
         bus.register(:rotate_tenant_token,
                      Insika::Commands::RotateTenantToken.new(token_store: spine.token_store,
                                                              event_stream: spine.event_stream))
+        # WS7: a business outcome per conversation (operator or integration).
+        bus.register(:record_outcome,
+                     Insika::Commands::RecordOutcome.new(outcome_store: spine.outcome_store,
+                                                         event_stream: spine.event_stream))
+        # the incumbent's half of a shadow pair, one command behind
+        # both mirror shapes (the mirror call itself + the follow-up route).
+        bus.register(:record_shadow_reply,
+                     Insika::Commands::RecordShadowReply.new(shadow_pairs: spine.shadow_pair_store,
+                                                             event_stream: spine.event_stream))
+        # WS8 (LGPD): purge one customer's memory + the whole footprint of their
+        # sessions (traces, tasks, checkpoints, outbox). The trace stores are
+        # deployment components (nil at the base — skipped). the
+        # audit collaborator records a content-free purge line.
+        bus.register(:forget_customer,
+                     Insika::Commands::ForgetCustomer.new(
+                       memory_store: spine.memory_store, session_store: spine.session_store,
+                       tool_trace_store: executor_extra[:tool_trace_store],
+                       context_trace_store: executor_extra[:context_trace_store],
+                       # the model-visible traces die with the
+                       # checkpoints (the same SessionPurge list).
+                       model_visible_trace_store: Insika::ModelVisibleTraceStore.new(store: spine.backend),
+                       task_store: spine.task_store, checkpoint_store: spine.checkpoint_store,
+                       outbox_store: spine.outbox_store,
+                       shadow_pairs: spine.shadow_pair_store,
+                       audit_store: spine.memory_audit_store,
+                       followup_store: spine.followup_store,
+                       contact_store: spine.contact_store,
+                       proposal_store: spine.proposal_store,
+                       event_stream: spine.event_stream
+                     ))
+        # the LGPD access right — export one customer's memory
+        # cell as content (the Studio download); the event stays counts-only.
+        bus.register(:export_customer_memory,
+                     Insika::Commands::ExportCustomerMemory.new(
+                       memory_store: spine.memory_store, event_stream: spine.event_stream
+                     ))
+        # WS8 (LGPD): purge ONE TENANT's data — sessions and their footprint,
+        # memory cells and outcomes. Operator-only by construction (ingress).
+        bus.register(:delete_tenant_data,
+                     Insika::Commands::DeleteTenantData.new(
+                       memory_store: spine.memory_store, session_store: spine.session_store,
+                       tool_trace_store: executor_extra[:tool_trace_store],
+                       context_trace_store: executor_extra[:context_trace_store],
+                       # the model-visible traces die with the tenant.
+                       model_visible_trace_store: Insika::ModelVisibleTraceStore.new(store: spine.backend),
+                       outcome_store: spine.outcome_store,
+                       funnel_store: spine.funnel_store, # the fold dies with the tenant
+                        followup_store: spine.followup_store,
+                        contact_store: spine.contact_store,
+                        proposal_store: spine.proposal_store,
+                        harvest_store: spine.harvest_store,
+                        schedule_store: spine.schedule_store,
+                        artifact_store: spine.artifact_store,
+                        task_store: spine.task_store, checkpoint_store: spine.checkpoint_store,
+                          outbox_store: spine.outbox_store,
+                          shadow_pairs: spine.shadow_pair_store,
+                          token_store: spine.token_store, # revoked BEFORE the sweep
+                          event_stream: spine.event_stream
+                        ))
+        # the operator's baseline freeze — the number
+        # read. Synchronous control command, dispatched from the Studio.
+        bus.register(:freeze_funnel_baseline,
+                     Insika::Commands::FreezeFunnelBaseline.new(
+                       funnel_store: spine.funnel_store, profiles: profiles,
+                       event_stream: spine.event_stream
+                     ))
+        # the follow-up mutations — the Studio's Cancel button
+        # and the channel opt-out event (a tenant principal never reaches the
+        # generic command ingress; these ride the same operator-grade path).
+        bus.register(:cancel_followup,
+                     Insika::Commands::CancelFollowup.new(followup_store: spine.followup_store,
+                                                          event_stream: spine.event_stream))
+        # the report destination's Studio mutation — delete one
+        # artifact (the only write on the Artifacts tab; a bus command, like
+        # every Studio mutation).
+        bus.register(:delete_artifact,
+                     Insika::Commands::DeleteArtifact.new(artifact_store: spine.artifact_store,
+                                                          event_stream: spine.event_stream))
+        bus.register(:revoke_contact,
+                     Insika::Commands::RevokeContact.new(contact_store: spine.contact_store,
+                                                         followup_store: spine.followup_store,
+                                                         store: spine.backend,
+                                                         event_stream: spine.event_stream))
+        # the human's answer on a distilled proposal — the ONLY
+        # mutation behind the Facts (wiki) page. Synchronous control command.
+        bus.register(:resolve_proposal,
+                     Insika::Commands::ResolveProposal.new(
+                       proposal_store: spine.proposal_store,
+                       memory_store: spine.memory_store,
+                       event_stream: spine.event_stream
+                     ))
+        #  /C10: the gated harvest — the mining pass, the double
+        # gate, the human's promote/rollback/dismiss. The BASE graph wires the
+        # nil factories (no eval surface, no criterion, no funnel): every flow
+        # refuses with a named reason or skips (parity). The deployment root
+        # re-registers with the real gate/criterion/negative list.
+        bus.register(:run_harvest,
+                     Insika::Commands::RunHarvest.new(
+                       profiles: profiles, harvest_store: spine.harvest_store,
+                       session_store: spine.session_store, task_store: spine.task_store,
+                       skill_store: skill_catalog.store,
+                       tool_trace_store: executor_extra[:tool_trace_store],
+                       settings_store: executor_extra[:settings_store],
+                       negative_list: nil, miner_factory: nil,
+                       event_stream: spine.event_stream
+                     ))
+        bus.register(:gate_harvest,
+                     Insika::Commands::GateHarvest.new(
+                       harvest_store: spine.harvest_store, gate: nil,
+                       conversion_gate: nil, criterion: nil,
+                       event_stream: spine.event_stream
+                     ))
+        bus.register(:promote_harvest,
+                     Insika::Commands::PromoteHarvest.new(
+                       harvest_store: spine.harvest_store,
+                       skill_store: skill_catalog.store,
+                       skill_catalog: skill_catalog,
+                       profile_source: profiles, criterion: nil, conversion_gate: nil,
+                       event_stream: spine.event_stream
+                     ))
+        bus.register(:rollback_harvest,
+                     Insika::Commands::RollbackHarvest.new(
+                       harvest_store: spine.harvest_store,
+                       skill_store: skill_catalog.store,
+                       skill_catalog: skill_catalog,
+                       profile_source: profiles, event_stream: spine.event_stream
+                     ))
+        bus.register(:reject_harvest,
+                     Insika::Commands::RejectHarvest.new(
+                       harvest_store: spine.harvest_store, event_stream: spine.event_stream
+                     ))
+        # the ONE path that writes proposals, served to the
+        # Studio's "Run distillation now" button. The same instance the
+        # DistillEngine's loop uses, so the manual and the automatic share one
+        # code path; the engine keeps the automatic pass when the root does
+        # not pass a runner here (nil = the command is not on the bus).
+        bus.register(:run_distillation, run_distillation) if run_distillation
+        # the demo seed's ONE path — the CLI's `insika demo:seed` builds
+        # the same Insika::Demo::Seeder itself (no executor, no bus, from
+        # Graph.spine alone), and the Studio's "Seed demo data" button
+        # dispatches this bus command; nothing else writes the demo agent.
+        config_store = Insika::ConfigStore.new(store: spine.backend)
+        demo_seeder = Insika::Demo::Seeder.new(
+          profiles: profiles, store: spine.backend, session_store: spine.session_store,
+          task_store: spine.task_store, outcome_store: spine.outcome_store,
+          funnel_store: spine.funnel_store, followup_store: spine.followup_store,
+          refinement_store: spine.refinement_store, pending_action_store: spine.pending_action_store,
+          proposal_store: spine.proposal_store, memory_store: spine.memory_store,
+          golden_store: Insika::GoldenStore.new(config_store: config_store),
+          baseline_store: Insika::BaselineStore.new(config_store: config_store),
+          event_stream: spine.event_stream
+        )
+        bus.register(:seed_demo_data,
+                     Insika::Commands::SeedDemoData.new(seeder: demo_seeder, event_stream: spine.event_stream))
         bus
       end
 
@@ -221,9 +612,15 @@ module Insika
       # them to their historic public constants (SESSION_STORE, REGISTRY, ...).
       Spine = Struct.new(
         :backend, :event_stream, :session_store, :task_store, :checkpoint_store,
-        :pending_action_store, :delegation_store, :memory_store, :refinement_store,
-        :token_store, :budget_ledger, :circuit_state, :outbox_store, :inbound_log, :code_tool_registry,
-        :workflow_registry, :policy_registry, :capability_registry, :hooks,
+        :pending_action_store, :delegation_store, :memory_store, :memory_audit_store,
+        :refinement_store,
+        :harvest_store,
+        :token_store, :budget_ledger, :circuit_state, :outbox_store, :shadow_pair_store,
+        :inbound_log, :outcome_store, :funnel_store,
+        :contact_store, :followup_store, :schedule_store, :proposal_store,
+        :knowledge_store,
+        :artifact_store,
+        :code_tool_registry, :workflow_registry, :policy_registry, :capability_registry, :hooks,
         :channel_registry, keyword_init: true
       )
 
@@ -233,8 +630,15 @@ module Insika
       Result = Struct.new(
         :backend, :event_stream,
         :session_store, :task_store, :checkpoint_store, :pending_action_store, :delegation_store,
-        :memory_store, :refinement_store, :outbox_store, :inbound_log, :token_store,
-        :budget_ledger, :circuit_state, :channel_registry, :channel_delivery,
+        :memory_store, :memory_audit_store, :refinement_store, :outbox_store, :shadow_pair_store,
+        :inbound_log, :token_store,
+        :budget_ledger, :circuit_state, :outcome_store, :funnel_store,
+        :contact_store, :followup_store, :proposal_store,
+        :schedule_store,
+        :harvest_store,
+        :knowledge_store,
+        :artifact_store,
+        :channel_registry, :channel_delivery,
         :code_tool_registry, :tool_registry, :workflow_registry, :policy_registry, :capability_registry,
         :tool_catalog, :skill_catalog, :prompt_catalog,
         :hooks, :guardrails, :middleware,
@@ -244,6 +648,61 @@ module Insika
       ) do
         def durable? = backend.is_a?(Insika::Stores::SQLite)
       end
+
+      # The save_artifact tool, registered OPTIONAL on the shared code registry
+      # (the per-agent allowlist is the switch). The signing/base config is
+      # bound at registration time from the environment — the tool instance is
+      # per-deployment, and the tenant/agent/task bindings arrive per-turn via
+      # the deposited turn context.
+      # `run_persona_eval` (C3.1): a QA agent's own probe against a SIBLING
+      # agent of THIS SAME graph. Registered OPTIONAL on the shared code
+      # registry, same switch as `save_artifact` — but unlike that one, this
+      # is NOT called unconditionally from `build`: it needs a `golden_store`
+      # and a `settings_store` (the persona model + judge panel), and neither
+      # lives on the spine (the base/minimal wiring builds without either, the
+      # same way it builds without a Studio) — so each root calls this itself,
+      # once it has both. `config/deployment.rb` (round1, and the actual
+      # production `config.ru` root) and `DSL::Runtime` both do.
+      #
+      # `graph` is the ALREADY-RETURNED `Graph::Result` — bus/executor fully
+      # assembled by the time a caller has it to pass here, so `GraphChat.new`
+      # needs no laziness of its own (the tool's own factory block is what is
+      # lazy — this method just registers it).
+      # `llm:` — the caller's own RubyLLM::Context, when it has one
+      # (DSL::Runtime does; config/deployment.rb does not, and reads the
+      # process-wide RubyLLM constant like the rest of that root already
+      # does). Forwarded as-is so the tool's OWN persona/judge calls spend
+      # the right credentials instead of silently defaulting to nil.
+      def register_persona_eval_tool(graph, golden_store:, settings_store:, llm: nil)
+        graph.code_tool_registry.register("run_persona_eval", optional: true) do
+          require "ruby_llm"
+          require_relative "../tools/run_persona_eval"
+          Insika::Tools::RunPersonaEval.new(
+            golden_store: golden_store, profiles: graph.profiles, tool_registry: graph.tool_registry,
+            runtime: GraphChat.new(graph: graph), graph: graph, settings_store: settings_store,
+            budget_ledger: graph.budget_ledger, event_stream: graph.event_stream, llm: llm
+          )
+        end
+      end
+
+      def register_artifact_tool(spine)
+        signing_key = Insika::EnvSchema.read("INSIKA_ARTIFACT_SIGNING_KEY")
+        signing_ttl = Insika::EnvSchema.read("INSIKA_ARTIFACT_SIGNING_TTL")
+        max_bytes = Insika::EnvSchema.read("INSIKA_ARTIFACT_MAX_BYTES")
+        base_url = Insika::Coercion.presence(Insika::EnvSchema.read("INSIKA_PUBLIC_URL"))
+        spine.code_tool_registry.register("save_artifact", optional: true) do
+          require "ruby_llm"
+          require_relative "../tools/save_artifact"
+          Insika::Tools::SaveArtifact.new(
+            artifact_store: spine.artifact_store,
+            base_url: base_url,
+            signing_key: signing_key,
+            signing_ttl: signing_ttl&.to_i,
+            max_bytes: max_bytes&.to_i,
+            event_stream: spine.event_stream
+          )
+        end
+      end
     end
   end
 end