Application Boundary Baseline

This inventory freezes the observable surfaces and current dependency direction before the 1.0 application-boundaries refactor moves code. It does not declare internal modules public or approve a contract change.

The golden fixtures under tests/fixtures/contracts/ remain authoritative. This page makes their ownership and the current architectural pressure visible in one place so each extraction can be reviewed against the same baseline.

Process Entry Points

  • test-data-agent -> test_data_agent.cli:main
  • test-data-agent-mcp-generator -> test_data_agent.mcp_generator_server:main
  • test-data-agent-mcp-trino -> test_data_agent.mcp_trino_server:main

These entry-point names and targets must continue to resolve throughout the refactor. A thin compatibility wrapper may retain an old target while the composition root moves internally.

Public Python Imports

The exact 66-name test_data_agent.__all__ baseline is protected by public-python-api.json. The exports are grouped below only to show ownership; grouping does not change their compatibility status.

Core data, result, error, and version contracts:

  • DATASET_SPEC_SCHEMA_VERSION, DatasetProfile, DatasetSpec, LocalCategoryField
  • DatasetGenerationResult, DatasetValidationReport
  • CliErrorCode, CliErrorDetail, CliErrorResponse, CliSuccessResponse
  • DoctorCheck, DoctorResponse, DoctorStatus
  • SqlQueryAdapter, SqlQueryProfileLimits, SqlQueryProfileRequest
  • __version__

Agent models and enums:

  • AgentApprovalReceipt, AgentCompletionCheckpoint
  • AgentFieldReference, AgentFieldSummary, AgentGenerationSummary
  • AgentNextAction, AgentPlanSummary, AgentRecoverySummary
  • AgentRelationshipSummary, AgentRequest, AgentResult
  • AgentReviewEntitySummary, AgentReviewFieldSummary
  • AgentReviewReport, AgentReviewSafetySummary, AgentReviewState
  • AgentSourceType, AgentWorkspaceStatus

Advisor contracts:

  • AdvisorContractError, AdvisorExchange, AdvisorExchangeClient
  • AdvisorProposal, AdvisorRequest, AdvisorReviewArtifact
  • DatasetAdvisor, ExchangeDatasetAdvisor

Public operations:

  • advise_agent_workspace, advise_dataset_spec
  • advisor_proposal_json_schema, apply_agent_advisor_proposal
  • approve_agent_workspace, build_agent_advisor_exchange
  • build_agent_advisor_request, build_advisor_exchange
  • build_advisor_request, build_advisor_review_artifact
  • detect_agent_source_type, generate_dataset
  • generate_dataset_bundle, infer_dataset_spec
  • inspect_agent_workspace, plan_agent_profile
  • plan_agent_request, recover_agent_workspace
  • profile_postgres_query_source, profile_trino_query_source
  • review_agent_workspace, solve_constraints
  • validate_advisor_proposal, validate_dataset

CLI Surface

cli-parser-surface.json freezes these 23 commands:

  • generate, export-postgres-sql, profile-example, infer-spec, profile-csv, profile-postgres, profile-query
  • generate-from-csv, validate, generate-from-example
  • demo, doctor, audit-verify, completion
  • agent-plan, agent-approve, agent-recover
  • agent-advise, agent-advisor-request
  • agent-advisor-apply, agent-status, agent-review
  • examples

Compatibility aliases remain:

  • generate-from-csv-folder -> generate-from-example
  • profile-csv-folder -> profile-example

The parser, option defaults, structured success/errors, doctor states, parser-derived completion, human output, and exit-code meanings remain owned by cli_parser.py, cli_contract.py, and cli_presenter.py. Moving handlers out of cli.py must not change those contracts.

MCP Tool Surfaces

mcp-generator-tools.json freezes these generator tools:

  • approve_dataset_plan, export_dataset, generate_dataset
  • infer_dataset_spec, inspect_dataset_plan, plan_dataset
  • plan_trino_dataset, profile_csv, recover_dataset_plan, validate_dataset

mcp-trino-tools.json freezes these default aggregate-only Trino tools:

  • describe_table, list_catalogs, list_schemas, list_tables
  • profile_aggregate_mapping, profile_column
  • profile_conditional_allowed_values, profile_conditional_required
  • profile_foreign_key, profile_formula_rule
  • profile_table, profile_table_safe
  • profile_temporal_ordering

