티스토리 뷰

Overview of Biligent

Round Planning Specification Round 0 (R0) Foundation & Infrastructure

Round 0 (R0) Planning Specification: Base Infrastructure, Core Harness & Platform Foundations

The Inaugural Engineering Increment Establishing Core Schemas, Dual Database Persistence (Domain DB & Integrated DB), Event Observability, Multi-User Auth, UI Shell, and LLM Gateway Scaffolding.

Round ID: R0 (Foundation Increment)
Prerequisite: None (Greenfield Project Inception)
Status: Approved Baseline Specification
 

Figure 1. Building the Solid Foundation Together. Just as nature's master engineers—the beaver laying heavy timbers, the badger anchoring the ground, the otter binding strong ropes, and the shepherd ensuring structural integrity—collaborate seamlessly, Round 0 constructs the unshakeable base infrastructure, contract schemas, storage engines, and event pipelines upon which all future multi-agent intelligence rests.

Round 0 Status & Authority: Round 0 (R0) is the foundational cornerstone of the Data Agent Platform. It provides all underlying contract schemas, dual-database abstractions (Domain DB & Integrated DB), structured observability, asynchronous parallel processing, multi-user authentication skeleton, domain lifecycle creation, and basic UI shell. Subsequent rounds (R1~R12) build upon R0 without altering its established interface inputs or outputs.

1. Purpose of Round 0

The purpose of Round 0 is to construct the foundational architecture and test harness for the entire platform from a completely greenfield state. Specifically, R0 implements:

  • Contracts & Schemas (contracts): Defines formal inter-agent request types, event schemas, standardized envelopes, versioned reference structures (DependencyRef), declarative representation formats, calculation step types, parameter bindings, knowledge tier transition tables, batch inclusion/exclusion logs (Batch), reason codes, and open/closed enumeration rules.
  • Dual-Tier Persistence (store): Implements isolated per-domain storage (Domain DB) and system-wide persistent storage (Integrated DB), with transactional write safety, key-value stores, and database migration capabilities.
  • Observability & Event Bus (observability): Provides structured event emission, topic subscription, distributed trace spans, and progress reporting with heartbeat telemetry.
  • Parallel Execution & LLM Gateway (parallel & llm_gateway): Manages asynchronous worker pools and external LLM provider routing with fallback support.
  • Access Control Skeleton (access): Establishes multi-user authentication, account registries, initial server administrator bootstrapping, internal user mapping, and declarative permission tables (RQ-123).
  • Domain Lifecycle Skeleton (domain_lifecycle): Implements create operations to instantiate new Domain DBs, register domain metadata in the Integrated DB, and emit domain creation events.
  • UI Shell Prototype (ui): Establishes the foundational conversational interface, opinion input panels, status bars, and real-time progress indicators.

2. Key Objectives & Milestones

The concrete milestones achieved in Round 0 include:

  1. All base modules pass 100% of their standalone unit test suites, proving zero circular dependencies and zero higher-level imports.
  2. Integrated DB and Domain DB schemas are created and verified through transactional isolation tests.
  3. Initial Server Administrator account can be registered via installation configuration.
  4. New domains can be created dynamically, provisioning dedicated isolated database instances.
  5. The event bus transmits structured event envelopes across modules with verified trace context propagation.
  6. Completion criteria defined in Section 17 are completely satisfied.

3. Architectural Intent, Usage & Necessity

Architectural Intent

Lay a mathematically rigorous, deterministic substrate that decouples autonomous agent reasoning from low-level storage, concurrency, and serialization concerns.

System Necessity

Without Round 0, none of the 35 foundational functional requirements (RQ) and 5 core user decision rules (UR) can be hosted or validated in subsequent rounds.

Operational Usage

Outputs from R0 form the immutable foundation. Subsequent rounds (R1~R12) attach downstream connections without modifying R0 interface signatures.

4. Scope (Inclusions & Exclusions)

Summary of delivered artifacts and boundaries for Round 0:

Category Delivered Count Detailed Item Catalog
Packages / Modules 8 Modules contracts, store, observability, parallel, llm_gateway, access (skeleton), domain_lifecycle (skeleton), ui (skeleton)
Agents 0 Agents No autonomous agents are instantiated in R0 (all agent contracts and envelopes are formally declared for introduction in R1~R11)
Functional Requirements 35 Requirements RQ-007~009, RQ-015~017, RQ-020, RQ-021, RQ-023~033, RQ-071~073, RQ-078, RQ-082, RQ-083, RQ-093, RQ-111, RQ-114, RQ-115, RQ-123, RQ-124, RQ-127, RQ-137, RQ-138, RQ-162
User Decision Rules 5 Rules UR-02 (Deterministic checks before async LLM), UR-18 (Session persistence), UR-26 (Task queue single-execution lock), UR-27 (Trace propagation), UR-28 (Immutable provenance logging)
Inter-Module Connections 4 Connection Pairs Platform → access, Platform → domain_lifecycle, store → observability, access → store

5. Modules Introduced in Round 0

Detailed architecture and state boundaries for all 8 modules implemented in Round 0:

Module Hierarchy & Group Round Scope Owned Storage & Tables Key Public Interfaces
access Major Group C (User Operations)
Middle: user_ops
R0 (Skeleton) · R8 (Full) · R9 (Re-application) Integrated DB: accounts, domain_roles, session_tokens authenticate(credentials) -> AuthSession
register_account(account_spec, provenance) -> AccountRef
authorize(user_id, operation, domain_id) -> AuthDecision
node_filter_for(user_id, domain_id) -> NodeFilter
domain_lifecycle Major Group C (User Operations)
Middle: user_ops
R0 (Skeleton) · R10 (Carryover/Reset) Integrated DB: domains_catalog, domain_status create(domain_spec, creator) -> domain_id
domain_info(domain_id) -> DomainMetadata
list_domains(user_id) -> DomainMetadata[]
contracts Major Group E (Base Infrastructure)
Middle: base
R0 (Comprehensive Schema Base) Stateless Schema Definitions (TypeScript / Pydantic models) Formal type definitions for Envelopes, Revisions, Provenance, Batch, CalcPlan, NodeFilter, Decision, EventPayloads
store Major Group E (Base Infrastructure)
Middle: base
R0 (Dual Engine Persistence) Domain DB & Integrated DB storage engines, connection pools, KV store connect_domain(domain_id) -> DBConn
connect_integrated() -> DBConn
execute_sql(conn, sql, params) -> Result
transaction(conn, callback) -> TxResult
kv_get(key) / kv_set(key, val)
observability Major Group E (Base Infrastructure)
Middle: base
R0 (Core Event Bus & Tracing) In-memory Event Bus & Log Spans emit_event(event_envelope)
subscribe(event_pattern, handler_fn) -> SubId
start_span(name, context) -> SpanRef
track_progress(task_id, step, total_steps, eta_ms)
parallel Major Group E (Base Infrastructure)
Middle: base
R0 (Worker Thread Pool) Stateless Worker Pool Management run_parallel(tasks, max_workers, timeout_ms) -> ResultList
run_async(task_fn, callback) -> TaskHandle
llm_gateway Major Group E (Base Infrastructure)
Middle: base
R0 (Multi-Backend Provider Client) Provider configuration, Mock backends for dev/testing call_llm(prompt, config) -> LLMResponse
register_hook(stage, hook_fn)
ui Top Presentation Layer
Shell Interface
R0 (Skeleton Shell) · Polish in R12 Local UI session state, chat display buffer Chat pane, opinion draft submission form, real-time progress bar, status notifications

6. Detailed Functional Specifications & Invariants for Round 0

Each module implemented in Round 0 must strictly satisfy its designated functional requirements, exception handling paths, and verifiable acceptance criteria:

1. Module: access (Authentication, Authorization & Account Registry)

Provides multi-user security boundaries, account registration, session authentication, and declarative permission evaluation based on the master permissions matrix:

Function Normal Operation & Behavior Exception & Boundary Handling Verifiable Acceptance Criteria
authenticate Validates user credentials (open auth methods: OAuth token or username/password) against the Integrated DB accounts table. Returns an authenticated AuthSession containing internal user ID and assigned global/domain roles. If credentials do not match or account is inactive, returns AUTH_FAILED immediately without leaking account existence details. Unit tests verify that valid credentials generate signed session tokens and invalid credentials are systematically rejected with standardized error codes.
authorize Evaluates whether a given user_id is authorized to perform a specific operation within domain_id by querying the declarative permissions matrix (§18). Also returns the learning_signal boolean flag. If user has no assigned role in the target domain, defaults strictly to DENIED with zero learning signal. Unknown operations default to DENIED. Test matrix passes 100% of authorization checks across Server Admin, Domain Admin, Read+Learn, and Read-Only roles matching the exact permissions table.
register_account Registers a new user account in the Integrated DB. Bootstraps the initial Server Administrator account from installation configuration settings during platform startup. Duplicate username or external auth identifier raises DUPLICATE_ACCOUNT exception with zero state corruption. Initial server admin account is successfully registered upon clean installation and verified in the accounts database table.
node_filter_for Generates a NodeFilter payload specifying authorized data types and accessible node IDs for the user within the domain. If user has full access, returns an unconstrained filter. If restricted, returns explicit inclusion lists. Downstream compute tests verify that restricted node filters correctly mask prohibited columns in query outputs.

2. Module: domain_lifecycle (Domain Instantiation & Cataloging)

Manages the lifecycle creation of isolated domain workbenches:

Function Normal Operation & Behavior Exception & Boundary Handling Verifiable Acceptance Criteria
create Creates a new isolated Domain DB instance, applies initial base schema DDLs, registers domain metadata into Integrated DB domains_catalog, assigns the creator as the first Domain Administrator, and emits a domain_created event. If domain name conflicts or storage provisioning fails, performs atomic rollback of both database file and catalog record. Calling create provisions a physically separate database file, returns a valid domain_id, and triggers a verifiable domain_created event on the event bus.
domain_info Retrieves domain metadata, creation timestamp, creator ID, and active status from the Integrated DB. If domain_id does not exist, raises DOMAIN_NOT_FOUND. Returns accurate metadata matching the created domain properties.

3. Module: store (Dual Database Persistence & Transactional Isolation)

Provides robust persistence primitives separating Domain DBs from the Integrated DB:

Function Normal Operation & Behavior Exception & Boundary Handling Verifiable Acceptance Criteria
connect_domain & connect_integrated Opens pooled connections to the target Domain DB or system Integrated DB with WAL (Write-Ahead Logging) mode enabled for high concurrency. Connection pool exhaustion queues callers up to a configured timeout before raising POOL_TIMEOUT. Verified concurrent read/write tests under multi-threaded access pass without database lock deadlocks.
transaction Executes a callback inside an atomic ACID transaction. Commits on success; automatically rolls back on any exception. Nested transactions use savepoints. Unhandled exceptions trigger immediate rollback and re-raise. Transactional failure injection tests confirm that partial writes are 100% rolled back, preserving database integrity.
kv_get & kv_set Provides fast key-value persistence for system flags, installation properties, and session caching. Non-existent keys return null/None without error. Key-value read/write/delete operations pass deterministic unit tests.

4. Module: observability (Event Bus, Telemetry & Progress Heartbeats)

The central sensory and telemetry backbone of the platform:

Function Normal Operation & Behavior Exception & Boundary Handling Verifiable Acceptance Criteria
emit_event Publishes a typed event envelope to the system event bus. Propagates distributed trace IDs and timestamps. Handler exceptions do not block other subscribers; errors are captured in audit logs. Events published to the bus are delivered to all registered pattern subscribers with sub-millisecond latency.
subscribe Registers an asynchronous callback handler for an event topic or wildcard pattern. Duplicate subscriptions are idempotent. Subscribers receive exact event envelopes matching their registered patterns.
track_progress Emits real-time progress updates (step index, total steps, estimated completion time, heartbeat). Step count out-of-bounds is clamped safely. UI progress listener receives real-time progress events within PR-01 heartbeat intervals.

5. Module: contracts (Authoritative Schema & Envelope Definitions)

Stateless type library governing all data structures across the platform:

// Core Contract Schemas declared in contracts module:
1. Envelope Schemas: RequestEnvelope, ResultEnvelope, EventEnvelope, ErrorEnvelope
2. Lineage & Provenance: ProvenanceRecord (actor, timestamp, method, source_ref, reason)
3. Versioning: DependencyRef (ref_id, rev, timestamp), MonotonicRevision
4. Computation: CalcPlan, CalcStep, SlotBinding, BatchExclusionRecord (included, excluded, reason_code)
5. Access: AuthSession, AccountRef, NodeFilter, PermissionsMatrixRow
6. Knowledge: KnowledgeTier (NeedsConfirmation | Approved | Certified), TierTransitionRule
7. Data Topology: NodeKind (ColumnName | KeyName | StatusValue | ConditionValue), ValueRole (Measurement | Status | Condition)

6. Modules: parallel & llm_gateway (Concurrency & LLM Client)

  • parallel.run_parallel: Executes CPU/IO bound tasks across a controlled worker pool, enforcing task timeouts and aggregating results safely.
  • llm_gateway.call_llm: Dispatches LLM requests to configured provider backends (with zero-cost local mock backends during testing), executing pre/post hook chains for logging and token budgeting.

7. Module: ui (Unified User & Developer Interface Shell)

Provides the web-based conversational interface, chat pane, opinion draft submission form, status bar, and real-time progress rendering connected to observability events.

7. Performance Requirements (PR)

Performance benchmarks targeted and measured in Round 0:

Owner Module Requirement ID Measurement Method Target Benchmark Architectural Rationale Path in R0
store PR-24 Measure concurrent write latency and failure rate across varying session counts; benchmark copy_domain duration across database sizes. TBD — Confirmed in Implementation Plan RQ-123 (Concurrency), RQ-138 (Migration), Common Completion Criteria 5 (Cross-round migration) store concurrent write & domain copy routines
observability PR-25 Measure difference in query/analysis processing time with span tracing enabled vs. disabled. TBD — Confirmed in Implementation Plan Common §14 (Trace logging overhead budget allocated within PR-29 response time) observability span lifecycle & tracing hooks
parallel PR-26 Worker thread allocation latency and overhead during parallel execution spikes. TBD — Confirmed in Implementation Plan Common §11 (Parallel worker pool resource bounds) parallel worker dispatch loop
access PR-27 Authentication token verification and permission evaluation latency per request. < 2 ms per request RQ-123 (Multi-user concurrency & low-overhead permission checks) access.authorize evaluation path

8. Functional Requirements Accepted in Round 0 (35 Items)

The 35 foundational requirements formally accepted and satisfied in Round 0:

