Hooks and the execution pipeline

Every extension point in the Data block is a hook on a five-phase chain: built-in behaviour, schema-declared pointcuts: and triggers:, access rules, computed fields, stateflow guards. They differ only in the phase and priority they occupy. Nothing runs outside the chain.

The five phases

Phase	Runs	Fires on	Still able to change
BeforeValidate	Before any validation, before compilation	every operation	the payload, the query AST, the mutation AST
AfterValidate	After validation, before compilation	every operation	the payload, the query AST, the mutation AST
BeforeExec	After the AST is compiled to SQL, before the statement runs	every operation	nothing that reaches the SQL. The statement is already built
AfterExec	After a mutation statement returns	create, update, delete	the returned rows, response metadata
AfterScan	After rows are scanned and relations eager-loaded	read, and named actions returning rows	the returned rows

AfterExec never fires on a read. AfterScan never fires on an entity create, update or delete, not even one with RETURNING. The mutation path scans the returned rows and goes straight to AfterExec, so read-side hooks (masking, decryption, virtual computed fields) do not touch the row a POST or PUT echoes back.

Operations are a bitmask, create, read, update, delete, and a hook runs when any bit overlaps with the current operation.

Read lifecycle

#	Stage	What it may change
1	Drain gate. A closed engine refuses with exec: engine closed	—
2	Observer timer starts	—
3	Per-request timeout wraps the context, when the request carries one	—
4	Entity resolved from the compiled schema	—
5	A remote entity short-circuits to the HTTP router and returns	skips every later stage
6	AST built from the query, or from filters / select / order_by / limit / offset	—
7	Row cap injected as a LIMIT: see the row cap	the AST
8	Hook context built: identity from the request principal, then asof / version / unmask / untokenize from the request flags	—
9	BeforeValidate	payload, AST
10	AfterValidate	payload, AST
11	AST compiled to SQL; row-level security is injected as a WHERE predicate here	—
12	BeforeExec	nothing that reaches this statement
13	Statement executed on the tenant’s pool	—
14	Rows scanned into both row views	—
15	Includes executed. One extra statement per relation, then children grouped onto parents	rows
16	AfterScan	rows
17	Cursor metadata built	—

Write lifecycle

A write is dispatched by the entity’s history strategy before the standard path runs, the first matching branch wins:

Order	Entity	Path
1	materialization: remote	HTTP router, no SQL compiled
2	Versioned history (type2, type6)	update rewritten to close-current + insert-new; delete rewritten to close
3	typeaudit	pre-image fetched, standard path, then one audit row per changed field
4	type3	pre-image fetched and folded into the payload as <field>_prev
5	type4	standard path, plus a pre-image copy into the history table
6	everything else	standard path

The standard path itself:

#	Stage	What it may change
1	Mutation AST built or accepted from the caller	—
2	?purge threaded onto the mutation	—
3	Payload extracted from the mutation data when not supplied separately	—
4	Hook context built	—
5	BeforeValidate	payload, mutation AST
6	AfterValidate	payload, mutation AST
7	Payload copied back into the mutation AST	—
8	AST compiled to SQL	—
9	BeforeExec	nothing that reaches this statement
10	Placeholders normalised for the dialect	—
11	Statement executed: Query when the mutation has RETURNING, otherwise Execute	—
12	Rows and affected-row count populated	—
13	AfterExec	returned rows

Payload edits after AfterValidate are discarded

Step 7 is the cutoff. The engine copies the hook payload into the mutation AST exactly once, immediately after AfterValidate and before compilation. A hook, pointcut or trigger that writes to the payload at BeforeExec, AfterExec or AfterScan changes nothing in the database and reports no error.

Anything that must reach the SQL belongs at BeforeValidate or AfterValidate.

Ordering

Within a phase, hooks run in ascending Priority. Ties run in registration order, and registration order is fixed by the service’s boot sequence, so the order is deterministic across restarts.

Bucket	Priority	Intended for
Access	100	authorization decisions
Validation	200	input validation
Transform	300	value rewriting
Business	400	domain rules
Infrastructure	500	audit, events, cache