The explicit opt-in row-returning tools are outside that default fixture. run_safe_select is registered only when TRINO_ENABLE_SAFE_SELECT=true, masks every returned string, and does not inherit the default source-literal-free guarantee for remaining non-string values.

Tool names, descriptions, input/output schemas, ordering, audit wrapping, and safety behavior remain compatibility-gated. Transport extraction must not move SQL, path, profile, or generation policy into FastMCP registration. Sensitive numeric Trino columns expose counts, cardinality, sign presence, and decimal order of magnitude only. Exact extrema and percentiles are neither queried nor carried into profiles, specs, or planning artifacts.

Artifact Contracts

The versioned contract catalog contains:

  • advisor-exchange.json, artifact-layout.json, boundary-compatibility.json
  • cli-agent-plan.json, cli-parser-surface.json
  • dataset-spec.json, generation-manifest.json
  • mcp-generate.json, mcp-generator-tools.json
  • mcp-plan.json, mcp-trino-tools.json
  • public-python-api.json, validation-report.json

The review-first agent workspace publishes these stable names:

  • agent_request.json, agent_plan.json, profile.json
  • dataset_spec.yaml, optional advisor_review.json
  • approval_receipt.json, agent_result.json
  • generated/, containing agent_completion.json

Generated bundles retain entity data files plus generation_manifest.json, validation_report.json, and the reviewed spec/profile artifacts. Rule-driven generation may add business_validation_report.json. Additive files or fields still require the existing contract review; rename or removal is breaking.

Current Dependency Direction

The current dependencies after completed extraction increments are:

Owner Current dependencies
__init__.py agent, advisor, core, CLI contracts, generation, I/O workflows, validation, version
cli.py public entry point, parser/presenter contracts, and compatibility wrappers
cli_application.py handler composition and first-owner command dispatch
cli_agent.py agent-* request translation, handler dispatch, lifecycle services, provider adapter, and presenters
cli_commands.py dataset and utility handlers, I/O workflows, audit, demo, rules, and presenters
cli_dependencies.py optional-extra module catalog, injected availability inspection, and normalized installation errors
cli_doctor.py installation diagnostics, synthetic quickstart smoke, and redacted optional-capability smoke orchestration
providers/openai.py, providers/gigachat.py optional provider-specific structured transports behind the provider-neutral exchange; no application authority
agent.py compatibility exports plus deterministic generation and completion validation
agent_contracts.py core field, relationship, and settings models only
agent_planning.py adapters, contracts, core, generation planning, profiling, safety, and workspace-store port
agent_review.py contracts, planning settings validation, bounded artifact readers, profile safety, and injected workspace status
agent_approval.py contracts, review context, bounded artifact readers, workspace-store publication, and injected status/generation ports
agent_recovery.py contracts, review/approval context, bounded artifact readers, workspace-store publication, and injected completion validation
agent_advising.py advisor contracts, review context, bounded artifact readers, atomic spec publication, and injected workspace status
agent_status.py contracts, bounded artifact readers, review/recovery inspection, and read-only lifecycle reconstruction
workspace_store.py typed workspace paths and transitions, core profile/spec models, bounded artifact I/O
io/path_policy.py descriptor-relative no-follow file/folder publication, inode revalidation, and guarded cleanup
Generator MCP server agent, adapters, audit, core, I/O, rules, safety, generator transport factory
trino_config.py environment parsing, credential-free JDBC-style endpoint normalization, validated catalog/schema defaults, typed exact/table-wildcard column selectors, connection settings, allowlist inputs, and resource budgets
postgres_config.py PostgreSQL source identity, credential-free JDBC-style endpoint normalization, connection settings, typed mandatory exact/table-wildcard column selectors, secret indirection, and profiling budgets
postgres_client.py injected-driver PostgreSQL sessions, forced read-only connection settings, cumulative profiling budgets, bounded result fetching, and redacted failures
postgres_query_builders.py allowlisted PostgreSQL metadata, aggregate shape, local category candidate, and relationship coverage queries without source-row access
postgres_profiler.py bounded wildcard metadata expansion plus complete allowlisted PostgreSQL aggregate normalization into qualified DatasetProfile entities and declared relationships
sql_query_source.py bounded local query-file loading, strict PostgreSQL/Trino AST policy, source authorization, wildcard expansion, and source-free fingerprinting
sql_query_profiling.py adapter-neutral no-row schema and aggregate-only virtual-entity normalization without query-row access
sql_query_adapters.py existing PostgreSQL/Trino client/config composition for allowlisted query-source profiling
postgres_sql_export.py deterministic validated PostgreSQL DDL/INSERT rendering and atomic one-file publication without source access
trino_sql_policy.py identifier validation, allowlists, SQL parsing, and bounded read-only policy
trino_query_builders.py typed, parameterized metadata and aggregate profiling query construction without I/O
trino_client.py injected driver access, session resource budgets, result limits, row conversion, and cleanup
trino_profiling.py allowlisted metadata, deterministic wildcard expansion/preflight, and aggregate-only profiling orchestration with injected query fetching
trino_masking.py sensitive-value masking, synthetic category summaries, safe column completion, and opt-in safe-select masking
Trino MCP server audit, extracted Trino config/policy/query builders/client/profiling/masking, compatibility wrappers, Trino transport factory
MCP transport modules optional FastMCP and audit wrapping around supplied callables
generation/profiling/validation/rules core models and pure policy helpers

