# AGENTS.md

Guidance for coding agents working in this repository.

## Project Overview

**QBit Scripting** (`qbit-scripting`): shared script projects, immutable strict-TypeScript builds, capability broker and record lifecycle hooks for QQQ. Current state and the production gate: `docs/STATUS.md`.

This QBit never executes script code and never compiles it in the JVM. Compilation and execution belong to an external, isolated worker behind `WorkerProvider`; with no qualified provider every operation fails closed.

## Build Commands

```bash
./mvnw compile    # always use the wrapper: machine Maven 3.10 cannot read the parent POM
./mvnw verify     # Checkstyle (validate phase, tests included) + unit tests
```

## Architecture

Entry point: `ScriptingQBitProducer` (`QBitProducer`, same style as qbit-printing) with `ScriptingQBitConfig`. Packages under `com.kingsrook.qbits.scripting`:

- `source` - `SourceFile`, `SourceSnapshot` (hashed, immutable), `GitCommitRef` + optional `GitSourceImporter` interface.
- `build` - `BuildCoordinator` (the only signer/verifier of artifacts), `ArtifactSubmission`, `BuildOutcome`.
- `worker` - `WorkerProvider` seam, `WorkerMessages` + `WorkerProtocol` (bounded JSON), `UnconfiguredWorkerProvider`.
- `capability` - `CapabilityDeclaration`, `CapabilityBroker`, `RecordReader`/`QqqRecordReader`.
- `hooks` - `HookEvent`, `HookResult`, `ScriptHookCustomizer` (a `TableCustomizerInterface`).
- `service` - `ScriptingService` (draft/check/test/publish/bind), `ScriptExecutor`, `ScriptSourceRegistry`, `ScriptingStore`, `Actor`.

Dependency rule: nothing imports document-generation, record-files, mobile or printing. Core only (`qqq-backend-core`).

## Invariants

- Draft sources live in the existing core `script` / `scriptRevision` / `scriptRevisionFile` tables; this QBit appends immutable revisions. Only publication advances `script.currentScriptRevisionId`, through reviewed core isolation authority in the same transaction; drafts never activate. No second registry.
- Tables `scripting_*` are readable with `scripting.view` and writable only by the system session the service switches to after authorizing a named `Actor` (`ScriptingTablePermission`).
- Lifecycle permissions are separate and never imply each other: `scripting.draft|check|test|publish|bind`.
- An artifact is accepted only if `BuildCoordinator` verified source hash, pinned toolchain, bundle hash and its HMAC attestation; this is re-checked before every execution.
- A binding names a publication; later drafts/builds/publications never change what it runs.
- Native hooks support PRE_INSERT/PRE_UPDATE patches only in authorized early phases, PRE_DELETE veto, and read-only POST_INSERT/UPDATE/DELETE observations. Pre failures veto; post failures warn because the backend action already occurred. Never call a post callback "after commit". Native validation owns field constraints; do not duplicate it.
- No Nashorn, Node `vm`, shell eval, embedded JS engine or regex "type checking" anywhere, and no tests that execute hostile code. Tests use the protocol-level `FakeWorker`.
- Worker messages carry no credentials, sessions or Java objects; capability tokens are opaque and scoped; reads are read-only.

## Naming

- Tables: lowercase snake_case, prefixed `scripting_`. Permissions: `scripting.<action>`.

## Code Style

- 3-space indentation, opening braces on the next line, `return (x);`.
- Javadoc flower-box banners on every class, record, enum, constructor and method, including private ones and tests (Checkstyle enforces this and the license header).
- Explicit imports only, grouped java.*, third party, static; no wildcard imports.
- Fluent setters (`withX()`) for configuration. No mutable global singletons.

## Dependencies

- Java 21. Parent `com.kingsrook:qbit-build-parent:2.0.0`, QQQ `4.1.0-RC.21` modules (public). NOTE: the source needs core APIs that RC.21 does not contain; see `docs/STATUS.md`. Tests: JUnit 6.0.1.