qbit-scripting/AGENTS.md

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

./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.