Exact local category values pass the shared core.privacy content validator before retention. The validator rejects sensitive fields, identifiers, quasi-identifiers, unsupported scalars, sensitive-looking values, free text, excess cardinality, and overlong values without echoing source content.

The two server modules currently import their transport factory to assemble the executable server. agent.py and cli.py remain compatibility owners around their extracted services; mcp_trino_server.py retains responsibilities named in the active OpenSpec. These boundaries are not permission to reverse safety dependencies during extraction.

The target direction remains:

CLI/MCP composition -> application services -> policy/core -> typed ports
                                              -> filesystem/database adapters

Safety policy must be callable below transports. Core and application services must not import CLI presentation or FastMCP registration. Compatibility modules may import extracted implementations temporarily, but extracted services must not import those wrappers back.

Migration Notes

No user migration is required for these internal ownership changes. Public package imports, CLI commands, MCP tools, error behavior, and artifact formats remain available through their existing entry points.

Previous owner Canonical internal owners Retained compatibility entry point
agent.py lifecycle and workspace persistence agent_contracts.py, agent_planning.py, agent_review.py, agent_approval.py, agent_recovery.py, agent_advising.py, agent_status.py, and workspace_store.py agent.py and package-root exports
cli.py composition and command handlers cli_application.py, cli_agent.py, cli_commands.py, cli_dependencies.py, and cli_doctor.py cli.py and the installed CLI
mcp_trino_server.py configuration, SQL policy, query construction, client access, profiling, and masking trino_config.py, trino_sql_policy.py, trino_query_builders.py, trino_client.py, trino_profiling.py, and trino_masking.py mcp_trino_server.py and its MCP tool surface

External callers should continue using the documented package, CLI, and MCP entry points. Internal contributors may import the canonical owners directly. Compatibility wrappers remain in place for the normal compatibility window; their eventual removal would require a separately documented public migration.

Workspace Store Migration

workspace_store.py now owns workspace artifact paths, typed persistence ports, atomic plan publication, and completion-marker publication. agent.py remains the compatibility owner for its existing constants, AgentArtifacts, and agent_artifacts import paths while lifecycle services are extracted.

Planning writes into a sibling staging directory and renames the complete workspace into place only after every artifact is ready. A failed plan restores an existing empty workspace and removes staging data. Completion publishes the approval receipt before the atomic agent_result.json state marker, preserving the existing checkpoint-based recovery behavior.

Planning Service Migration

agent_contracts.py now owns lifecycle models and agent_planning.py owns safe profile-to-plan orchestration. Public package and agent.py imports remain compatible, and workspace_store.py re-exports AgentArtifacts. Direct service calls enforce source-path and profile-safety checks before publishing artifacts.

agent_review.py now owns metadata-only review report construction and review fingerprint refresh. The compatibility wrapper injects inspect_agent_workspace; the extracted service has no reverse dependency on agent.py, CLI, or MCP transports and rejects a replaced spec symlink before reading it.

agent_approval.py now owns the reviewed-fingerprint gate, idempotent completed result handling, and atomic receipt/result publication. Its typed ports inject workspace inspection and deterministic generation without a reverse dependency on agent.py, CLI, or MCP transports.

agent_recovery.py now owns recovery fingerprint checks, interrupted bundle publication, and recovery-state inspection. Its typed validation port preserves tamper detection without importing agent.py, CLI, or MCP transports.

