f0d695ec97
QRun-IO/ci-policy: ci / fork-guard (push) Skipped
QRun-IO/ci-policy: ci / head-profile (push) Skipped
QRun-IO/ci-policy: ci / application-template-0 (push) Skipped
QRun-IO/ci-policy: ci / gradle-1 (push) Skipped
QRun-IO/ci-policy: ci / java-docker-3 (push) Skipped
QRun-IO/ci-policy: ci / java-docker-4 (push) Skipped
QRun-IO/ci-policy: ci / java-frontend-browser-5 (push) Skipped
QRun-IO/ci-policy: ci / java-maven-6 (push) Skipped
QRun-IO/ci-policy: ci / java-maven-7 (push) Skipped
QRun-IO/ci-policy: ci / node-8 (push) Skipped
QRun-IO/ci-policy: ci / node-9 (push) Skipped
QRun-IO/ci-policy: ci / node-10 (push) Skipped
QRun-IO/ci-policy: ci / node-playwright-11 (push) Skipped
QRun-IO/ci-policy: ci / repository-policy-12 (push) Skipped
QRun-IO/ci-policy: ci / source-config-13 (push) Skipped
QRun-IO/ci-policy: ci / source-config-14 (push) Skipped
QRun-IO/ci-policy: ci / android-0 (push) Skipped
QRun-IO/ci-policy: ci / original-business (push) Skipped
QRun-IO/ci-policy: ci / original-mcp (push) Skipped
QRun-IO/ci-policy: ci / original-voyage (push) Skipped
QRun-IO/ci-policy: ci / original-cli (push) Skipped
QRun-IO/ci-policy: ci / repository-policy (push) Skipped
QRun-IO/ci-policy: ci / java-core-2-head (push) Skipped
QRun-IO/ci-policy: ci / java-docker-3-head (push) Skipped
QRun-IO/ci-policy: ci / java-maven-6-head (push) Skipped
QRun-IO/ci-policy: ci / java-maven-7-head (push) Skipped
QRun-IO/ci-policy: ci / not-enrolled (push) Failing after 7s
QRun-IO/ci-policy: native / fork-deny (push) Skipped
QRun-IO/ci-policy: native / dotnet-0 (push) Skipped
QRun-IO/ci-policy: ci / ci-result (push) Failing after 6s
QRun-IO/ci-policy: native / native-result (push) Successful in 6s
Save the current implementation and README, status, and known-issue documentation at the user-requested stop. No completed release or deployment is claimed. Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: GPT-6 Codex <noreply@openai.com>
56 lines
3.9 KiB
Markdown
56 lines
3.9 KiB
Markdown
# 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.
|