Any integer is legal, and values between buckets (250, 310) are normal. The supported range is [0, 1000].

An out-of-range priority is a warning, not a rejection

A hook whose priority falls outside [0, 1000] is still added, at that priority, after a line is printed to standard error. Ordering is silently corrupted rather than refused.

What data.svc registers

This is the complete chain in the deployable service, in run order. Two rows are conditional; everything else is always present.

BeforeValidate

Priority	Hook	Operations	Does
50	request_options_bridge	all	Copies the query-string flags onto the hook context
100	defaults	create	Fills defaultvalue: on fields the caller omitted
100	access	all	Tier-1 action guards, deny-by-default
150	pointcut dispatchers	per method	The Before* CRUD methods, BeforeAggregate, BeforePurge, BeforeRestore, BeforeSoftDelete, BeforeUpsert
200	validate	create, update	Field validations: and modifiers
250	entityvalidate	create, update	Entity entityvalidations:

defaults and access are both at 100; defaults was registered first, so field defaults are filled before the access guard runs.

AfterValidate

Priority	Hook	Operations	Does
150	audit	create, update	Fills createdby / createdon / updatedby / updatedon
175	temporal	read	Resolves ?version=latest-N against the row’s current version number
176	temporal_type4	read	Redirects a point-in-time read to the history table
190	rls_create	create	Evaluates the RLS create rule in-process. Skipped when row-level security is off
260	filefield	create, update	Stores uploaded file parts. Only when file storage is configured
335	pointcut dispatcher	read	OnRLSFilter
350	businessconstraint	create, update, delete	Multi-entity constraints:
350	stateflow	create, update	State-machine transition legality
360–440	pointcut dispatchers	per method	BeforeTransition (360), BeforeSCDInsert (395), BeforeFieldEncrypt (440)
500	trigger	create, update, delete	before_create / before_update / before_delete triggers

BeforeExec

Priority	Hook	Operations	Does
105	preimage	update, delete	Fetches the pre-mutation row. Runs only for entities declaring an After* / On*Conflict pointcut, or named as the source of a cross-entity refresh trigger
110	pointcut dispatcher	read	BeforeCacheRead
290	materialized	create, update	Evaluates write-time computed fields into the payload: after the statement is compiled. See below
480	pointcut dispatcher	delete	BeforeCascade

materialized sits on the wrong side of the cutoff

The write-time computed-field hook evaluates each expression and writes the result to the payload: at BeforeExec, which is after the payload has already been copied into the mutation and compiled into SQL. The column list and the bound values are fixed by then, so a materialized computed value does not reach the statement. Evaluation errors are still recorded on the response metadata under materialized:error:<field>, which makes a working expression and a discarded one look identical.

Cross-entity refresh is unaffected: the refresh drainer issues its own update with the computed value in the payload, and that goes through the normal write path.

AfterExec

Priority	Hook	Operations	Does
420–545	pointcut dispatchers	per method	AfterTransition (420), the After* CRUD methods (480), AfterCommit (500), OnRollback (510), OnTerminal (530), OnCacheInvalidate (545)
600	event	create, update, delete	Registered with no event bus: returns immediately. See below
650	materialized_refresh_enqueue	create, update, delete	Queues cross-entity computed-field refreshes. Only when the schema declares refresh triggers

AfterScan

Priority	Hook	Operations	Does
260	filefield	read	Resolves stored file references to URLs. Only when file storage is configured
280	computed	read	Evaluates virtual computed fields onto scanned rows
340–540	pointcut dispatchers	read	BeforeFieldDecrypt (340), AfterFieldDecrypt (360), OnFieldMask (420), OnComplianceMask (430), AfterQuery / AfterAggregate (480), AfterCacheWrite (540)

On failure

When an operation fails, the dispatchers that observe that failure run with the error bound as ctx.error, and the operation still fails with its own error.

