Skip to main content

Architecture & Compliance

TeaQL offers reviewable boundaries for generated data access. These mechanisms can support a secure or regulated application, but they do not establish SOC 2, GDPR, PCI DSS, tenant isolation, or audit completeness by themselves.

Current evidence boundary: generated Rust 4.1.1 query and mutation contracts, teaql-tool-core 1.0.0 environment parsing, evaluator Markdown reports, generated masking metadata, and SQLite Golden Path execution have been reviewed or executed. Custom authorization policy, safe-event sink output, non-SQLite providers, and deployment isolation require application evidence.

Runtime Context Is an Enforcement Point​

Generated queries execute through the runtime context. This gives an application one place to supply repositories, provider configuration, actor and tenant resources, and request policy.

The context does not authenticate a caller, infer ownership, or create a tenant filter automatically. The application must:

  1. validate identity before constructing context resources;
  2. reject missing or inconsistent tenant/actor state;
  3. register the intended policy for every generated request path;
  4. cover list, single-record, aggregate, association, mutation, background, and administrative operations;
  5. test raw/custom provider access as a separate bypass surface.

Use Multi-Tenant Query Boundary for the design and negative-test matrix. Model-specific checker method names must be read from current generated source rather than copied from an illustration.

Intent and Audit Are Declarations​

Maintained generated reads end with:

comment -> purpose -> execute_for_xxx

Maintained generated mutations use:

audit_as -> save/update

These contracts make an operation and its stated reason visible. They do not prove that the reason is truthful or that the actor is authorized. Audit descriptions must be combined with verified identity, policy, transaction, and sink behavior.

Sensitive-Field Metadata​

_audit_mask_fields and _audit_value_max_len can be carried into generated entity metadata and consumed by compatible safe-audit paths. Current evidence includes evaluator guidance for an email field and regenerated masking metadata; maintained safe-sink execution for every value and failure path is still pending.

Do not assume masking applies to database values, API responses, exceptions, custom logs, traces, exports, backups, or a sink that consumes raw events. Masking is also not encryption, tokenization, authorization, or deletion. See Sensitive Field Audit Masking.

Evaluator Findings Are Versioned Evidence​

Current evaluation returns a Markdown report with errors, warnings, suggestions, solids, rule IDs, and targets. A reproduced email-field probe produced a privacy suggestion; it did not halt evaluation. Therefore:

  • fix blocking errors before generation;
  • review warnings and suggestions explicitly;
  • do not claim every sensitive keyword is blocking;
  • do not describe the output as a JSON report unless the selected client actually produces one;
  • retain the complete report and exit status.

See Reading Markdown Reports.

Rust Code Is Not Automatically Sandboxed​

Generated intent wrappers constrain specific generated operations. Arbitrary handwritten Rust can still use networking, files, processes, environment variables, database clients, unsafe code, or new dependencies when the build and operating system permit it.

Projects can add Clippy restrictions and dependency policies, but those are application-owned build controls. Their coverage depends on the exact lint configuration, workspace membership, allow attributes, generated code policy, and CI enforcement. Combine them with container/host restrictions, outbound allowlists, scoped credentials, and code review.

The released teaql-tool-core 1.0.0 module labels are audit-filter labels, not proof that executable HTTP, filesystem, command, email, or queue capabilities exist. See Rust Agent Tool Boundary.

Environment and Schema Controls​

Current generated workspaces parse TEAQL_AUDIT, TEAQL_SQL, TEAQL_SQL_TABLES, TEAQL_TOOL, TEAQL_TOOL_FOCUS, TEAQL_SINK, and TEAQL_SCHEMA. The parser rejects unknown protected variable names, unknown focused modules, and unknown generated table names.

Although TEAQL_SCHEMA accepts _verify, _dryrun, and _execute, the currently generated runtime calls ensure_schema() in all three branches. Do not present _dryrun as non-mutating or as a production safety boundary until the implementation is fixed and verified against the selected provider.

The older names ending in _LOG belong to a separate formatter compatibility layer. Use Environment Variables for the exact parser, values, defaults, and caveats.

Architecture Review Checklist​

  • Identity and tenant resources are validated before policy execution.
  • Every query shape has positive and negative authorization tests.
  • Every mutation declares audit_as and has transaction/failure tests.
  • Raw SQL, custom repositories, background jobs, and admin paths are inventoried.
  • Evaluator findings and regenerated diffs are reviewed.
  • Every audit/log sink is tested for masking, access, delivery, retention, and failure.
  • Provider/database credentials and deployment permissions use least privilege.
  • Network, filesystem, process, and dependency restrictions exist outside TeaQL.
  • Schema behavior is tested on a disposable database before production use.
  • Compliance claims map to concrete organizational and technical evidence.

For the complete responsibility map, use Security and Trust Boundaries.