agent_advising.py now owns safe advisor requests/exchanges, persisted proposal resume, and fingerprint-bound spec application. It remains metadata-only and injects workspace inspection without importing agent.py, CLI, or MCP transports.

CLI Doctor Service Migration

cli_doctor.py owns installation diagnostics and local capability smoke orchestration. cli.py retains compatibility wrappers and injects its current module importer and smoke callables. DoctorReport separates human text from typed JSON states and never interprets an import or local smoke as proof of remote configuration or reachability.

cli_dependencies.py centralizes optional-extra discovery and installation errors for doctor capability checks and provider advice. Importers and loaders remain injectable so direct service calls preserve fail-closed behavior.

cli_agent.py now owns review-first agent-* request translation and command handling. cli.py keeps the public entry point and compatibility helpers, then injects those helpers into the extracted handler without changing parser or presenter contracts.

cli_commands.py now owns dataset and utility command handling, including the direct business-rule bridge. cli.py keeps the existing business-rule compatibility helper while injecting doctor and rule dependencies.

cli_application.py now composes the utility, dataset, and agent handlers and dispatches to the first handler that owns a command. cli.py retains the public entry point and a thin run_command compatibility wrapper with its existing test override points.

Trino Configuration Migration

trino_config.py now owns validated connection settings, allowlist inputs, and query resource budgets. mcp_trino_server.py re-exports the existing config types, constants, and parsing helpers for compatibility while consuming the extracted configuration without adding a Trino-client or MCP dependency to that boundary.

Trino SQL Policy Migration

trino_sql_policy.py now owns identifier validation, allowlist enforcement, and bounded read-only SQL validation. mcp_trino_server.py re-exports the existing policy errors, constants, and helpers while using the extracted policy before any client execution.

Trino Query Builder Migration

trino_query_builders.py now owns metadata, aggregate profiling, and rule profiling query construction as typed TrinoQuery values. The builders validate identifiers, keep source values in bound parameters, and perform no I/O. mcp_trino_server.py retains orchestration and compatibility exports while passing built queries to the existing bounded client path.

Trino Client Migration

trino_client.py now owns configured driver connections, fail-closed session resource budgets, a process-wide concurrency cap, client-side result limits, row conversion, and nested cursor/connection cleanup. mcp_trino_server.py retains its existing _execute_query, _fetch_dicts, trino, and error imports as compatibility wrappers while delegating execution to the injected TrinoClient boundary.

Trino Profiling Migration

trino_profiling.py now owns allowlisted metadata inspection, aggregate-only table and column profiling, and count-only rule profiling behind an injected TrinoQuery fetcher. Direct service calls enforce the explicit configuration allowlist before I/O, and condition values remain bound parameters rather than SQL or result metadata. mcp_trino_server.py keeps the existing public tool functions as wrappers and injects the safe column summarizer from trino_masking.py.

Trino Masking Migration

trino_masking.py now owns content-aware value masking, masked sensitive patterns, synthetic category-rank summaries, safe column-profile completion, and opt-in safe-select result masking. Aggregate profiles replace source categories with synthetic labels or masked patterns. Safe-select masking is heuristic: returned rows may retain allowed source values that are not classified as sensitive, so they are outside the source-literal-free guarantee for the default aggregate-only tools. mcp_trino_server.py retains the remaining tool functions and privacy helper imports as compatibility exports while delegating masking below the transport boundary.

Trino MCP Privacy Boundary

The former row-sampling diagnostic is no longer registered or retained as a public Python compatibility wrapper, masking-service method, or query builder. The default aggregate-only tools provide metadata and profiling. The explicit opt-in row-returning tools include run_safe_select, which masks every string recursively inside bounded composite values but is not a source-literal-free replacement for that diagnostic.

Architecture Gate

tests/test_application_architecture.py parses package imports and definitions without importing optional transports. It rejects CLI/MCP dependencies from lower-layer agent and Trino services, domain ownership inside MCP registration, missing direct policy dependencies, duplicate safety-policy definitions, and cycles across the extracted boundary modules.

Per-Increment Review

Each refactor pull request must:

  1. name the responsibility being moved and the old compatibility owner;
  2. preserve the golden fixtures listed above without regeneration;
  3. add direct-service tests for the moved safety boundary;
  4. add or tighten an architecture dependency rule when a new boundary exists;
  5. run the focused tests plus the relevant public contract gates.

See Public Stability for change classification and the active OpenSpec for the staged extraction plan.