Failure	Pointcuts
An access rule or gate refused the operation	OnAccessDeny
A stateflow guard refused the transition	OnGuardFail
A duplicate key, or a precondition the row no longer met	OnInsertConflict (create), OnUpdateConflict (update)
The write’s statement failed and was undone	OnRollback

Not currently active

These keys load without complaint and survive validation, but do not take effect at runtime. Use the alternative given rather than relying on the declaration.

Declaration	Use instead
beforeRead / afterRead / beforePurge / afterPurge in the legacy hooks: block, or a triggers: entry on any event other than before_/after_ create, update and delete	Refused at load (can never fire). Use a pointcut for read and purge behaviour
subscriptions: at entity level	Refused at boot on data.svc. See Change streams for the supported path
The legacy string-filter row-security block	Superseded by the predicate translator. Declare rls: under access:. See Row-level security
script-file: on any hook, pointcut, trigger or rule	Only inline bodies execute. Put the script body inline
tx-mode: on a scripted endpoint	Refused at load. An endpoint is not wrapped in a transaction; write the script to be idempotent. See Scripted endpoints

Note

transforms:, compliances: (read-side masking), field-level encryption, enum label resolution and the entity validation hooks are in the chain and take effect. They are listed in the phase table above.

Pointcuts

pointcuts: is the declarative hook surface: a schema author names a lifecycle method and attaches a script. It is entity-scoped only: there is no top-level pointcuts: key, and a top-level block is dropped without a message.

Not the same thing as the published pointcut interfaces

The pointcut interfaces the block publishes over meta.svc are a separate surface with a separate vocabulary, and no code path in the deployed service executes an implementation of one. The pointcuts: block described here is dispatched by the hook chain on every request.

entities:
  - name: sales_order
    pointcuts:
      - method: BeforeInsert
        name: stamp_channel
        language: javascript
        rule: |
          ({ __patch: { channel: ctx.user.roles.indexOf("api") >= 0 ? "api" : "web" } });

      - method: AfterUpdate
        name: notify_downstream
        async: true
        order: 10
        code: ORDER_HOOK_FAILED
        tags: [audit]
        script:
          language: javascript
          expression: |
            data.create("order_event", { order_id: ctx.row.id, kind: "updated" });

Key	Type	Default	Meaning
method	string	—	Canonical method name. Case-sensitive; an unknown value fails the load
name	string	—	Label used in logs, metrics and error messages
group	string	—	Legacy v1 form, backfilled into method when method is absent
language	string	javascript	Engine for the inline rule: shortcut
rule	string	—	Inline body, the shortcut form. Used only when script: is absent
script	mapping	—	Nested script reference; wins over rule:
order	int	0	Tie-break among pointcuts on the same method; lower first
async	bool	false	Run off the request path. Ignored on every Before* method and on OnInsertConflict / OnUpdateConflict / OnGuardFail
code	string	—	Error code surfaced when this pointcut aborts
tags	list	—	Observability labels
enabled	bool	true	Explicit false skips the pointcut at dispatch

file: and func: are not the key names

The nested script: block takes language:, expression:, script:, script-file: and function:, the same five keys as every other script reference on the platform. file: and func: appear in comments and internal examples; they parse to nothing, and the dispatcher skips the empty reference silently.

The methods

Each method runs only when the event its name describes happens.

