HHostingByteSoftware
Ctrl K
ComunidadGuías…

architecture.toml

Rama main · réplica de lectura del repositorio original.

Archivo original ↗Preguntar a KiBot
schema_version = "1.0"
system = "mikan"
docs = "ARCHITECTURE.md"

# Canonical global architecture index.
# Schema: .pi/skills/mikan-architecture/references/SCHEMA.md
# Detailed semantics live in ARCHITECTURE.md and module-local README files.
# IDs are stable references and must not be reused for a different concept.

[[modules]]
id = "composition-root"
name = "Process composition root"
kind = "entrypoint"
docs = "ARCHITECTURE.md#boot-and-process-lifecycle"
sources = ["src/main.ts", "src/cli/process-lifecycle.ts", "src/cli/boot.ts"]

[[modules]]
id = "observability"
name = "Process observability"
kind = "infrastructure"
docs = "src/observability/README.md"
sources = ["src/observability/"]

[[modules]]
id = "platform-adapters"
name = "Platform adapters"
kind = "adapter"
docs = "src/adapters/README.md"
sources = ["src/adapters/"]

[[modules]]
id = "conversation-intake"
name = "Conversation intake"
kind = "orchestrator"
docs = "src/adapters/README.md#contracts"
sources = ["src/adapters/intake.ts"]

[[modules]]
id = "conversation-runtime"
name = "Conversation runtime"
kind = "orchestrator"
docs = "src/runtime/README.md"
sources = ["src/runtime/"]

[[modules]]
id = "harness"
name = "Agent harness"
kind = "core"
docs = "src/harness/README.md"
sources = ["src/harness/"]

[[modules]]
id = "office"
name = "Conversation office"
kind = "authority"
docs = "src/office/README.md"
sources = ["src/office/"]

[[modules]]
id = "state-migrations"
name = "State migrations"
kind = "authority"
docs = "src/migrations/README.md"
sources = ["src/migrations/", "src/cli/migrate.ts"]

[[modules]]
id = "configuration"
name = "Configuration and live settings"
kind = "authority"
docs = "src/settings/README.md"
sources = ["src/settings/"]

[[modules]]
id = "sandbox"
name = "Sandbox execution"
kind = "infrastructure"
docs = "src/sandbox/README.md"
sources = ["src/sandbox/"]

[[modules]]
id = "sessions"
name = "Conversation sessions"
kind = "authority"
docs = "src/sessions/README.md"
sources = ["src/sessions/"]

[[modules]]
id = "vault"
name = "Credential vault"
kind = "authority"
docs = "src/vault/README.md"
sources = ["src/vault/"]

[[modules]]
id = "commands"
name = "Built-in commands"
kind = "registry"
docs = "src/adapters/commands/README.md"
sources = ["src/adapters/commands/"]

[[modules]]
id = "web-adapter"
name = "Web adapter"
kind = "adapter"
docs = "src/adapters/README.md#contracts"
sources = ["src/adapters/web/"]

[[modules]]
id = "events"
name = "Scheduled events"
kind = "infrastructure"
docs = "src/events/README.md"
sources = ["src/events/"]

# A seam is a stable relationship callers depend on. Interface names refer to
# source-level contracts or authority entry points; details stay in docs/code.

[[seams]]
id = "telemetry"
owner = "observability"
consumers = [
  "composition-root",
  "platform-adapters",
  "conversation-runtime",
  "harness",
  "sandbox",
  "vault",
  "events",
  "web-adapter",
]
interface = "vendor-neutral errors, spans, metrics, events, attribution, and shutdown"
docs = "src/observability/README.md"

[[seams]]
id = "platform-messaging"
owner = "platform-adapters"
consumers = [
  "composition-root",
  "conversation-intake",
  "conversation-runtime",
  "harness",
  "web-adapter",
  "events",
]
interface = "MessagingBot, ConversationEvent, ConversationResponder"
docs = "src/adapters/README.md"

[[seams]]
id = "intake"
owner = "conversation-intake"
consumers = ["platform-adapters"]
interface = "processMessageIntake"
docs = "src/adapters/README.md#contracts"

[[seams]]
id = "runtime"
owner = "conversation-runtime"
consumers = ["composition-root", "conversation-intake", "web-adapter", "configuration"]
interface = "ConversationRuntime"
docs = "src/runtime/README.md"

[[seams]]
id = "runner"
owner = "harness"
consumers = ["conversation-runtime"]
interface = "PiAgentWrapper"
docs = "ARCHITECTURE.md#agent-execution"

[[seams]]
id = "mcp-tools"
owner = "harness"
consumers = ["web-adapter"]
interface = "loadMcpTools"
docs = "src/harness/README.md"