Requirement ID Requirement Title Delivered Scope in Round 0 Responsible Module
RQ-007 Raw Storage Persistence Provides reliable storage primitives for raw files, tables, and serialized objects. store
RQ-008 Transactional ACID Writes Ensures atomic commit/rollback across all write operations. store
RQ-009 Key-Value State Caching Provides fast in-memory and persistent KV caching. store
RQ-015 Structured Event Bus Publishes typed events with topic subscription and wildcard routing. observability
RQ-016 Distributed Trace Propagation Propagates trace IDs across async boundaries and thread pools. observability
RQ-017 Real-Time Progress Reporting Emits progress percentage, intra-step estimates, and heartbeats. observability
RQ-020 Parallel Worker Pool Manages concurrent execution threads with timeout controls. parallel
RQ-021 Asynchronous Task Dispatch Enables non-blocking task execution and callback notifications. parallel
RQ-023 Multi-Provider LLM Gateway Abstracts LLM provider API calls behind a unified interface. llm_gateway
RQ-024 Zero-Cost Local Mock Backend Provides deterministic mock LLM responses for test suites. llm_gateway
RQ-025 Pre/Post LLM Hook Chain Executes hooks for prompt inspection, token counting, and safety. llm_gateway
RQ-026 Formal Contract Envelope Schemas Defines Request, Result, Event, and Error envelope data models. contracts
RQ-027 Immutable Provenance Records Standardizes audit metadata (actor, timestamp, source, reason). contracts
RQ-028 DependencyRef Versioning Provides versioned dependency tracking for lineage and invalidation. contracts
RQ-029 CalcPlan & Step Schema Formalizes calculation plan steps, bindings, and output formats. contracts
RQ-030 Batch Exclusion Log Format Standardizes row inclusion/exclusion records with reason codes. contracts
RQ-031 Node & Value Role Schemas Defines 4 Node Kinds and 3 Value Roles as authoritative types. contracts
RQ-032 Knowledge Tier Enums & Rules Formalizes Needs Confirmation, Approved, and Certified states. contracts
RQ-033 Open/Closed Enumeration Rules Defines extension policies for enum lists across modules. contracts
RQ-071 User Authentication Validates user credentials via multiple authentication schemes. access
RQ-072 Account Registry Maintains registered user accounts and profile metadata. access
RQ-073 Initial Server Admin Bootstrap Creates the primary server administrator upon first installation. access
RQ-078 Declarative Permission Evaluation Evaluates operations against the declarative permissions matrix. access
RQ-082 NodeFilter Generation Generates column/node access masking filters per user role. access
RQ-083 Learning Signal Gating Emits learning signal flag based on user authorization. access
RQ-093 Domain DB Instantiation Provisions a physically isolated database file per domain. domain_lifecycle
RQ-111 Domain Cataloging Registers domain metadata into the system Integrated DB. domain_lifecycle
RQ-114 Domain Creation Events Emits domain_created event upon successful domain setup. domain_lifecycle
RQ-115 First Domain Admin Assignment Assigns the domain creator as the initial Domain Administrator. domain_lifecycle
RQ-123 Multi-User Concurrency Foundation Enables safe concurrent access for multiple user sessions. access · store
RQ-124 Internal User Mapping Maps external authentication IDs to immutable internal user IDs. access
RQ-127 Chat & Query UI Pane Provides interactive conversational interface prototype. ui
RQ-137 Progress Bar & Status Display Renders real-time progress estimates and status badges. ui
RQ-138 Cross-Server Export/Import Scaffold Defines schema migration hooks for domain data export. domain_lifecycle · store
RQ-162 Dual Storage Boundary Isolation Enforces strict physical separation of Domain DB vs. Integrated DB. store

9. User Decision Rules Applied in Round 0 (UR)

The 5 user decision rules governed in Round 0:

Rule ID Rule Title Enforcement & Implementation in Round 0 Responsible Module
UR-02 Deterministic Validation Priority Enforces that deterministic checks execute synchronously within time budgets before invoking asynchronous LLM evaluations. llm_gateway · observability
UR-18 Session Continuity & Draft Persistence Maintains user draft state and conversational context even across temporary network disconnects. access · store · ui
UR-26 Single-Execution Concurrency Lock Applies a mutex lock per domain for heavy asynchronous maintenance tasks to prevent race conditions. store · parallel
UR-27 Distributed Context Propagation Requires all dispatched tasks to carry trace contexts and user authorization tokens. observability · parallel
UR-28 Immutable Provenance Enforcement Mandates non-null provenance audit records on every persisted state modification. contracts · store

10. Permissions Matrix & Input Document Mappings in Round 0

In Round 0, the declarative permission evaluator (access.authorize) is implemented to enforce the 4 primary roles across all server-level and domain-level operations. Supported input documents for R0 include configuration YAMLs, SQL DDL migrations, and account registration payloads.

11. Inter-Module Wiring & Contract Connections in Round 0

The 4 primary inter-module contract connections wired and verified in Round 0:

Connection Kind Contract / Event Name Sender Module Receiver Module Verification Test Suite
Request Contract access.authenticate ui (Shell Login) access Unit & Contract Integration Test
Request Contract domain_lifecycle.create Platform Orchestrator domain_lifecycle Domain Provisioning Integration Test
Event Pair domain_created domain_lifecycle observability → ui Event Dispatch & Subscription Test
Internal Dependency store.connect_domain access / domain_lifecycle store Transactional DB Isolation Test

12. Platform Orchestrator Duties in Round 0

The top-level platform orchestrator (platform) executes the following sequence during system startup:

  1. Bootstrap Sequence: Initializes base storage paths, connects to the Integrated DB, runs pending schema migrations.
  2. Server Administrator Registration: Checks if the initial server admin account exists; if absent, reads installation environment variables to bootstrap the root administrator.
  3. Lifecycle & Event Wiring: Wires the central event bus dispatcher in observability and registers core event handlers.
  4. UI Shell Launch: Starts the web server and binds the UI shell to handle incoming client sessions.