Method	Phase	Operations	Runs when
BeforeQuery	BeforeValidate	read	Every read
AfterQuery	AfterScan	read	Every read
BeforeAggregate	BeforeValidate	read	A read with an aggregate or a groupby
AfterAggregate	AfterScan	read	A read with an aggregate or a groupby
BeforeInsert	BeforeValidate	create	Every create
AfterInsert	AfterExec	create	Every create
OnInsertConflict	on failure	create	A create meets a duplicate key
BeforeUpdate	BeforeValidate	update	Every update
AfterUpdate	AfterExec	update	Every update
OnUpdateConflict	on failure	update	An update meets a duplicate key or a failed precondition
BeforeUpsert	BeforeValidate	create, update	An upsert
AfterUpsert	AfterExec	create, update	An upsert
BeforeDelete	BeforeValidate	delete	Every delete
AfterDelete	AfterExec	delete	Every delete
BeforeSoftDelete	BeforeValidate	delete	A delete that is not a purge, on an entity with a deletedon field
AfterSoftDelete	AfterExec	delete	The same
BeforeCascade	BeforeExec	delete	Every delete
BeforePurge	BeforeValidate	delete	A purge (?purge=true)
AfterPurge	AfterExec	delete	A purge
BeforeRestore	BeforeValidate	update	A restore
AfterRestore	AfterExec	update	A restore
AfterCommit	AfterExec	create, update, delete	The write has committed: at once outside a transaction, after the commit inside one
OnRollback	AfterExec, on failure	create, update, delete	The transaction the write ran in rolled back, or the write’s statement failed
BeforeTransition	AfterValidate	update	A stateflow transition, after the guard; ctx.from, ctx.to and ctx.event are bound
AfterTransition	AfterExec	update	A stateflow transition
OnGuardFail	on failure	update	A stateflow guard refused the transition
OnTerminal	AfterExec	update	A transition into a final state
BeforeSCDInsert	AfterValidate	create	An insert into a versioned (type2 / type6) entity
BeforeFieldEncrypt	AfterValidate	create, update	Once for each encrypted or tokenized field the write sets, before it is encrypted
BeforeFieldDecrypt	AfterScan	read	Once for each encrypted or tokenized field the read returns, before it is decrypted
AfterFieldDecrypt	AfterScan	read	The same, after it is decrypted
OnFieldMask	AfterScan	read	Once for each field compliance masked, redacted or hid
BeforeCacheRead	BeforeExec	read	The entity cache answers or fills the read
AfterCacheWrite	AfterScan	read	The read’s rows were written to the entity cache
OnCacheInvalidate	AfterExec	create, update, delete	The write invalidates the entity’s cache
OnAccessDeny	on failure	all	An access rule or gate refused the operation
OnRLSFilter	AfterValidate	read	A row rule for read, the entity’s own or one a layer stacked, narrows the read
OnComplianceMask	AfterScan	read	Compliance masked, redacted or hid a field

BeforeBegin, BeforeBulk, AfterBulk, OnBulkChunk, BeforeBulkInsert, AfterBulkInsert, BeforeSCDExpire, AfterSCDClose, BeforeIndex, AfterIndex and BeforeReindex are reserved names: a pointcut declared under one fails the load, naming why and what to use instead. Bulk writes run row by row, so BeforeInsert, BeforeUpdate and BeforeDelete cover each row of a bulk request.

The return-value contract

Script returns	Effect
null / nothing	Continue
false from a Before* method	Abort with the pointcut’s code:, or POINTCUT_ABORT
{ __abort: true, code, message } from a Before* method	Abort with that code and message
{ __abort: true } from an After* or On* method	Recorded on the hook context; the write has already happened, so the request answers as it was
{ __patch: { field: value } } from a Before* method at BeforeValidate or AfterValidate	Shallow-merge into the payload
{ __patch: … } from BeforeCascade	Refused with POINTCUT_PATCH_REFUSED: the statement is already compiled
{ __replace: { … } } from OnInsertConflict	The create answers with this row instead of the conflict error
Anything else	Ignored

Assigning to ctx.payload does nothing, return __patch

The script sees a copy of the payload, not the live one. ctx.payload.channel = "api" mutates the copy and is thrown away. The only supported way for a pointcut to change what gets written is to return { __patch: { … } } from a Before* method that runs at BeforeValidate or AfterValidate.

Failure and async semantics

After* methods plus OnAccessDeny, OnRLSFilter, OnComplianceMask, OnRollback, OnCacheInvalidate and OnTerminal are observers: a script crash there is recorded on the hook context and the operation proceeds. Every other method returns a typed error that aborts the request.

Do not put anything that must not silently fail in an After* pointcut.

async: true sends the work to a process-wide worker pool, 8 workers, a queue of 2048, shared across tenants.

Async pointcuts are dropped under backpressure