[[seams]]
id = "harness-model-calls"
owner = "harness"
consumers = ["platform-adapters"]
interface = "evaluateWithJev"
docs = "src/harness/README.md"

[[seams]]
id = "office-resolution"
owner = "office"
consumers = [
  "platform-adapters",
  "conversation-runtime",
  "sessions",
  "vault",
  "configuration",
  "web-adapter",
  "harness",
  "events",
]
interface = "Workspace.office, Office, createConversationEvent, createConversationMessage, parseGithubConversationId"
docs = "src/office/README.md"

[[seams]]
id = "settings"
owner = "configuration"
consumers = [
  "composition-root",
  "conversation-runtime",
  "commands",
  "office",
  "harness",
  "web-adapter",
]
interface = "resolve settings, apply settings mutations"
docs = "ARCHITECTURE.md#configuration-authority"

[[seams]]
id = "projection"
owner = "office"
consumers = ["harness"]
interface = "resolveWorkspaceProjection"
docs = "src/office/README.md"

[[seams]]
id = "executor"
owner = "sandbox"
consumers = ["harness"]
interface = "pi-durable ExecutionEnv, SandboxAdapter"
docs = "src/sandbox/README.md"

[[seams]]
id = "session-store"
owner = "sessions"
consumers = ["conversation-runtime", "harness"]
interface = "session-key policy, managed session store"
docs = "src/sessions/README.md"

[[seams]]
id = "vault-resolution"
owner = "vault"
consumers = ["harness", "web-adapter"]
interface = "VaultManager"
docs = "src/vault/README.md"

[[seams]]
id = "command-inventory"
owner = "commands"
consumers = ["platform-adapters", "conversation-runtime"]
interface = "COMMAND_MANIFEST"
docs = "src/adapters/commands/README.md"

[[seams]]
id = "event-protocol"
owner = "events"
consumers = ["harness", "web-adapter"]
interface = "EventStore, OfficeEventStore, EventScheduler, buildEventPayload, parseEventPayload"
docs = "src/events/README.md"

# Resources record global ownership and security classification. Paths are
# conceptual locations; detailed layouts belong to the owning module docs.

[[resources]]
id = "workspace-root"
authority = "office"
scope = "deployment"
classification = "shared-workspace-data"
docs = "ARCHITECTURE.md#storage-and-authority-map"

[[resources]]
id = "office-directory"
authority = "office"
scope = "conversation"
classification = "conversation-data"
docs = "src/office/README.md"

[[resources]]
id = "state-dir"
authority = "configuration"
scope = "deployment"
classification = "host-private"
docs = "ARCHITECTURE.md#storage-and-authority-map"

[[resources]]
id = "migration-record"
authority = "state-migrations"
scope = "deployment"
classification = "host-authoritative"
docs = "src/migrations/README.md"

[[resources]]
id = "office-registry"
authority = "office"
scope = "deployment"
classification = "host-authoritative"
docs = "src/office/README.md"

[[resources]]
id = "settings"
authority = "configuration"
scope = "deployment-and-conversation"
classification = "host-authoritative"
docs = "ARCHITECTURE.md#configuration-authority"

[[resources]]
id = "session-files"
authority = "sessions"
scope = "session"
classification = "conversation-data"
docs = "src/sessions/README.md"

[[resources]]
id = "platform-log"
authority = "platform-adapters"
scope = "conversation"
classification = "conversation-data"
docs = "src/adapters/README.md"

[[resources]]
id = "workspace-projection"
authority = "office"
scope = "conversation-runtime"
classification = "authorized-view"
docs = "src/office/README.md"

[[resources]]
id = "vault-store"
authority = "vault"
scope = "credential-key"
classification = "credential"
docs = "src/vault/README.md"

[[resources]]
id = "openconnector-runtime-token"
authority = "harness"
scope = "conversation"
classification = "credential"
docs = "src/harness/README.md"

[[resources]]
id = "runner-state"
authority = "conversation-runtime"
scope = "office-and-session"
classification = "ephemeral"
docs = "src/runtime/README.md"

[[resources]]
id = "events-bus"
authority = "events"
scope = "conversation"
classification = "host-only-scheduling"
docs = "ARCHITECTURE.md#scheduled-execution"

[[flows]]
id = "boot"
path = [
  "composition-root",
  "observability",
  "office",
  "configuration",
  "conversation-runtime",
  "platform-adapters",
  "web-adapter",
  "events",
]
docs = "ARCHITECTURE.md#boot-and-process-lifecycle"