13. Rule Gates Verification for Round 0

Evaluation of mandatory architectural rule gates for Round 0:

Gate # Rule Gate Description Target Scope in R0 Evaluation Result & Evidence
Gate 1 Forbidden Hardcoded Sample Data — Zero hardcoded test domain identifiers in code or prompts. Codebase AST scan across all R0 modules PASSED (Zero hardcoded domain names detected)
Gate 4 User Cognitive Load Minimization — Policy caps on UI top-level navigation screens. ui shell top navigation bar PASSED (Strict single-screen unified workbench layout)
Gate 5 Zero Prior-Round Regression — Cumulative test suite pass rate 100%. Base unit test suite PASSED (100% green on all R0 test suites)
Gate 6 Placeholder Closure — All required R0 placeholders resolved in plan. R0 Planning & Implementation docs PASSED (All R0 placeholders formally resolved)

14. Final Acceptance Scenarios (S1~S10) Status

Full end-to-end user acceptance scenarios (S1 through S10) evaluate complete end-to-end data interpretation capabilities spanning multiple agents (A0~A8) introduced in later rounds. Round 0 provides the necessary underlying harness and passes all prerequisite infrastructure assertions.

15. Implementation Plan Closure Items (CL-01 ~ CL-05)

All wiring details and concrete SQL table schemas are formally closed in the Round 0 Implementation Plan without leaving any open architectural ambiguities.

16. Open Placeholders Registry for Round 0

Authoritative tracking of configuration values and benchmark targets resolved across review reports and implementation plans:

# Placeholder Item Closing Stage Formal Text & Target Default Value Default Source
1 Concurrent Write Latency Benchmark (PR-24) Implementation Plan Target latency under 50 concurrent domain write sessions 100 ms max Default DB Engine Spec
2 Span Logging Overhead Budget (PR-25) Implementation Plan Tracing overhead ratio relative to total execution < 5% overhead Observability Spec
3 Heartbeat Emission Interval (PR-01) Review Report Maximum period between real-time progress heartbeat events 500 ms UI Spec
4 Default Connection Pool Size Implementation Plan Pooled database connections per active domain 10 connections Store Invariant

17. Round 0 Completion Criteria & Quality Signoff

Round 0 is certified complete when all 6 mandatory completion conditions are fully satisfied:

  1. Unit & Contract Tests: 100% of unit, contract, and independence tests pass across all 8 base modules.
  2. Storage & Multi-Tenant Isolation: Physical separation between Integrated DB and Domain DBs is verified under concurrent write stress tests.
  3. Event Bus Verification: Event emission, topic matching, and trace context propagation achieve 100% reliability.
  4. Auth & Permissions: Declarative permission evaluation is verified against all roles in the master permissions matrix.
  5. Zero Code Smells: Static analysis confirms zero circular dependencies and zero higher-level imports in base packages.
  6. Rule Gates Passed: Rule Gates 1, 4, 5, and 6 pass verification audit.

18. Handoff to Next Round (Round 1: Raw Ingestion & Simple Connectivity)

Transition to Round 1 (R1)

With the successful completion and sealing of Round 0, the platform possesses all fundamental infrastructure required to ingest real data.

Incoming Deliverables for Round 1 (R1):

  • loader: Parsing raw CSV/Excel files into Domain DB tables without prior schema documentation.
  • profile: 2-stage scanning and statistical characterization of table columns.
  • connectivity: Construction of the initial multi-layer connectivity graph and path IDs.
  • Agent A6 (Data Analysis Agent): First autonomous agent instance orchestrating map generation.

The solid foundation laid in R0 guarantees that Round 1 and beyond can focus purely on data interpretation, semantic learning, and multi-agent reasoning.

© 2026 Data Agent Platform Architecture Group. All rights reserved.

Published for Tistory Blog · Round 0 Foundation Specification · Multi-Agent Systems

반응형
반응형
250x250
최근에 올라온 글
최근에 달린 댓글
Total
Today
Yesterday
링크
«   2026/11   »
일 월 화 수 목 금 토
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
글 보관함