The queue send is non-blocking. When the queue is full the task is discarded and a counter increments; the request succeeds. Treat async pointcuts as best-effort. An async task runs with the request’s identity and tenant, so its data.* calls meet the same rules the caller does, and it is not stopped when the request ends.

What a pointcut script sees

One binding, named ctx.

Key	Populated on
ctx.op	Always: create / update / delete / query
ctx.entity	Always. The entity name
ctx.tenant	Always. The full customer:env:product:tenant key
ctx.user.id, ctx.user.roles	Always
ctx.method	Always. The pointcut method name
ctx.metadata	Always. The per-request bag shared across hooks
ctx.payload	Whenever a payload exists. A copy
ctx.row, ctx.rows	Every method that runs once the rows exist: After*, On*Conflict, and the read methods that run after the scan (BeforeFieldDecrypt, OnFieldMask, OnComplianceMask). ctx.row is the first row, ctx.rows all of them
ctx.previous	After* and On*Conflict on update and delete, from the pre-image hook
ctx.from, ctx.to, ctx.event	The transition methods: the states and the event
ctx.error	The methods that run on failure: the operation’s error message
ctx.reason	OnAccessDeny: what the access rule or gate said. OnRLSFilter: the read’s row rules, joined with AND. OnFieldMask and OnComplianceMask: why the values stay masked (unmask was not requested, unmask was not granted, or unmask does not reveal a hidden field)
ctx.fieldName, ctx.field	The field-level methods: the field this run is for, and its type, compliance and modifiers
ctx.headers	Requests over HTTP: the request headers, keyed by canonical name (ctx.headers["X-Access-Reason"]), repeated values joined with , . Headers that carry credentials are left out: Authorization, Proxy-Authorization, Cookie, and any header whose name contains auth, token, secret, password, apikey, api-key, session, signature, credential or cookie
ctx.bulkChunk	Each row of an array create in the operations envelope: { index, total, size, position }. The array is one chunk, so index is 0 and total 1; size is the number of rows and position the row’s place among them, counting from 0
ctx.tx	When the operation is inside a transaction. Opaque to scripts

The field-level methods run once for each field the operation touches: BeforeFieldEncrypt for each encrypted or tokenized field the write sets, BeforeFieldDecrypt and AfterFieldDecrypt for each such field the read returns, and OnFieldMask for each field the read masks, redacts or hides.

Triggers

triggers: is the older declarative surface, and it uses a different binding vocabulary from pointcuts.

entities:
  - name: sales_order
    triggers:
      - name: block_locked_orders
        event: before_update
        priority: 10
        language: javascript
        script: |
          payload.status !== "locked";

Key	Meaning
name	Label used in the abort message
event	before_create / before_update / before_delete: matched case-insensitively
priority	Order among triggers on the same event; lower first
language, expression, script, script-file, function	The script body, inline on the trigger: not nested under a script: mapping

Bindings: tenant, user_id, roles, entity, operation (Create / Read / Update / Delete, capitalized), payload on mutations, rows after a scan.

A before_* trigger that returns boolean false aborts with trigger "<name>": operation aborted by trigger. Any other return value is ignored.

A trigger cannot modify the payload

payload is a copy, and the trigger hook writes nothing back. Assigning payload.order_number = … compiles, runs, and changes nothing. A trigger is a veto, not a transform. Use a pointcut returning __patch, a defaultvalue:, or a computed field.

Writing a hook in JavaScript

js and javascript both select the JavaScript engine; the other accepted language: values are expr (the default when the key is empty), cel, lua, starlark, go and wasm. Anything else fails with script: unsupported runtime. On data.svc only the languages the deployment offers run. By default these are expr, cel, js / javascript, starlark and wasm; lua runs when the deployment lists it in scripts.runtimes (see Configuration), and go is not available on data.svc. A schema that uses a language not offered is refused when the tenant’s engine is built.

The engine is ECMAScript 5.1 with parts of newer editions. There is no module loader, no require, no fetch, and no console: logging goes through log.info(…).