[[flows]]
id = "conversation-run"
path = [
  "platform-adapters",
  "conversation-intake",
  "conversation-runtime",
  "harness",
  "platform-adapters",
]
docs = "ARCHITECTURE.md#conversation-run"

[[flows]]
id = "execution-resolution"
path = ["harness", "office", "harness", "vault", "sandbox"]
docs = "ARCHITECTURE.md#execution-resolution"

[[flows]]
id = "scheduled-text-event"
path = ["events", "platform-adapters", "conversation-runtime", "harness", "platform-adapters"]
docs = "ARCHITECTURE.md#scheduled-execution"

[[invariants]]
id = "identity-office-address"
owners = ["office"]
applies_to = ["platform-adapters", "conversation-runtime", "sessions", "vault"]
docs = "ARCHITECTURE.md#inv-identity-office-address"
adr = "docs/adr/0005-office-address-identity.md"

[[invariants]]
id = "identity-office-key"
owners = ["office"]
applies_to = ["configuration", "sessions", "vault"]
docs = "ARCHITECTURE.md#inv-identity-office-key"
adr = "docs/adr/0005-office-address-identity.md"

[[invariants]]
id = "office-record-before-directory"
owners = ["office"]
applies_to = ["office-registry", "office-directory"]
docs = "ARCHITECTURE.md#inv-office-record-before-directory"

[[invariants]]
id = "runtime-composite-identity"
owners = ["conversation-runtime", "sessions"]
applies_to = ["runner-state", "session-files"]
docs = "ARCHITECTURE.md#inv-runtime-composite-identity"

[[invariants]]
id = "intake-order"
owners = ["conversation-intake"]
applies_to = ["platform-adapters", "conversation-runtime"]
docs = "ARCHITECTURE.md#inv-intake-order"

[[invariants]]
id = "session-serialization"
owners = ["conversation-runtime"]
applies_to = ["runner-state"]
docs = "ARCHITECTURE.md#inv-session-serialization"

[[invariants]]
id = "process-shutdown-order"
owners = ["composition-root", "platform-adapters", "web-adapter", "events", "conversation-runtime"]
applies_to = ["platform-adapters", "web-adapter", "events", "events-bus", "runner-state"]
docs = "ARCHITECTURE.md#inv-process-shutdown-order"

[[invariants]]
id = "runner-materialization-rollback"
owners = ["harness", "sessions"]
applies_to = ["runner-state", "mcp-tools", "session-files"]
docs = "ARCHITECTURE.md#inv-runner-materialization-rollback"

[[invariants]]
id = "run-settlement"
owners = ["conversation-runtime", "harness"]
applies_to = ["runner-state", "platform-adapters"]
docs = "ARCHITECTURE.md#inv-run-settlement"

[[invariants]]
id = "projection-coherence"
owners = ["office"]
applies_to = ["office", "office-directory", "workspace-projection", "harness", "sandbox"]
docs = "ARCHITECTURE.md#inv-projection-coherence"

[[invariants]]
id = "state-dir-host-only"
owners = ["configuration"]
applies_to = ["state-dir", "workspace-projection", "vault-store"]
docs = "ARCHITECTURE.md#inv-state-dir-host-only"

[[invariants]]
id = "execution-policy-enforcement"
owners = ["harness", "sandbox"]
applies_to = ["workspace-projection"]
docs = "ARCHITECTURE.md#inv-execution-policy-enforcement"

[[invariants]]
id = "credential-least-authority"
owners = ["harness", "vault"]
applies_to = ["vault-store", "sandbox"]
docs = "ARCHITECTURE.md#inv-credential-least-authority"

[[invariants]]
id = "mcp-conversation-authority"
owners = ["harness", "conversation-runtime"]
applies_to = ["mcp-tools", "openconnector-runtime-token", "office", "runner-state"]
docs = "ARCHITECTURE.md#inv-mcp-conversation-authority"

[[invariants]]
id = "settings-runner-coherence"
owners = ["configuration", "conversation-runtime"]
applies_to = ["settings", "runner-state"]
docs = "ARCHITECTURE.md#inv-settings-runner-coherence"

[[invariants]]
id = "session-format-compatibility"
owners = ["sessions", "harness"]
applies_to = ["session-files"]
docs = "ARCHITECTURE.md#inv-session-format-compatibility"

# Deviations make current implementation limits visible without changing the
# accepted target model in prose or ADRs.

[[deviations]]
id = "runtime-resource-identity"
status = "open"
affects = ["sandbox", "office"]
docs = "ARCHITECTURE.md#dev-runtime-resource-identity"
adr = "docs/adr/0005-office-address-identity.md"