One script engine is built per (tenant, datastore) and cached for the life of that tenant’s data engine. It holds the compiled-script cache, so compilation cost amortises across a tenant’s requests without sharing compiled code between tenants.

Return value

The value of the last expression evaluated is the result. For a guard, return a bool.

Guard results are not coerced: true allows, false denies, and anything else, a string (even "false"), a number, a list, no value at all, fails with rule did not return a boolean. On a request that is 500 with code rule_not_boolean; the operation is refused.

A panic inside a script is recovered and returned as an evaluation error, not a crash.

Globals

Namespace	Functions
data.*	query, find_one, find_by_id, count, exists, aggregate, create, create_many, update, update_many, delete, upsert
schema.*	entity, fields, field, relations, stateflow, field_group. Read-only, no database access
json.*, string.*, math.*, array.*, time.*, template.*, hash.*, log.*	Pure-compute utilities
cept.*	customer, product, environment, tenant: identity strings, always present, empty when the host supplies no identity
Root	ulid(), uuid(), nanoid(), now(), tsnano(), interpolate()

A legacy flat surface is also registered, bare query, queryOne, queryById, count, exists, aggregate, insert, insertMany, update, updateMany, deleteRecord, upsert, getEntity, getFields, getField, getRelations, getStateflow, getFieldGroup, hash, hmac, randomUUID, randomBytes. Prefer the namespaced form: it cannot be shadowed by a tenant-shipped local.

These are the namespaces a script on data.svc sees, in every language. It has no filesystem, network or process access.

data.* re-enters the engine

A data.* call goes back through Engine.Query or Engine.Create, which means it runs the full hook chain again: access rules, row-level security, validation, audit stamping. A script that calls data.update on the entity it is hooked to will re-enter its own pointcuts.

A data.* call carries no request principal

A data.* call from a script runs as the caller. Every evaluation the runtime performs for a request, an access guard, a trigger, a computed field or a pointcut, rebinds the data, schema and flat service functions to that request, so the re-entrant call carries the caller’s user, roles and tenant, is cancelled when the client disconnects, and meets the same gates the caller does: deny-by-default, the action guards and the row rules. A pointcut that writes an entity its caller may not create is refused; in an After* pointcut, which is an observer, the refusal is recorded and the caller’s own operation stands. Background work, the materialization runner and the CLI still call with no principal and are not gated.

Declare an explicit access rule on every entity a script touches. Do not treat the re-entrant chain as a substitute for checking the caller’s rights in the script itself.

Timeouts and limits

Every script runs under a deadline. A hook, pointcut, trigger, rule or computed-field body that does not return is stopped when its budget passes, and the caller is answered instead of waiting on it.

# boot document
scripts:
  timeout: 5s      # the default; `none` removes the bound

The budget never extends the caller’s own deadline. A request with 200 ms left gives its scripts 200 ms, whatever the boot document says, so a client that disconnects stops the script it started. A scripted endpoint’s tx-timeout: replaces the budget for that invocation.

What the caller sees depends on where the script sat. A hook, guard or endpoint script that is stopped fails its operation, and a REST caller gets script_timeout. A virtual computed field is an enrichment, so the read still answers: the field comes back null with a compute_failed warning naming the budget.

Each execution also has a memory budget, scripts.memory (64 MiB by default). WASM modules and the V8 JavaScript runtime (javascript-v8) are stopped when they exceed it; scripts in the other languages are bounded by scripts.timeout. See Configuration.

Stopping a script means stopping the interpreter, which JavaScript, Lua and Starlark each support. A language that cannot be interrupted would release the caller on time and say so in the error rather than report a stop it did not perform.

A worked pointcut

AfterInsert is an observer method, so a failure here is recorded and the insert still succeeds.

entities:
  - name: sales_order
    pointcuts:
      - method: AfterInsert
        name: high_value_approval
        script:
          language: javascript
          script: |
            if (ctx.row.total_amount > 100000) {
              data.create("approval_task", {
                id: ulid(),
                entity: "sales_order",
                ref_id: ctx.row.id,
                opened_by: ctx.user.id,
                opened_at: now()
              });
            }

The data.create call re-enters the engine, so the new approval_task row is subject to that entity’s own access rules, row-level security and validations, evaluated with an empty principal, as above, not with the identity that issued the original insert.

Transactions

Property	Behaviour
Scope	One BEGIN per transactional call, a single-entity POST / PUT / PATCH / DELETE is not wrapped. It is one autocommit statement
Multi-operation envelope	The multi-entity bulk request body runs every operation in one transaction; any failure rolls back all of them
Bulk update	Opens one transaction and issues one full update per record
Isolation	Caller-supplied isolation level, read-only flag, and per-transaction schema. The schema option issues a SET search_path after BEGIN on PostgreSQL
Commit	The callback returning nil commits
Rollback	The callback returning an error rolls back and returns that error
Panic	Rolls back, then re-raises the original panic
Nesting	Refused. A transactional call on an already-transactional engine returns exec: nested transaction not supported. There is no savepoint support
No factory	exec: no backend configured

Compose by passing the transaction down, not by nesting

Two helpers that each open their own transaction cannot be called from one another. The inner call fails at runtime. The inner helper must accept the transactional engine it is given instead of starting its own.

Closing an engine flips a closed flag and polls the in-flight counter until it reaches zero or the context expires. After that every operation returns exec: engine closed without touching the pool. Closing the engine does not close the pool: pool ownership stays with the caller, and several engines can share one pool and drain independently.

Hook coverage on the bulk paths

Request	What runs
Operations envelope (POST, PUT, PATCH or DELETE on /rest with operations[])	Each operation is one write through the full chain, and all of them run in one transaction: a failure rolls every operation back. An array create runs the full chain once for each row, and each row’s pointcuts read its place from ctx.bulkChunk. Update, delete and restore take one row each
Bulk import (POST /bulk, CSV, JSON or JSONL)	Each row is created through the full chain. Rows are read in chunks of ?chunk= rows (1000 by default) and are not written in one transaction: rows created before a failing row stay. With ?skiperrors=true a failing row is skipped and reported, and the import goes on

Every path checks each row against the request’s caller.

Named actions on the chain

A named action runs the same chain as entity CRUD, with the action and its parameters on the hook context instead of an entity payload:

1. Resolve the action and pick the section by HTTP method: GET→read, POST→create, PUT/PATCH→update, DELETE→delete. A missing section is a 405 carrying an Allow header.
2. Validate parameters: unknown names rejected, defaults applied, required and enum enforced.
3. Inject :user_id, :tenant and :roles; force-set {{schema}} and {{datastore}}.
4. BeforeValidate → AfterValidate → render SQL → BeforeExec → execute → AfterExec → AfterScan when rows were returned.

Note the order at the end: on the action path AfterExec runs before AfterScan.

Sharp edge	Detail
{{schema}} and {{datastore}} are never caller-overridable	Identifiers cannot be bound as values, so a caller-supplied override would let a qualified identifier escape into another tenant’s schema
:roles is a comma-joined string	So role IN (:roles) is portable. Split on the comma in SQL for real array semantics
Parameter type coercion is permissive	Only the enum check is strict; the raw value passes through. Do not rely on the declared type for sanitisation

Scripted endpoints and the chain

A scripted endpoint is a whole HTTP handler written in script. It does not run on the hook chain. The request never resolves an entity, so no phase fires. The chain is reached only when the script calls data.*, and then it is the chain of whatever entity that call targets, with no principal on it, the same empty-identity re-entry described above.

Two consequences for the pipeline: an endpoint is not wrapped in a transaction (there is no tx-mode:; the key is refused at load), and its tx-timeout: bounds only what the script asks the engine for, see Timeouts and limits.

Errors

The HTTP layer classifies by error type first, access denial 403, validation 422, not-found 404, and falls back to matching the message text for untyped errors: access denied / not authorised / not authorized / forbidden → 403, not found → 404, validation / invalid / is required → 422, everything else → 500, the full status rules and the code table are on error codes.

Message	Raised by	HTTP
hook <name> (<Phase>): <cause>	Wrapper applied to every hook failure. The form the log shows. The API sends <cause> as the message and puts hook and phase in details	from the cause
access denied (tier <n>): <reason>	The access hook refused the operation	403
the rule’s own message:	Field or entity validation refused the write	422
invalid transition on <entity>.<field>: <reason>	The stateflow refused the transition	422
trigger "<name>": operation aborted by trigger	A before_* trigger returned false; a validation failure with code TRIGGER_ABORTED	422
the pointcut’s own message	A Before* pointcut aborted: returned false or { __abort: true, … }. details.code is the abort’s code (else the pointcut’s code:, else POINTCUT_ABORT), details.pointcut its name, details.method the method	422
pointcut <Method>/<Name>: <cause>	A synchronous pointcut script failed; details.code is the pointcut’s code: or POINTCUT_ERR, details.cause the script’s failure	500
exec: entity not found	No rows matched, or the named action is not registered	404
exec: forbidden	The database refused the statement: insufficient privilege	403
exec: validation failed	The database refused the statement: not-null or check violation	422
exec: conflict	Duplicate key or foreign-key violation	409
exec: engine closed	An operation arrived after shutdown began	500
exec: nested transaction not supported	A transaction was opened inside a transaction	500
exec: no backend configured	No transaction factory is wired	500
exec: no compiler available	No SQL compiler for the backend	500
POINTCUT_ABORT	Default code for a Before* pointcut returning false or __abort without a code	—

The exec: and hook … (…): prefixes in this table are the engine’s own and never reach a client. The API’s message is the innermost cause; what the engine knows about where it came from, hook and phase, the validation rule and its code, the database’s SQLSTATE and object names, travels as details. See error codes. | POINTCUT_ERR | Default code for a non-observer pointcut script crash | — | | script: unsupported runtime | The language: token is not one of the eight accepted values | 500 | | script: expression did not return a boolean | A guard returned a non-coercible value | 500 | | script evaluation: file-referenced scripts not yet wired | A script reference used script-file: with no inline body | 500 | | pointcut "<name>": unknown method "<m>" | Schema-load failure. The method name is misspelled or unsupported | load fails |

An abort is the caller’s 422; a crash is the product’s 500

A pointcut abort is the product refusing the request, so it answers 422 whatever its code: says, the code travels in details.code for the client to branch on, never picks the status. A pointcut whose script crashed is a defect in the product, not in the request: 500, with the failure in details.cause.

Sharp edges

• Payload edits stop mattering after AfterValidate.
• AfterScan does not run on entity writes, so a created row is echoed back unmasked and without virtual computed fields.
• after_* triggers run after the write; events: publishes to the change stream a subscriptions: block serves; transforms: and field encryption load and do not run.
• The beforeRead, afterRead, beforePurge and afterPurge slots of the legacy hooks: block are refused at load: no phase would fire them.
• A trigger cannot modify the payload; a pointcut must return __patch to do so.
• The write-time computed-field hook runs one phase too late for its value to reach the column.
• async: true is ignored on every Before* method, and async work is dropped under backpressure.
• A crash in an After* pointcut is swallowed.
• script-file: never executes in a hook, pointcut, trigger or rule.
• A data.* call from a script re-enters the chain as the caller: the same user, roles and tenant, the same gates.
• Transactions do not nest, and a single-record write over HTTP is not in one.

Continue with

Concern	Page
The four access tiers and their rule vocabulary	Access rules
Rule-to-WHERE translation and its failure mode	Row-level security
Declarative field and entity rules	Validations
State machines, guards and transition scripts	Stateflows
Computed fields, virtual and materialized	Fields
History strategies and what each one writes	Entities
Query-string flags the bridge hook reads	Request flags
Custom HTTP routes implemented in script	Scripted endpoints
The published pointcut interfaces	Pointcuts
Entities served over HTTP instead of SQL	Remote entities
Endpoint-level HTTP reference	Data API reference