ConfigLoader - Unified configuration file loading for business services
Single responsibility: Load all service configuration files from standardized locations with consistent error handling.
CENTRAL REGISTRY of the paths this package owns. Both configs below are
mandatory: neither has a default and neither is skippable, so a service
missing one does not boot — loadServiceConfig() and loadOperations()
throw, naming the absolute path they tried. That is where "required" is
stated; the registry entries carry no such field, because nothing read one
(d.772, change-discipline.md § Removing something removes its declaration).
One more path stands in that registry, and it is NOT a config this loader loads:
Usage: const { ConfigLoader } = require('@onlineapps/service-wrapper'); const config = ConfigLoader.loadAll({ env: process.env });
Design principle: ONE place to define where every config lives, and to load
the two that are configs. Validation of their CONTENT is not here — the
shape of operations.json is @onlineapps/conn-orch-validator's subject;
this loader checks only that the file parses and carries its top-level key.
Infrastructure orchestration for microservices. Thin layer that delegates all work to specialized connectors.
Shared logger proxy for business services.
Handlers, services and controllers are required at module load time, long
before wrapper.initialize() has produced a real logger. This module is the
late-binding indirection between the two: bootstrap calls setLogger() once,
every consumer calls getLogger() whenever it actually logs.
Fail-fast, no fallback. If getLogger() is reached before setLogger(), that
is a wiring defect and it throws — it does NOT hand back a console-shaped
substitute. A silent console fallback makes a service that lost its real
logger look healthy: the log lines still appear on stdout, while nothing
reaches the monitoring connector, the log files or the correlation context.
See architecture-principles.md §3 (No Fallbacks) and §4 (Fail-Fast).
Consumers call getLogger() at call time, never at module scope — binding
the result into a module-level constant would capture the state before
bootstrap and defeat the indirection.
redactedInputGuard.js — a redacted copy of the input never reaches a handler.
@onlineapps/logger-contract redactSensitiveDeep replaces the value of
every declared sensitive field with REDACTED_PLACEHOLDER in the copies made
for logs, traces and events (SecretBox §8). Those are observability copies.
The execution message — the one that carries the value to its owning handler
— must never be one of them: a handler handed the placeholder authenticates
with the string, stores it as a password or sends it as a token, and the run
reports success.
This wrapper redacts nothing. It GUARDS, in invokeOperation(): every
declared sensitive field whose value IS the placeholder — matched by key name
at any depth, the way redactSensitiveDeep matches — refuses the message
with InvalidEnvelopeError (400 INVALID_ENVELOPE) before the handler runs.
The refusal names the FIELD, never a value.
Where the rule comes from (lead's decision N1, 0.2b-1053):
sensitive_input_fields: the recipe's
rule, the sorted unique union of every operation's declaration
(@onlineapps/conn-orch-orchestrator _executeTaskStep), and the guard
applies exactly that;_dispatchViaInvokeOperation), which has no recipe, so its rule is the
operation's own operations.json declaration — read through the ONE
reader of that declaration, sensitiveFieldsForOperation;The walk below is deliberately minimal and local: logger-contract exports
the placeholder and the declaration reader, but not a walk that FINDS a value
without copying the tree (redactSensitiveDeep clones and replaces). Lifting
this walk into logger-contract beside redactSensitiveDeep is a candidate
for that package, recorded as a finding of d.1280 — until then this is the
one implementation in this package.
The deadline of ServiceWrapper.shutdown() — one watchdog, armed before the first
teardown step, that ends the process when the teardown does not.
Owner's decision: api/docs/governance/confirmations/biz-shutdown-deadline.md 001 (d.1102
measured, d.1105 built). Without it a teardown against a Redis or a broker that holds
the connection and never answers never ended: bootstrap()'s process.exit(0) never
came, and on the fatal path — where nothing sends a SIGKILL — the process stayed up,
dead, for good.
The process edge (writeStderr, exit) is injected; nothing here touches process.
The SIGTERM/SIGINT handler bootstrap() installs — the one place a signal becomes a
teardown and an exit code.
Owner's decision: api/docs/governance/confirmations/biz-shutdown-deadline.md 001 — exit 0
only after a clean teardown, exit 1 when shutdown() rejects, and a second signal
during a running teardown is ignored. Until d.1105 the handler was
await wrapper.shutdown(); process.exit(0) on both signals: a rejected teardown ended
the process on an unhandled rejection instead, and a second signal started a second
teardown over the first (d.1102).
A teardown that never settles is not this handler's business: the deadline armed
inside shutdown() ends it (shutdownDeadline.js).
The deadline of ONE ATTEMPT of a step — how long this wrapper lets an operation's handler run before it abandons the attempt.
Owner's word (conf step-error-classification 005 — variant A, a deadline
per ATTEMPT per operation): the deadline
is per operation, declared as timeout_ms in config/service/operations.json
beside retry; an operation that declares none gets the platform default;
a declaration outside the platform range is refused by the operation's name,
never replaced by the default — the rule retry follows in
@onlineapps/conn-orch-orchestrator (retryPolicy.js).
The numbers — the platform default and the range — are not this module's:
@onlineapps/handler-contract owns them (STEP_TIMEOUT_MIN_MS,
STEP_TIMEOUT_MAX_MS, DEFAULT_STEP_TIMEOUT_MS), and this module reads
them and keeps no copy (conf handler-contract 002, d.1382). It exports
DEFAULT_STEP_TIMEOUT_MS, MIN_STEP_TIMEOUT_MS and MAX_STEP_TIMEOUT_MS,
which are those values.
The wrapper ENFORCES it (ServiceWrapper.invokeOperation races the handler
against it and aborts ctx.abortSignal); whether a timed-out step is tried
again is the orchestrator's decision (005: a reading operation by the retry
policy, a writing one straight to workflow.failed) — the attempt ends with a TIMEOUT-class
error (StepTimeoutError, 504 STEP_TIMEOUT), and status 504 is
ErrorTypes.TIMEOUT in @onlineapps/error-handler-core ErrorClassifier.js.
ContextBuilder — assembles an OperationContext for a single invocation.
Contract: api/docs/biz/10-invocation/operation-context.md and api/docs/biz/10-invocation/handler-dispatch.md Layer: L3 orchestration (see ARCHITECTURE_PRINCIPLES.md §7).
./OperationContext and the error CLASSES from ./ErrorMapper
(L2 types, no behaviour — ErrorMapper itself imports nothing, so there is
no cycle; ./OperationContext already depends on the same module).
MUST NOT import HandlerRegistry or SchemaValidator, and MUST NOT call
ErrorMapper.map() — mapping stays the wrapper's job.SRP: single job — translate (mqMessage, operationSpec) into a ready-to-use OperationContext plus a release() hook the wrapper must call after the handler returns (success or failure).
A handler broke the error contract — it raised a code the wrapper produces.
Deliberately NOT branded and carrying no code of its own: it is not a
business outcome, it is our defect, so ErrorMapper takes it down the
unhandled-fault branch — error level WITH the stack in the log, and a masked
500 INTERNAL_ERROR to the caller
(api/docs/biz/70-contracts/error-handling.md §5). A code of its own would be
a platform-wide identity, and that dictionary is added to by changing the
contract node, not by a library minting a name.
ServiceWrapper class Collection of connectors that enhance business service with infrastructure
The code an error gets when nothing about it was declared.
The code a BRANDED error gets when its shape is broken — our own defect.
ReadonlySet.<string>The codes this file puts on an envelope when the failure declared NOTHING.
They are the opposite of every other code the table produces: the rest are a
handler's (or the wrapper's) statement about an outcome, these two are the
absence of one. An INTERNAL_ERROR envelope means an unbranded error nobody
classified; MALFORMED_BUSINESS_ERROR means an error that claimed the brand
and broke the shape.
Exported because an envelope loses the distinction otherwise. Once
ServiceWrapper._dispatchViaInvokeOperation() rebuilds a failure as a plain
Error with code and status, a masked 500 INTERNAL_ERROR is shaped
exactly like a declared 500 DATA_INTEGRITY_VIOLATION, and only this list
separates them (ServiceWrapper._classifyDeliveryError() — an undeclared
failure keeps its delivery attempts, a declared one does not).
ReadonlySet.<string>The codes whose dictionary row declares that a retry is meaningful.
A code's declared identity is not only its name and its status: the accepted
dictionary carries a Retry column, and that column is part of what the code
means platform-wide. PROVIDER_UNAVAILABLE is the row that says yes.
Owner: api/docs/biz/70-contracts/error-handling.md § Accepted domain codes —
a row there is the fact, this list is only the machine-readable side of it, so
a code joins or leaves this set when that table changes and never otherwise.
❌ Not a flag on an error instance: which codes may be retried is a property
of the contract dictionary, not of one throw
(.claude/rules/single-source-of-truth.md).
Read by ServiceWrapper._classifyDeliveryError(): such a code keeps its
delivery attempts, exactly as an undeclared failure does, while every other
declared business code is settled on the first delivery (d.547).
HandlerLoader
L3 Orchestration helper used by HandlerRegistry. Resolves v3 handler
references of the form "relative/path#exportName" to actual exported
functions, relative to the host service's source directory.
Layer: L3 (Orchestration). Pure filesystem + require. No cross-imports from other wrapper modules.
Service Wrapper - Collection of connectors for business services
Provides infrastructure components in single-process architecture:
Uses HTTP pattern exclusively - no direct handler calls
The error codes this wrapper produces about its own dispatch, with what a handler that means the same thing throws instead.
The dictionary of codes, and which of them belong to the wrapper rather than to a handler, has one owner — the nodes cited below, not this comment.
CLIENT_CANCELLED is deliberately NOT here. ErrorMapper matches it on the
error's name outside the brand contract, because the abort it must
recognise is Node's own AbortController DOMException — which a handler
awaiting an aborted call legitimately propagates.
Until this Map existed nothing enforced the split: a handler lives in a
service repository, which review here never sees, and the cost of missing one
is not cosmetic — see _invokeHandlerUnderContract().
The orchestrator major the wrapper's v3 invocation model requires.
ONE constant: the guard below branches on it and the refusal names it, so the
sentence an operator reads cannot drift from the comparison that raised it
(change-discipline.md § One rail per concern). WHICH released version
carries this major is not written here — that is the platform SSOT's fact
(api/config/libraries.json), and a number copied into a message is a
descriptive fact maintained by hand (doc-code-binding.md §1).
The PLATFORM env key that owns the deadline of one discovery lookup (d.1093). Named
once here, so renaming it is one edit in this package; its declaration (why, consumers,
value) is api/config/shared-env.json.
What an operator should do next about a failed boot phase, carried ON the
error rather than decided at the catch that reports it.
FÁZE 0.3 already worked this way — it reads error.code !== 'MQ_CONNECTION_FATAL'
off the error @onlineapps/mq-client-core threw, because only the layer that
produced the failure knows whether asking again can change the answer. This is
the same rail, named once and readable by every phase that has more than one
disposition.
A phase whose failure is always of one kind (0.12, 0.15, 0.10) passes its constant and reads nothing — the marker is for the phases where the disposition is a FACT about the failure, not about the phase.
The Tier-1 steps that read NOTHING but the files already on disk.
@onlineapps/conn-orch-validator 10.0.0 runs seven steps and reports each one
under its own key in result.steps (ValidationOrchestrator.runFullValidation()):
1 structure the service tree — ServiceStructureValidator
2 config config/service/*.json
3 env the env contract the service declares
4 operations operations.json against the v3 shape
5 cookbooks the service's own recipes, RUN against handlers and DB
6 connectors warnings only — it can never fail a validation
7 manifest the uniform, measured on the checkout
Five of them decide from files alone. A verdict of theirs is the same on the
next attempt and on the attempt after that, because nothing between two
attempts changes what they read — so retrying is not caution, it is 18,5 minutes
of a boot that cannot succeed (measured twice: biz-converter exit 1 after
18 min 53 s, W591 on MISSING_COOKBOOKS). Step 5 is the one that depends on the
world around the service, and it is the one that keeps the budget.
The classification reads the STEP, never the message: result.errors is one
flat array into which step 1 pushes objects and steps 2/4/5/7 push sentences
(that mixture is why describeValidationFinding() exists), so a message tells
an operator what happened and tells this code nothing it can decide on.
The cached health signal each dependency component keeps, by component name.
ONE place says which components there are and where each one's last verdict
lives, so refreshDependencyHealth() writes the field and
_recordDependencyHealth() compares against it without either of them
spelling the field name again.
The wrapper.errorHandling keys this package forwards to
@onlineapps/conn-infra-error-handler. Named, not spread: a key outside this
list configures nothing in the core, and forwarding it blindly would let a
misspelling pass in silence.
dlqEnabled left the list in d.493, for the reason
@onlineapps/error-handler-core retired it (that package's CHANGELOG,
### Removed — DLQRouter): the core stopped reading the key, so forwarding it
configured nothing. It is not merely dropped — a config still writing it is
REFUSED by name (_assertRetiredDlqEnabledKey).
maxRetries, retryDelay and retryMultiplier left it in d.1264 and are
refused the same way (RETIRED_RETRY_KEYS).
The three wrapper.errorHandling keys that configured RetryHandler of
@onlineapps/error-handler-core, retired in d.1264 and REFUSED by name
(_assertRetiredRetryKeys).
Nothing on this package's path read what they configured: the orchestrator
calls the connector's classifyError() only, and this wrapper its
logError() only — neither reaches retryHandler. A step is retried by
@onlineapps/conn-orch-orchestrator under the retry policy of its operation,
declared as retry in operations.json and handed over by the
operationMutatesLookup hook (conf step-error-classification 002 variant B;
004: "wrapper.errorHandling.* is removed"). The four § Removing questions
are answered in this package's CHANGELOG, [Unreleased] — Removed.
The restart cooldown window, and ONLY that: how long a service that failed
validation for the SAME cause waits before it tries again after a restart
(_applyRestartCooldown()).
It is not a schedule. Until d.755b a third ladder stage slow_backoff claimed
it as one — a 6-hour retry forever — and nothing ever entered that state, so
the claim was never true. The ladder ends at the hourly ceiling with a fatal
teardown, which is the documented end of the road.
Every state the re-validation cycle can be in. TWO backoff stages, because
two is what the concept declares: fast ladder, then hourly up to the ceiling,
then _shutdownFatally() — "there is no third retry phase"
(api/docs/architecture/validator.md - Re-Validation Backoff Schedule).
The provenance mark: this error was raised by the wrapper, not by a handler.
booleanIs this envelope value a usable tenancy id?
The rule comes from the wire contract, not from this file:
api/docs/biz/10-invocation/mq-envelope.md declares envelope.tenant_id an
integer and says "Positive integer.". Zero is explicitly not a value
(api/docs/biz/20-tenancy/multitenancy.md §1.6; the tenant-wide scope was
retired by the owner on 2026-09-03).
A decimal STRING is accepted alongside the number because that is what
already crosses this boundary and is forwarded unchanged — the builder
validates, it never converts. The accepted string form is exact: no sign, no
leading zero, no whitespace, no decimal point, so "5" passes while "05",
" 5", "5.0" and "-5" do not.
booleanIs this envelope id missing?
ONE predicate for workflow_id, correlation_id and step_id — three
fields of the same kind, so a value that is a value for one of them is a
value for all three. Until d.363 the first two were checked with
.length === 0 and the third with .trim() === '', so an id of nothing but
whitespace passed two guards and was refused by the third, inside one method.
The value that got through is not harmless: workflow_id and step_id name
the storage prefix content/<workflow_id>/<step_id>, and correlation_id is
what a trace is joined on.
It refuses blankness and NOTHING else. An id with real content and spaces
around it is a value and is forwarded exactly as published — trimming it here
would be the builder inventing a second spelling of somebody's id
(architecture-principles.md §3), and this file validates, it never converts.
stringHow a rejected value may be named in an error message.
A number is safe to print — it carries no foreign data. Anything else is named by its type ONLY: the envelope is caller-supplied, so a string or an object could carry a secret or personal data into a log line.
functionTovárna plánovače z jádra — načtená LÍNĚ a s hláškou §5.
Port potřebuje z pinovaného @onlineapps/mq-client-core jmenný prostor
scheduler s továrnou createSchedulerPublisher. Verze, která port
plánovače ještě nevydává, se načte BEZ chyby a prostor scheduler prostě
nemá — to je druhá větev níž („export chybí"), a běžný případ. Samotné
require selže jen tehdy, když jádro nejde načíst vůbec (v node_modules
chybí nebo je rozbité) — první větev („modul se nenačte"). Chybějící sekce
scheduler v queueConfig require neshodí: odmítne až složení jména
fronty, tedy volání, ne načtení.
Kdyby se jádro načítalo v hlavičce souboru, spadl by při nenačitatelném
jádru CELÝ wrapper při načtení modulu — tedy i službě, která plánovač vůbec
nepoužívá. Načítá se proto až při stavbě portu: vada pinu se pozná při
stavbě kontextu, jménem slotu a s opravou (architecture-principles.md §5),
a ne pádem, který o plánovači nic neříká.
ObjectThe fields every log line ABOUT an error must carry: the error itself, its
text as exception.message and its class as exception.type — the
OpenTelemetry semantic-convention attributes, as own, enumerable properties.
Error.message is non-enumerable. A meta of { err } therefore survives
JSON.stringify as { name, code, status, details } — the sentence saying
what went wrong is gone, except where a stack key happens to be passed too,
and then only as the first line of it. Measured (BIZ-converter, dev, wrapper
8.1.1): four of this file's log lines pass no stack, so their message did
not reach the operator at all.
Why not a message key: the telemetry log envelope carries the record's own
text in its body, and the monitoring consumer merges the body over the data,
so a message in the data never reached Loki (measured d.868, DEV Loki).
exception.type is the constructor's name, not err.name: BusinessError
sets name itself, so a service subclass that sets none of its own reports
BusinessError by name while its constructor still names the class.
One rail for the whole package: ServiceWrapper uses it for the two lines it
writes about an error itself (change-discipline.md § One rail per concern).
ErrorEnvelopeAssemble the caller-facing envelope. details and correlation_id appear
only when supplied — the shape the contract documents, nothing padded.
ObjectTHE mapping. One place decides both halves of what a throw becomes:
envelope — what the caller receives;log — the line whoever HANDLES the throw writes for it.Two halves, one branching table, because a second copy of the table is how a
caller-facing status and its log line drift apart
(.claude/rules/change-discipline.md § One rail per concern).
Pure: it decides, it does not log. map is the wrapper's own path and writes the line; toCallerEnvelope is the path for a service that already logs the failure itself and needs the envelope only.
ErrorEnvelopeThe envelope a caller receives for err — and NOTHING else. No logger, no
log line, no other side effect: a service that already logged the failure
itself calls this instead of instantiating an ErrorMapper, so one
failure stays one log line (measured: the converter logged every 5xx twice,
BIZ-converter 2026-09-14).
Same mapping table as map, because it IS the same function underneath — the two differ only in whether the log half is used.
Contract: api/docs/biz/70-contracts/error-handling.md;
the table: api/docs/biz/10-invocation/handler-dispatch.md § ErrorMapper — throw-to-envelope.
objectBuild the default Ajv instance used when the caller does not inject one. Change the option set only together with the documents named under See.
stringSummarise the first ajv error into a human-readable string.
Shape: <phase>/<instancePath> <ajv message>
stringName what was handed in where an Ajv instance was expected, for the refusal message. It describes the value, never prints it: the caller knows what it passed, and a schema compiler's innards are not error-message material.
functionTie the caller's own abort signal, when one came with the message, to the controller this wrapper owns for the attempt: the caller aborting aborts the attempt too, with the caller's reason (d.1264b).
ObjectThe wrapper's v3 invocation model wires OrchestratorConnector with invoker RPC, which the orchestrator has carried since the major above. If npm resolves an older one (stale tree / lockfile), WorkflowOrchestrator throws "apiMapper is required" — fail here with an explicit contract error instead.
stringOne finding of ValidationOrchestrator as a sentence an operator can act on.
results.errors is a MIXED array and always has been: steps 2, 4, 5 and 7 push
sentences (the manifest's own describeFinding, a cookbook failure), while step
1 — ServiceStructureValidator — pushes objects { type, path, message, fix }.
Interpolating that array into a template literal turned every object into
[object Object], so the code (MISSING_COOKBOOKS), the path and the way out
were dropped at the last step before the log (architecture-principles.md §5;
measured by W591 on a boot whose tests/cookbooks was empty).
A sentence travels verbatim — the step that produced it already wrote it in the
[Context] Problem - Expected/Fix shape. An object is rendered into that shape
here. Anything else is serialized rather than described: a formatter that threw
would replace the failure it was called to report.
stringThe message the two Tier-1 throw sites raise — the startup path (FÁZE 0.2,
_ensureValidationProof) and the hourly revalidation (_executeRevalidation).
ONE helper, because one wording of one fact is one rail
(.claude/rules/change-discipline.md § One rail per concern).
ErrorStamp the disposition on an error and hand it back, so a throw stays one
expression.
Array.<string>Which static steps of this result failed.
All five report { valid, errors }; only step 5 answers with success, and it
is deliberately not in the list. A step that did not run at all is absent from
result.steps — the run fails fast after steps 1 and 3 — and an absent step has
no verdict to read.
ErrorStamp an error the wrapper is about to raise from inside a handler's call.
booleanDid this wrapper raise the error itself?
ObjectWhat build() resolves to.
ObjectMQ response envelope produced by map(). Never null — map() never throws.
ObjectThe error member of an ErrorEnvelope.
ObjectBody published to a caller's reply queue by _publishWorkflowRpcReply().
ObjectWhat invokeOperation() resolves to. Never rejects — failures arrive as error.
@onlineapps/service-wrapper/ConfigLoader](#module_@onlineapps/service-wrapper/ConfigLoader)
## @onlineapps/service-wrapper
Infrastructure orchestration for microservices.
Thin layer that delegates all work to specialized connectors.
**Since**: 2.0.0
**Author**: OA Drive Team
**License**: MIT
### @onlineapps/service-wrapper~bootstrap(serviceRoot, [options]) ⇒ Promise.<{wrapper: ServiceWrapper}>
Bootstrap a business service with standard configuration.
Eliminates boilerplate code in service index.js.
Zero-HTTP shape (ADR 0005): no Express app is created, no port is bound.
Business operations flow via MQ + in-process HandlerRegistry dispatch.
Health flows via MQ heartbeat (Phase 0.10 inside wrapper.initialize()).
There is no logger option. `wrapper.initialize()` hands `wrapper.logger` to the
shared proxy in FÁZE 0.12 — before FÁZE 0.2 runs the service's Tier-1
cookbooks — so by the time this function returns every consumer already reads
the real instance through `getLogger()`. A caller that still passes
`options.setLogger` is refused by name (`assertNoRetiredLoggerOption`).
A service that owns a database hands its ONE Sequelize instance over as
`options.db` — the instance `createSequelize()` from `@onlineapps/conn-base-db`
built, the same object its handlers import
(api/docs/biz/70-contracts/database-contract.md §10). The wrapper calls
`authenticate()` on it for `components.db` and nothing else. It is required
exactly when `config/service/integration-contract.json` declares
`requiredConnectors.db === true`; a mismatch either way stops the boot in
FÁZE 0.15.
**Kind**: inner method of [@onlineapps/service-wrapper](#module_@onlineapps/service-wrapper)
| Param | Type | Description |
| --- | --- | --- |
| serviceRoot | string | Service root directory (__dirname from index.js) |
| [options] | Object | Optional overrides |
| [options.db] | Object | The service's Sequelize instance (see above) |
| [options.scheduler] | Object | Boot hook `{ recurrences }` for FÁZE 0.7b (conf `scheduler` 010) |
**Example**
```js
// index.js (minimal, no database)
require('@onlineapps/service-wrapper').bootstrap(__dirname);
```
**Example**
```js
// index.js of a service that owns a database
const sequelize = require('./src/db'); // built by createSequelize()
require('@onlineapps/service-wrapper').bootstrap(__dirname, { db: sequelize });
```
## @onlineapps/service-wrapper/logger
Shared logger proxy for business services.
Handlers, services and controllers are `require`d at module load time, long
before `wrapper.initialize()` has produced a real logger. This module is the
late-binding indirection between the two: bootstrap calls `setLogger()` once,
every consumer calls `getLogger()` whenever it actually logs.
Fail-fast, no fallback. If `getLogger()` is reached before `setLogger()`, that
is a wiring defect and it throws — it does NOT hand back a console-shaped
substitute. A silent console fallback makes a service that lost its real
logger look healthy: the log lines still appear on stdout, while nothing
reaches the monitoring connector, the log files or the correlation context.
See `architecture-principles.md` §3 (No Fallbacks) and §4 (Fail-Fast).
Consumers call `getLogger()` at call time, never at module scope — binding
the result into a module-level constant would capture the state before
bootstrap and defeat the indirection.
**Example**
```js
// bootstrap, once, after wrapper.initialize()
const { setLogger } = require('@onlineapps/service-wrapper');
setLogger(wrapper.logger);
```
**Example**
```js
// any consumer
const { getLogger } = require('@onlineapps/service-wrapper');
function handle() {
getLogger().info('Message', { data: 'value' });
}
```
* [@onlineapps/service-wrapper/logger](#module_@onlineapps/service-wrapper/logger)
* [~_logger](#module_@onlineapps/service-wrapper/logger.._logger) : Object \| null
* [~setLogger(logger)](#module_@onlineapps/service-wrapper/logger..setLogger) ⇒ void
* [~getLogger()](#module_@onlineapps/service-wrapper/logger..getLogger) ⇒ Object
### @onlineapps/service-wrapper/logger~\_logger : Object \| null
**Kind**: inner property of [@onlineapps/service-wrapper/logger](#module_@onlineapps/service-wrapper/logger)
### @onlineapps/service-wrapper/logger~setLogger(logger) ⇒ void
Inject the logger instance. Called once during bootstrap; a later call
replaces the instance (tests wire an in-memory logger this way).
**Kind**: inner method of [@onlineapps/service-wrapper/logger](#module_@onlineapps/service-wrapper/logger)
**Throws**:
- Error If `logger` is not an object exposing all four methods. The
previously stored instance is left untouched when validation fails.
| Param | Type | Description |
| --- | --- | --- |
| logger | Object | Logger exposing info/warn/error/debug as functions. |
### @onlineapps/service-wrapper/logger~getLogger() ⇒ Object
Return the injected logger.
**Kind**: inner method of [@onlineapps/service-wrapper/logger](#module_@onlineapps/service-wrapper/logger)
**Returns**: Object - The logger passed to `setLogger()`.
**Throws**:
- Error If `setLogger()` has not run yet. There is no console
fallback — an uninitialised logger is a bootstrap defect, not a degraded
mode to be papered over.
## redactedInputGuard
redactedInputGuard.js — a redacted copy of the input never reaches a handler.
`@onlineapps/logger-contract` `redactSensitiveDeep` replaces the value of
every declared sensitive field with `REDACTED_PLACEHOLDER` in the copies made
for logs, traces and events (SecretBox §8). Those are observability copies.
The execution message — the one that carries the value to its owning handler
— must never be one of them: a handler handed the placeholder authenticates
with the string, stores it as a password or sends it as a token, and the run
reports success.
This wrapper redacts nothing. It GUARDS, in `invokeOperation()`: every
declared sensitive field whose value IS the placeholder — matched by key name
at any depth, the way `redactSensitiveDeep` matches — refuses the message
with `InvalidEnvelopeError` (400 `INVALID_ENVELOPE`) before the handler runs.
The refusal names the FIELD, never a value.
Where the rule comes from (lead's decision N1, 0.2b-1053):
- the orchestrator's message carries `sensitive_input_fields`: the recipe's
rule, the sorted unique union of every operation's declaration
(`@onlineapps/conn-orch-orchestrator` `_executeTaskStep`), and the guard
applies exactly that;
- a message without the key is a direct dispatch
(`_dispatchViaInvokeOperation`), which has no recipe, so its rule is the
operation's own `operations.json` declaration — read through the ONE
reader of that declaration, `sensitiveFieldsForOperation`;
- a key present in any other shape than an array of non-empty strings is a
defective envelope and is refused by name.
The walk below is deliberately minimal and local: `logger-contract` exports
the placeholder and the declaration reader, but not a walk that FINDS a value
without copying the tree (`redactSensitiveDeep` clones and replaces). Lifting
this walk into `logger-contract` beside `redactSensitiveDeep` is a candidate
for that package, recorded as a finding of d.1280 — until then this is the
one implementation in this package.
**See**
- api/docs/architecture/secretbox.md §8
- api/docs/biz/10-invocation/handler-dispatch.md
* [redactedInputGuard](#module_redactedInputGuard)
* [~SENSITIVE_RULE_KEY](#module_redactedInputGuard..SENSITIVE_RULE_KEY)
* [~isWellFormedRule(value)](#module_redactedInputGuard..isWellFormedRule) ⇒ boolean
* [~describeShape(value)](#module_redactedInputGuard..describeShape) ⇒ string
* [~resolveSensitiveRule(mqMessage, operations, operation)](#module_redactedInputGuard..resolveSensitiveRule) ⇒ Array.<string>
* [~findRedactedFields(input, fieldNames)](#module_redactedInputGuard..findRedactedFields) ⇒ Array.<string>
* [~assertNoRedactedInput(params)](#module_redactedInputGuard..assertNoRedactedInput)
* [~assertDeclaredSensitiveInputFields(operationsMap)](#module_redactedInputGuard..assertDeclaredSensitiveInputFields)
### redactedInputGuard~SENSITIVE\_RULE\_KEY
The wire key the orchestrator sends the recipe rule under.
**Kind**: inner constant of [redactedInputGuard](#module_redactedInputGuard)
### redactedInputGuard~isWellFormedRule(value) ⇒ boolean
Is `value` the shape a sensitive-field rule must have: an array of non-empty
strings (`[]` included)?
**Kind**: inner method of [redactedInputGuard](#module_redactedInputGuard)
| Param | Type |
| --- | --- |
| value | \* |
### redactedInputGuard~describeShape(value) ⇒ string
One word for what arrived instead of a rule — the TYPE, never the content:
a malformed rule may carry anything, and this message reaches a log.
**Kind**: inner method of [redactedInputGuard](#module_redactedInputGuard)
| Param | Type |
| --- | --- |
| value | \* |
### redactedInputGuard~resolveSensitiveRule(mqMessage, operations, operation) ⇒ Array.<string>
The sensitive-field rule that applies to one invocation.
**Kind**: inner method of [redactedInputGuard](#module_redactedInputGuard)
**Returns**: Array.<string> - the field names to guard; `[]` when nothing is declared
**Throws**:
- InvalidEnvelopeError when the message carries the key in a shape
other than an array of non-empty strings
- Error when the message carries no rule and the operation's own
declaration cannot be read (the spec names the key in a non-array shape)
| Param | Type | Description |
| --- | --- | --- |
| mqMessage | Object | the operation message; `sensitive_input_fields` is read when present |
| operations | Object | the service's operations.json object (`{ operations: { string | the operation being invoked |
### redactedInputGuard~findRedactedFields(input, fieldNames) ⇒ Array.<string>
The names among `fieldNames` whose value, anywhere in `input`, IS the
redaction placeholder — unique, sorted. Matching follows
`redactSensitiveDeep`: by key name, at any depth, through arrays and plain
objects; a Date or a Buffer is a leaf, a shared or circular object is
visited once.
**Kind**: inner method of [redactedInputGuard](#module_redactedInputGuard)
| Param | Type | Description |
| --- | --- | --- |
| input | Object | the operation input (an object; `invokeOperation` has already refused anything else) |
| fieldNames | Array.<string> | the rule |
### redactedInputGuard~assertNoRedactedInput(params)
Refuse an input that is a redacted copy: any declared sensitive field whose
value is the placeholder.
**Kind**: inner method of [redactedInputGuard](#module_redactedInputGuard)
**Throws**:
- InvalidEnvelopeError naming the field(s) — and never a value
| Param | Type | Description |
| --- | --- | --- |
| params | Object | |
| params.input | Object | the operation input |
| params.fieldNames | Array.<string> | the rule (`resolveSensitiveRule`) |
| params.operation | string | the operation, for the message |
### redactedInputGuard~assertDeclaredSensitiveInputFields(operationsMap)
Refuse, at boot (FÁZE 0.1b), a `sensitive_input_fields` declaration no guard
can apply — by the operation's name, before the service registers.
Absent = no declaration. Present = an array of unique non-empty strings
(`[]` included). Anything else used to surface as an `Error` on the first
direct dispatch of that operation (finding d.1280/2), after registration.
This is a MINIMAL check of this wrapper's own: the registration contract
(`@onlineapps/service-validator-core` `operationsSchemaValidator.js`, the
owner of what `operations.json` must satisfy) checks `retry` and
`timeout_ms` and says nothing about this key — recorded as a finding of
d.1285 for that contract (`api/docs/biz/30-operations/registration-wire.md`,
`schema-v3.md` § `sensitive_input_fields`). When the contract takes the rule,
this check cites it and defines nothing of its own.
**Kind**: inner method of [redactedInputGuard](#module_redactedInputGuard)
**Throws**:
- Error naming the first operation whose declaration is malformed
| Param | Type | Description |
| --- | --- | --- |
| operationsMap | Object.<string, Object> | `operations.json` `operations` |
## shutdownDeadline
The deadline of `ServiceWrapper.shutdown()` — one watchdog, armed before the first
teardown step, that ends the process when the teardown does not.
Owner's decision: api/docs/governance/confirmations/biz-shutdown-deadline.md 001 (d.1102
measured, d.1105 built). Without it a teardown against a Redis or a broker that holds
the connection and never answers never ended: `bootstrap()`'s `process.exit(0)` never
came, and on the fatal path — where nothing sends a SIGKILL — the process stayed up,
dead, for good.
The process edge (`writeStderr`, `exit`) is injected; nothing here touches `process`.
* [shutdownDeadline](#module_shutdownDeadline)
* [~SHUTDOWN_TIMEOUT_KEY](#module_shutdownDeadline..SHUTDOWN_TIMEOUT_KEY)
* [~SHUTDOWN_STEPS](#module_shutdownDeadline..SHUTDOWN_STEPS)
* [~list()](#module_shutdownDeadline..list)
* [~armShutdownDeadline(options)](#module_shutdownDeadline..armShutdownDeadline) ⇒ Object
### shutdownDeadline~SHUTDOWN\_TIMEOUT\_KEY
The platform env key that owns the deadline. Named once; its declaration (value, why,
consumers) is `api/config/shared-env.json`.
**Kind**: inner constant of [shutdownDeadline](#module_shutdownDeadline)
### shutdownDeadline~SHUTDOWN\_STEPS
The teardown steps of `shutdown()` that can wait on something outside the process, in
the order they run (d.998b — this list describes the order, it does not set it). The
heartbeat stop and the revalidation timer are synchronous and cannot hang, so they are
not steps a deadline can find pending.
**Kind**: inner constant of [shutdownDeadline](#module_shutdownDeadline)
### shutdownDeadline~list()
A list an operator can read, or the word for an empty one.
**Kind**: inner method of [shutdownDeadline](#module_shutdownDeadline)
### shutdownDeadline~armShutdownDeadline(options) ⇒ Object
Arm the watchdog. On expiry it writes ONE line through `writeStderr` — synchronously,
and not through the telemetry transport, which may be the very step that hangs and
closes last — and then calls `exit(1)`: an incomplete teardown must not look clean.
The timer is deliberately NOT `unref()`ed: a teardown blocked on a socket keeps the
loop alive anyway, and the watchdog must outlive it.
**Kind**: inner method of [shutdownDeadline](#module_shutdownDeadline)
**Returns**: Object - call `disarm()` when the teardown ends, however it ends
**Throws**:
- Error when an option is missing or malformed
| Param | Type | Description |
| --- | --- | --- |
| options | Object | |
| options.timeoutMs | number | positive whole number of milliseconds |
| options.steps | Array.<string> | every step label, in teardown order |
| options.progress | function | `() => ({ pending, released, failed })`, read at expiry |
| options.writeStderr | function | synchronous writer of one text chunk to stderr |
| options.exit | function | ends the process with the given code |
## signalShutdown
The SIGTERM/SIGINT handler `bootstrap()` installs — the one place a signal becomes a
teardown and an exit code.
Owner's decision: api/docs/governance/confirmations/biz-shutdown-deadline.md 001 — exit 0
only after a clean teardown, exit 1 when `shutdown()` rejects, and a second signal
during a running teardown is ignored. Until d.1105 the handler was
`await wrapper.shutdown(); process.exit(0)` on both signals: a rejected teardown ended
the process on an unhandled rejection instead, and a second signal started a second
teardown over the first (d.1102).
A teardown that never settles is not this handler's business: the deadline armed
inside `shutdown()` ends it (`shutdownDeadline.js`).
### signalShutdown~createSignalShutdown(options) ⇒ function
**Kind**: inner method of [signalShutdown](#module_signalShutdown)
**Returns**: function - `async (signalName) => void`, to be called on every signal
**Throws**:
- Error when an option is missing
| Param | Type | Description |
| --- | --- | --- |
| options | Object | |
| options.wrapper | Object | the ServiceWrapper to tear down |
| options.exit | function | ends the process with the given code |
| options.log | function | writes one informational line |
| options.error | function | writes one error line |
## stepDeadline
The deadline of ONE ATTEMPT of a step — how long this wrapper lets an
operation's handler run before it abandons the attempt.
Owner's word (conf `step-error-classification` 005 — variant A, a deadline
per ATTEMPT per operation): the deadline
is per operation, declared as `timeout_ms` in `config/service/operations.json`
beside `retry`; an operation that declares none gets the platform default;
a declaration outside the platform range is refused by the operation's name,
never replaced by the default — the rule `retry` follows in
`@onlineapps/conn-orch-orchestrator` (`retryPolicy.js`).
The numbers — the platform default and the range — are not this module's:
`@onlineapps/handler-contract` owns them (`STEP_TIMEOUT_MIN_MS`,
`STEP_TIMEOUT_MAX_MS`, `DEFAULT_STEP_TIMEOUT_MS`), and this module reads
them and keeps no copy (conf `handler-contract` 002, d.1382). It exports
`DEFAULT_STEP_TIMEOUT_MS`, `MIN_STEP_TIMEOUT_MS` and `MAX_STEP_TIMEOUT_MS`,
which are those values.
The wrapper ENFORCES it (`ServiceWrapper.invokeOperation` races the handler
against it and aborts `ctx.abortSignal`); whether a timed-out step is tried
again is the orchestrator's decision (005: a reading operation by the retry
policy, a writing one straight to `workflow.failed`) — the attempt ends with a TIMEOUT-class
error (`StepTimeoutError`, 504 `STEP_TIMEOUT`), and status 504 is
`ErrorTypes.TIMEOUT` in `@onlineapps/error-handler-core` `ErrorClassifier.js`.
**See**: api/docs/governance/confirmations/step-error-classification.md
* [stepDeadline](#module_stepDeadline)
* [~StepTimeoutError](#module_stepDeadline..StepTimeoutError)
* [new StepTimeoutError(params)](#new_module_stepDeadline..StepTimeoutError_new)
* [~MIN_STEP_TIMEOUT_MS](#module_stepDeadline..MIN_STEP_TIMEOUT_MS)
* [~MAX_STEP_TIMEOUT_MS](#module_stepDeadline..MAX_STEP_TIMEOUT_MS)
* [~STEP_TIMEOUT_CODE](#module_stepDeadline..STEP_TIMEOUT_CODE)
* [~show()](#module_stepDeadline..show)
* [~resolveStepTimeout(declared, operation)](#module_stepDeadline..resolveStepTimeout) ⇒ number
* [~assertDeclaredStepTimeouts(operationsMap)](#module_stepDeadline..assertDeclaredStepTimeouts) ⇒ void
### stepDeadline~StepTimeoutError
One attempt ran past its deadline.
Not a business error and not branded: the wrapper raises it around the
handler, never a handler, and `ErrorMapper` recognises it by `name` and
`code` (`describeFailure`, the branch beside `AbortError`) — the light entry
`./errors` does not load this module. It carries `type`
`TIMEOUT` explicitly — the class the orchestrator retries — and `details`
naming the deadline, which the envelope keeps (it names nothing of the
caller's data).
**Kind**: inner class of [stepDeadline](#module_stepDeadline)
#### new StepTimeoutError(params)
| Param | Type |
| --- | --- |
| params | Object |
### stepDeadline~MIN\_STEP\_TIMEOUT\_MS
The shortest deadline an operation may declare, in ms - `STEP_TIMEOUT_MIN_MS` of handler-contract under the name this module exports.
**Kind**: inner constant of [stepDeadline](#module_stepDeadline)
### stepDeadline~MAX\_STEP\_TIMEOUT\_MS
The longest deadline an operation may declare, in ms - `STEP_TIMEOUT_MAX_MS` of handler-contract under the name this module exports.
**Kind**: inner constant of [stepDeadline](#module_stepDeadline)
### stepDeadline~STEP\_TIMEOUT\_CODE
The code an attempt ended by its deadline carries. Produced by the wrapper only.
**Kind**: inner constant of [stepDeadline](#module_stepDeadline)
### stepDeadline~show()
A declared value as the refusal shows it — `NaN` and `-0` stay what they are.
**Kind**: inner method of [stepDeadline](#module_stepDeadline)
### stepDeadline~resolveStepTimeout(declared, operation) ⇒ number
The deadline of one attempt of `operation`.
**Kind**: inner method of [stepDeadline](#module_stepDeadline)
**Returns**: number - the deadline in ms
**Throws**:
- Error when a declaration is not an integer within the platform range
| Param | Type | Description |
| --- | --- | --- |
| declared | \* | `timeout_ms` from the operation's record (`undefined` = none declared) |
| operation | string | the operation's name, for the refusal |
### stepDeadline~assertDeclaredStepTimeouts(operationsMap) ⇒ void
Refuse the first operation whose `timeout_ms` declaration is invalid — run
at boot (FÁZE 0.1b), so a service never starts with a deadline nothing
applies.
**Kind**: inner method of [stepDeadline](#module_stepDeadline)
**Throws**:
- Error the refusal of `resolveStepTimeout` for the first bad declaration
| Param | Type | Description |
| --- | --- | --- |
| operationsMap | Object.<string, Object> | the `operations` map of operations.json |
## ContextBuilder
ContextBuilder — assembles an OperationContext for a single invocation.
Contract: api/docs/biz/10-invocation/operation-context.md and api/docs/biz/10-invocation/handler-dispatch.md
Layer: L3 orchestration (see ARCHITECTURE_PRINCIPLES.md §7).
- Depends on connectors (L1/L2) via constructor injection only.
- Imports `./OperationContext` and the error CLASSES from `./ErrorMapper`
(L2 types, no behaviour — ErrorMapper itself imports nothing, so there is
no cycle; `./OperationContext` already depends on the same module).
MUST NOT import HandlerRegistry or SchemaValidator, and MUST NOT call
ErrorMapper.map() — mapping stays the wrapper's job.
- Does NOT validate handler input/output schemas (SchemaValidator owns that).
- Does NOT invoke handlers (ServiceWrapper owns that).
SRP: single job — translate (mqMessage, operationSpec) into a ready-to-use
OperationContext plus a release() hook the wrapper must call after the
handler returns (success or failure).
**Kind**: global class
* [ContextBuilder](#ContextBuilder)
* [new ContextBuilder(deps)](#new_ContextBuilder_new)
* [.build(mqMessage, operationSpec)](#ContextBuilder+build) ⇒ [Promise.<ContextBuildResult>](#ContextBuildResult)
### new ContextBuilder(deps)
| Param | Type | Description |
| --- | --- | --- |
| deps | Object | |
| deps.connectors | Object | { cache, http, secrets, state, monitoring, mq } |
| deps.config | Object | Read-only service config snapshot. |
| deps.logger | Object | Base logger (must expose `.child()` to be useful). |
### contextBuilder.build(mqMessage, operationSpec) ⇒ [Promise.<ContextBuildResult>](#ContextBuildResult)
Build an OperationContext for one MQ invocation.
Fail-fast order:
1. MQ envelope shape (operation, envelope, workflow_id, correlation_id,
step_id), plus the shape of a PRESENT envelope.person_id — `null` and
an absent key stay valid (`integer | null` per the wire contract), a
present value must be a positive integer (isPositiveIntegerId).
2. Tenancy from operationSpec.bundle_scope — presence AND shape:
'tenant' -> tenant_id required
'workspace' -> tenant_id AND workspace_id required
'platform' -> both optional, and neither is shape-checked
A required id must also BE a positive integer (isPositiveIntegerId).
An operation that declares NO bundle_scope is refused by name — the key
is required (api/docs/biz/30-operations/schema-v3.md), so its absence is
a packaging bug of ours and never a silent 'workspace'.
3. Scoped logger (via base.child() when available; fall back to base logger
only when the base does not implement .child — bunyan/pino both do).
4. Connector acquisition (cache, httpClient, state, secrets facade).
5. stream — a slot, always `null`; chunk streaming has no protocol yet
and a handler that calls it fails loudly (d.802b).
6. abortSignal — mqMessage.abortSignal. `ServiceWrapper.invokeOperation()`
always passes the signal of the controller it owns for the attempt
(aborted by the step deadline and by the caller's own signal, d.1264b);
a direct caller without one gets a controller nothing aborts.
**Kind**: instance method of [ContextBuilder](#ContextBuilder)
**Returns**: [Promise.<ContextBuildResult>](#ContextBuildResult) - Callers MUST await release() in a finally block.
release() is idempotent.
**See**: api/docs/biz/10-invocation/operation-context.md § Release
| Param | Type | Description |
| --- | --- | --- |
| mqMessage | Object | Parsed MQ message (envelope, operation, ids). |
| operationSpec | Object | operations.json entry for this op (bundle_scope, ...). |
## ErrorMapper
**Kind**: global class
* [ErrorMapper](#ErrorMapper)
* [new ErrorMapper(options)](#new_ErrorMapper_new)
* [.map(err, meta)](#ErrorMapper+map) ⇒ [ErrorEnvelope](#ErrorEnvelope)
### new ErrorMapper(options)
| Param | Type | Description |
| --- | --- | --- |
| options | Object | |
| options.logger | Object | Base logger (must expose .info/.warn/.error). |
### errorMapper.map(err, meta) ⇒ [ErrorEnvelope](#ErrorEnvelope)
Map a handler exception to an MQ response envelope AND log it — the
wrapper's own path, where the wrapper is the one handling the throw.
Never throws. Always returns `{ status, error: { code, message, [details], [correlation_id], [type] } }`.
Exactly one line is written per call, at the level the mapping decided.
Need the envelope without that line — because you log the failure yourself
— use [toCallerEnvelope](#toCallerEnvelope); it is the same mapping, minus the log.
Recognition is by the brand + shape contract (see the file header), never by
`instanceof`. Branded + malformed → 500 `MALFORMED_BUSINESS_ERROR` with the
offending field named in the log; unbranded → 500 `INTERNAL_ERROR`, masked.
**Kind**: instance method of [ErrorMapper](#ErrorMapper)
| Param | Type |
| --- | --- |
| err | Error |
| meta | Object |
| [meta.operation] | string |
| [meta.correlation_id] | string |
| [meta.workflow_id] | string |
## HandlerLoader
**Kind**: global class
* [HandlerLoader](#HandlerLoader)
* [new HandlerLoader(deps)](#new_HandlerLoader_new)
* [.resolve(handlerRef)](#HandlerLoader+resolve) ⇒ function
### new HandlerLoader(deps)
| Param | Type | Description |
| --- | --- | --- |
| deps | Object | |
| deps.baseDir | string | Absolute path to the service source root (typically `path.join(serviceRoot, 'src')`, e.g. `/app/src`). |
| deps.logger | Object | Logger per `@onlineapps/logger-contract`. |
### handlerLoader.resolve(handlerRef) ⇒ function
Resolve `"relative/path#exportName"` to the exported function.
Cached per handlerRef string. Throws on any malformed / missing input.
**Kind**: instance method of [HandlerLoader](#HandlerLoader)
| Param | Type | Description |
| --- | --- | --- |
| handlerRef | string | v3 handler descriptor from operations.json. |
## HandlerRegistry
**Kind**: global class
* [HandlerRegistry](#HandlerRegistry)
* [new HandlerRegistry(deps)](#new_HandlerRegistry_new)
* [.validate()](#HandlerRegistry+validate) ⇒ void
* [.invoke(operation, input, ctx)](#HandlerRegistry+invoke) ⇒ Promise.<\*>
### new HandlerRegistry(deps)
| Param | Type | Description |
| --- | --- | --- |
| deps | Object | |
| deps.operations | Object | Parsed operations.json (v3): map opName -> opSpec. |
| deps.handlerLoader | Object | Abstraction with .resolve(handlerRef) -> Function. `handlerRef` is the v3 "Object | Logger with at least .debug/.info; .trace is optional. |
### handlerRegistry.validate() ⇒ void
Eagerly resolve every declared handler. Called once by
ServiceWrapper.initialize() BEFORE MQ subscription.
Fail-fast: throws on the first bad entry. No catch-and-continue.
**Kind**: instance method of [HandlerRegistry](#HandlerRegistry)
**Throws**:
- Error On missing/invalid handler field or non-function resolution.
**See**: api/docs/biz/10-invocation/handler-dispatch.md § Where the pipeline is built
### handlerRegistry.invoke(operation, input, ctx) ⇒ Promise.<\*>
Hot-path invocation. O(1) Map lookup, no filesystem I/O, no reflection.
Handler errors propagate untouched — ErrorMapper is the component
that translates them into response envelopes.
**Kind**: instance method of [HandlerRegistry](#HandlerRegistry)
**Returns**: Promise.<\*> - Whatever the handler returns.
**Throws**:
- UnknownOperationError If the operation is not registered.
**See**: api/docs/biz/10-invocation/handler-dispatch.md § `ErrorMapper` — throw-to-envelope
| Param | Type | Description |
| --- | --- | --- |
| operation | string | Operation name as declared in operations.json. |
| input | Object | Already-validated input payload (SchemaValidator ran earlier). |
| ctx | Object | Immutable OperationContext from ContextBuilder. |
## SchemaValidator
**Kind**: global class
* [SchemaValidator](#SchemaValidator)
* [new SchemaValidator([options])](#new_SchemaValidator_new)
* [.precompile(operations)](#SchemaValidator+precompile) ⇒ void
* [.validateInput(operation, data)](#SchemaValidator+validateInput) ⇒ null
* [.validateOutput(operation, data)](#SchemaValidator+validateOutput) ⇒ null
### new SchemaValidator([options])
**Throws**:
- Error When `options.ajv` is present but exposes no `compile()`.
| Param | Type | Description |
| --- | --- | --- |
| [options] | object | |
| [options.ajv] | object | Pre-configured Ajv instance (DI). Omit it and a strict Ajv is created internally; PASS it and it is checked. Injection is for tests and for callers that need custom formats/keywords. |
### schemaValidator.precompile(operations) ⇒ void
Compile input and output schemas for every declared operation.
Fail-fast: any compile error throws immediately and aborts startup.
**Kind**: instance method of [SchemaValidator](#SchemaValidator)
**Throws**:
- Error When a schema carries a `default` the gates would not apply (any
in an output schema; in an input schema, any not on a property under
`properties`), when two slots declare the same root `$id` (see
`_claimSchemaId`), or when a schema does not compile.
| Param | Type | Description |
| --- | --- | --- |
| operations | object | operations.json v3 object (opName → spec). Each spec MAY have `.input` (JSON Schema) and `.output` (JSON Schema). Missing input or output is permitted (operation declares none). |
### schemaValidator.validateInput(operation, data) ⇒ null
Validate input payload for a known operation.
**Kind**: instance method of [SchemaValidator](#SchemaValidator)
**Returns**: null - Returns null on success (or when the op has no input schema).
**Throws**:
- Error When the operation was never precompiled (operator bug).
- ValidationError When `data` does not conform to the compiled schema.
| Param | Type | Description |
| --- | --- | --- |
| operation | string | Operation name from operations.json. |
| data | \* | Payload to validate. |
### schemaValidator.validateOutput(operation, data) ⇒ null
Validate output payload produced by the handler.
**Kind**: instance method of [SchemaValidator](#SchemaValidator)
**Returns**: null - Returns null on success (or when the op has no output schema).
**Throws**:
- Error When the operation was never precompiled (operator bug).
- ValidationError Tagged `phase: 'output'` — ErrorMapper treats this as a server bug.
| Param | Type | Description |
| --- | --- | --- |
| operation | string | Operation name from operations.json. |
| data | \* | Handler result. |
## HandlerContractError
A handler broke the error contract — it raised a code the wrapper produces.
Deliberately NOT branded and carrying no `code` of its own: it is not a
business outcome, it is our defect, so `ErrorMapper` takes it down the
unhandled-fault branch — `error` level WITH the stack in the log, and a masked
`500 INTERNAL_ERROR` to the caller
(`api/docs/biz/70-contracts/error-handling.md` §5). A code of its own would be
a platform-wide identity, and that dictionary is added to by changing the
contract node, not by a library minting a name.
**Kind**: global class
### new HandlerContractError(message, [options])
| Param | Type | Description |
| --- | --- | --- |
| message | string | |
| [options] | Object | |
| [options.cause] | Error | The error the handler actually threw. |
## ServiceWrapper
ServiceWrapper class
Collection of connectors that enhance business service with infrastructure
**Kind**: global class
* [ServiceWrapper](#ServiceWrapper)
* [new ServiceWrapper(options)](#new_ServiceWrapper_new)
* [.refreshDependencyHealth()](#ServiceWrapper+refreshDependencyHealth) ⇒ Promise.<void>
* [.startHealthHeartbeat()](#ServiceWrapper+startHealthHeartbeat) ⇒ Promise.<void>
* [.stopHealthHeartbeat()](#ServiceWrapper+stopHealthHeartbeat) ⇒ void
* [.invokeOperation(mqMessage)](#ServiceWrapper+invokeOperation) ⇒ [Promise.<OperationEnvelope>](#OperationEnvelope)
* [.shutdown()](#ServiceWrapper+shutdown)
### new ServiceWrapper(options)
Create a new ServiceWrapper instance
**Throws**:
- Error when a platform env key the constructor reads is missing, not a whole
number, or not positive: `BIZ_SHUTDOWN_TIMEOUT_MS` (d.1105), and
`REGISTRY_DISCOVERY_TIMEOUT_MS` with `BIZ_HEARTBEAT_INTERVAL_MS` (d.1130) — FÁZE 0.7
uses those two, but reads the fields, so a bad key refuses the wrapper here instead
of surfacing in that phase as a transient error.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| options | Object | | Configuration options |
| options.config | Object | | Service and wrapper configuration |
| options.operations | Object | | Operations schema |
| options.serviceBaseDir | string | | Absolute path to the service's handler directory, like `/app/src`: pass `__dirname` from the service index.js, or `path.join(serviceRoot, 'src')`. Required — `HandlerLoader` requires the handler modules `operations.json` names relative to it, so a wrapper without it could dispatch nothing. |
| [options.serviceRoot] | string | | Service root directory (for validation) |
| [options.db] | Object | | The service's ONE Sequelize instance, as `createSequelize()` from `@onlineapps/conn-base-db` returns it (api/docs/biz/70-contracts/database-contract.md §10). The wrapper never builds or locates it; it only calls `authenticate()` on it to state `components.db`. Required exactly when the integration contract declares `requiredConnectors.db === true`, refused when it declares `false`. |
| [options._validationOrchestrator] | Object | Promise.<void>
Refresh cached component health signals for the heartbeat.
The heartbeat itself is fire-and-forget on a short interval; we do not
probe DB/Redis/cache on every heartbeat. Instead, this helper is invoked
periodically (or on demand) to keep `_lastDbHealth` / `_lastRedisHealth` /
`_lastCacheHealth` fresh so the next heartbeat carries meaningful status.
Ties into `_checkDatabaseDependency` / `_checkRedisDependency` /
`_probeCacheHealth` which remain the single source of truth for what
"healthy" means.
**Kind**: instance method of [ServiceWrapper](#ServiceWrapper)
### serviceWrapper.startHealthHeartbeat() ⇒ Promise.<void>
Start the health heartbeat publisher (ADR 0005, Phase 0.10).
Wires this biz service into the existing infrastructure heartbeat
mechanism at `@onlineapps/infrastructure-tools` — the same mechanism
already used in production by api_gateway, api_services_validator,
api_delivery_endpoint. Registry's `infrastructureHealth.listener`
consumes the messages and `infrastructureHealthTracker` maintains
the state.
Payload shape follows the validated infra format:
{ serviceName, version, status, timestamp,
components: { mq, redis, db, cache }, correlationId }
First heartbeat is emitted synchronously by publisher.start().
On publish failure, the shared publisher logs and continues — the
service is not crashed by a heartbeat glitch, and the next tick carries
the same verdict.
Failing to START is the other thing entirely, and it THROWS: every cause
is a permanent configuration fault and nothing here retries. Phase 0.10
ends the boot on it (`initialize()`; owner decision
api/docs/governance/confirmations/boot-phase-0-10.md 001).
**Kind**: instance method of [ServiceWrapper](#ServiceWrapper)
**Throws**:
- Error the publisher could not be built or could not start
### serviceWrapper.stopHealthHeartbeat() ⇒ void
Stop the heartbeat publisher (used in cleanup paths).
**Kind**: instance method of [ServiceWrapper](#ServiceWrapper)
### serviceWrapper.invokeOperation(mqMessage) ⇒ [Promise.<OperationEnvelope>](#OperationEnvelope)
v3 single-operation invocation.
Dispatch path for MQ-delivered operation messages. Never throws — always
returns an envelope `{ status, result }` or `{ status, error }` produced
by ErrorMapper.
**Kind**: instance method of [ServiceWrapper](#ServiceWrapper)
**See**: api/docs/biz/10-invocation/handler-dispatch.md § End-to-end call flow
| Param | Type | Description |
| --- | --- | --- |
| mqMessage | Object | Parsed MQ message with { operation, input, envelope, workflow_id, correlation_id, ... }. |
### serviceWrapper.shutdown()
Shutdown wrapper and cleanup resources.
Runs under a deadline (d.1105, confirmation biz-shutdown-deadline 001): a watchdog
armed before the first step ends the process with exit 1 and one stderr line naming
the pending step when the teardown outlives `BIZ_SHUTDOWN_TIMEOUT_MS`. Every caller
is covered — `bootstrap()`'s signal handler, `_handleInitializationError()` and
`_shutdownFatally()`, the last of which nothing else would ever kill.
**Kind**: instance method of [ServiceWrapper](#ServiceWrapper)
**Throws**:
- AggregateError when a step failed; the teardown still ran every step
## INTERNAL\_ERROR\_CODE
The code an error gets when nothing about it was declared.
**Kind**: global constant
## MALFORMED\_BUSINESS\_ERROR\_CODE
The code a BRANDED error gets when its shape is broken — our own defect.
**Kind**: global constant
## UNDECLARED\_FAILURE\_CODES : ReadonlySet.<string>
The codes this file puts on an envelope when the failure declared NOTHING.
They are the opposite of every other code the table produces: the rest are a
handler's (or the wrapper's) statement about an outcome, these two are the
absence of one. An `INTERNAL_ERROR` envelope means an unbranded error nobody
classified; `MALFORMED_BUSINESS_ERROR` means an error that claimed the brand
and broke the shape.
Exported because an envelope loses the distinction otherwise. Once
`ServiceWrapper._dispatchViaInvokeOperation()` rebuilds a failure as a plain
`Error` with `code` and `status`, a masked 500 `INTERNAL_ERROR` is shaped
exactly like a declared 500 `DATA_INTEGRITY_VIOLATION`, and only this list
separates them (`ServiceWrapper._classifyDeliveryError()` — an undeclared
failure keeps its delivery attempts, a declared one does not).
**Kind**: global constant
## CONTRACT\_RETRYABLE\_CODES : ReadonlySet.<string>
The codes whose dictionary row declares that a retry is meaningful.
A code's declared identity is not only its name and its status: the accepted
dictionary carries a `Retry` column, and that column is part of what the code
means platform-wide. `PROVIDER_UNAVAILABLE` is the row that says yes.
Owner: `api/docs/biz/70-contracts/error-handling.md` § Accepted domain codes —
a row there is the fact, this list is only the machine-readable side of it, so
a code joins or leaves this set when that table changes and never otherwise.
❌ Not a flag on an error instance: which codes may be retried is a property
of the contract dictionary, not of one throw
(`.claude/rules/single-source-of-truth.md`).
Read by `ServiceWrapper._classifyDeliveryError()`: such a code keeps its
delivery attempts, exactly as an undeclared failure does, while every other
declared business code is settled on the first delivery (d.547).
**Kind**: global constant
## path
HandlerLoader
L3 Orchestration helper used by HandlerRegistry. Resolves v3 handler
references of the form `"relative/path#exportName"` to actual exported
functions, relative to the host service's source directory.
Layer: L3 (Orchestration). Pure filesystem + require. No cross-imports
from other wrapper modules.
**Kind**: global constant
**See**: api/docs/biz/10-invocation/handler-dispatch.md
## MQConnector
Service Wrapper - Collection of connectors for business services
Provides infrastructure components in single-process architecture:
- MQ integration (RabbitMQ)
- Service discovery (Registry)
- Monitoring and metrics
- Health checks
Uses HTTP pattern exclusively - no direct handler calls
**Kind**: global constant
## WRAPPER\_RESERVED\_ERROR\_CODES
The error codes this wrapper produces about its own dispatch, with what a
handler that means the same thing throws instead.
The dictionary of codes, and which of them belong to the wrapper rather than
to a handler, has one owner — the nodes cited below, not this comment.
`CLIENT_CANCELLED` is deliberately NOT here. `ErrorMapper` matches it on the
error's `name` outside the brand contract, because the abort it must
recognise is Node's own `AbortController` `DOMException` — which a handler
awaiting an aborted call legitimately propagates.
Until this Map existed nothing enforced the split: a handler lives in a
service repository, which review here never sees, and the cost of missing one
is not cosmetic — see `_invokeHandlerUnderContract()`.
**Kind**: global constant
**See**
- api/docs/biz/70-contracts/error-handling.md
- api/docs/biz/10-invocation/handler-dispatch.md
## REQUIRED\_CONN\_ORCH\_ORCHESTRATOR\_MAJOR
The orchestrator major the wrapper's v3 invocation model requires.
ONE constant: the guard below branches on it and the refusal names it, so the
sentence an operator reads cannot drift from the comparison that raised it
(`change-discipline.md` § One rail per concern). WHICH released version
carries this major is not written here — that is the platform SSOT's fact
(`api/config/libraries.json`), and a number copied into a message is a
descriptive fact maintained by hand (`doc-code-binding.md` §1).
**Kind**: global constant
## REGISTRY\_DISCOVERY\_TIMEOUT\_KEY
The PLATFORM env key that owns the deadline of one discovery lookup (d.1093). Named
once here, so renaming it is one edit in this package; its declaration (why, consumers,
value) is `api/config/shared-env.json`.
**Kind**: global constant
## BOOT\_DISPOSITION
What an operator should do next about a failed boot phase, carried ON the
error rather than decided at the `catch` that reports it.
FÁZE 0.3 already worked this way — it reads `error.code !== 'MQ_CONNECTION_FATAL'`
off the error `@onlineapps/mq-client-core` threw, because only the layer that
produced the failure knows whether asking again can change the answer. This is
the same rail, named once and readable by every phase that has more than one
disposition.
A phase whose failure is always of one kind (0.12, 0.15, 0.10) passes its
constant and reads nothing — the marker is for the phases where the disposition
is a FACT about the failure, not about the phase.
**Kind**: global constant
## STATIC\_VALIDATION\_STEPS
The Tier-1 steps that read NOTHING but the files already on disk.
`@onlineapps/conn-orch-validator` 10.0.0 runs seven steps and reports each one
under its own key in `result.steps` (`ValidationOrchestrator.runFullValidation()`):
1 `structure` the service tree — `ServiceStructureValidator`
2 `config` `config/service/*.json`
3 `env` the env contract the service declares
4 `operations` operations.json against the v3 shape
5 `cookbooks` the service's own recipes, RUN against handlers and DB
6 `connectors` warnings only — it can never fail a validation
7 `manifest` the uniform, measured on the checkout
Five of them decide from files alone. A verdict of theirs is the same on the
next attempt and on the attempt after that, because nothing between two
attempts changes what they read — so retrying is not caution, it is 18,5 minutes
of a boot that cannot succeed (measured twice: biz-converter `exit 1` after
18 min 53 s, W591 on `MISSING_COOKBOOKS`). Step 5 is the one that depends on the
world around the service, and it is the one that keeps the budget.
The classification reads the STEP, never the message: `result.errors` is one
flat array into which step 1 pushes objects and steps 2/4/5/7 push sentences
(that mixture is why `describeValidationFinding()` exists), so a message tells
an operator what happened and tells this code nothing it can decide on.
**Kind**: global constant
## DEPENDENCY\_HEALTH\_FIELD
The cached health signal each dependency component keeps, by component name.
ONE place says which components there are and where each one's last verdict
lives, so `refreshDependencyHealth()` writes the field and
`_recordDependencyHealth()` compares against it without either of them
spelling the field name again.
**Kind**: global constant
## ERROR\_HANDLING\_KEYS
The `wrapper.errorHandling` keys this package forwards to
`@onlineapps/conn-infra-error-handler`. Named, not spread: a key outside this
list configures nothing in the core, and forwarding it blindly would let a
misspelling pass in silence.
`dlqEnabled` left the list in d.493, for the reason
`@onlineapps/error-handler-core` retired it (that package's CHANGELOG,
`### Removed — DLQRouter`): the core stopped reading the key, so forwarding it
configured nothing. It is not merely dropped — a config still writing it is
REFUSED by name (`_assertRetiredDlqEnabledKey`).
`maxRetries`, `retryDelay` and `retryMultiplier` left it in d.1264 and are
refused the same way (`RETIRED_RETRY_KEYS`).
**Kind**: global constant
## RETIRED\_RETRY\_KEYS
The three `wrapper.errorHandling` keys that configured `RetryHandler` of
`@onlineapps/error-handler-core`, retired in d.1264 and REFUSED by name
(`_assertRetiredRetryKeys`).
Nothing on this package's path read what they configured: the orchestrator
calls the connector's `classifyError()` only, and this wrapper its
`logError()` only — neither reaches `retryHandler`. A step is retried by
`@onlineapps/conn-orch-orchestrator` under the retry policy of its operation,
declared as `retry` in `operations.json` and handed over by the
`operationMutatesLookup` hook (conf `step-error-classification` 002 variant B;
004: "`wrapper.errorHandling.*` is removed"). The four § Removing questions
are answered in this package's CHANGELOG, `[Unreleased]` — `Removed`.
**Kind**: global constant
## REVALIDATION\_SLOW\_MS
The restart cooldown window, and ONLY that: how long a service that failed
validation for the SAME cause waits before it tries again after a restart
(`_applyRestartCooldown()`).
It is not a schedule. Until d.755b a third ladder stage `slow_backoff` claimed
it as one — a 6-hour retry forever — and nothing ever entered that state, so
the claim was never true. The ladder ends at the hourly ceiling with a fatal
teardown, which is the documented end of the road.
**Kind**: global constant
**See**: api/docs/architecture/validator.md - Re-Validation Backoff Schedule
## REVALIDATION\_STATE
Every state the re-validation cycle can be in. TWO backoff stages, because
two is what the concept declares: fast ladder, then hourly up to the ceiling,
then `_shutdownFatally()` — "there is no third retry phase"
(`api/docs/architecture/validator.md` - Re-Validation Backoff Schedule).
**Kind**: global constant
## WRAPPER\_RAISED\_ERROR
The provenance mark: this error was raised by the wrapper, not by a handler.
**Kind**: global constant
## isPositiveIntegerId(value) ⇒ boolean
Is this envelope value a usable tenancy id?
The rule comes from the wire contract, not from this file:
api/docs/biz/10-invocation/mq-envelope.md declares `envelope.tenant_id` an
integer and says "Positive integer.". Zero is explicitly not a value
(api/docs/biz/20-tenancy/multitenancy.md §1.6; the tenant-wide scope was
retired by the owner on 2026-09-03).
A decimal STRING is accepted alongside the number because that is what
already crosses this boundary and is forwarded unchanged — the builder
validates, it never converts. The accepted string form is exact: no sign, no
leading zero, no whitespace, no decimal point, so `"5"` passes while `"05"`,
`" 5"`, `"5.0"` and `"-5"` do not.
**Kind**: global function
| Param | Type |
| --- | --- |
| value | \* |
## isMissingId(value) ⇒ boolean
Is this envelope id missing?
ONE predicate for `workflow_id`, `correlation_id` and `step_id` — three
fields of the same kind, so a value that is a value for one of them is a
value for all three. Until d.363 the first two were checked with
`.length === 0` and the third with `.trim() === ''`, so an id of nothing but
whitespace passed two guards and was refused by the third, inside one method.
The value that got through is not harmless: `workflow_id` and `step_id` name
the storage prefix `content/\* |
## describeRejectedId(value) ⇒ string
How a rejected value may be named in an error message.
A number is safe to print — it carries no foreign data. Anything else is
named by its type ONLY: the envelope is caller-supplied, so a string or an
object could carry a secret or personal data into a log line.
**Kind**: global function
| Param | Type |
| --- | --- |
| value | \* |
## requireSchedulerPublisherFactory() ⇒ function
Továrna plánovače z jádra — načtená LÍNĚ a s hláškou §5.
Port potřebuje z pinovaného `@onlineapps/mq-client-core` jmenný prostor
`scheduler` s továrnou `createSchedulerPublisher`. Verze, která port
plánovače ještě nevydává, se načte BEZ chyby a prostor `scheduler` prostě
nemá — to je druhá větev níž („export chybí"), a běžný případ. Samotné
`require` selže jen tehdy, když jádro nejde načíst vůbec (v `node_modules`
chybí nebo je rozbité) — první větev („modul se nenačte"). Chybějící sekce
`scheduler` v `queueConfig` `require` neshodí: odmítne až složení jména
fronty, tedy volání, ne načtení.
Kdyby se jádro načítalo v hlavičce souboru, spadl by při nenačitatelném
jádru CELÝ wrapper při načtení modulu — tedy i službě, která plánovač vůbec
nepoužívá. Načítá se proto až při stavbě portu: vada pinu se pozná při
stavbě kontextu, jménem slotu a s opravou (`architecture-principles.md` §5),
a ne pádem, který o plánovači nic neříká.
**Kind**: global function
**Returns**: function - `createSchedulerPublisher` jádra
**Throws**:
- Error když jádro továrnu nemá nebo se nenačte
## errorLogFields(err) ⇒ Object
The fields every log line ABOUT an error must carry: the error itself, its
text as `exception.message` and its class as `exception.type` — the
OpenTelemetry semantic-convention attributes, as own, enumerable properties.
`Error.message` is non-enumerable. A meta of `{ err }` therefore survives
`JSON.stringify` as `{ name, code, status, details }` — the sentence saying
what went wrong is gone, except where a `stack` key happens to be passed too,
and then only as the first line of it. Measured (BIZ-converter, dev, wrapper
8.1.1): four of this file's log lines pass no `stack`, so their message did
not reach the operator at all.
Why not a `message` key: the telemetry log envelope carries the record's own
text in its body, and the monitoring consumer merges the body over the data,
so a `message` in the data never reached Loki (measured d.868, DEV Loki).
`exception.type` is the constructor's name, not `err.name`: `BusinessError`
sets `name` itself, so a service subclass that sets none of its own reports
`BusinessError` by name while its constructor still names the class.
One rail for the whole package: `ServiceWrapper` uses it for the two lines it
writes about an error itself (`change-discipline.md` § One rail per concern).
**Kind**: global function
**See**: api/shared/monitoring/monitoring-core/README.md § Wire shape — the telemetry log envelope
| Param | Type | Description |
| --- | --- | --- |
| err | \* | Anything that was thrown. |
## buildEnvelope(status, code, message, [details], [correlation_id]) ⇒ [ErrorEnvelope](#ErrorEnvelope)
Assemble the caller-facing envelope. `details` and `correlation_id` appear
only when supplied — the shape the contract documents, nothing padded.
**Kind**: global function
| Param | Type |
| --- | --- |
| status | number |
| code | string |
| message | string |
| [details] | \* |
| [correlation_id] | string |
## describeFailure(err, [context]) ⇒ Object
THE mapping. One place decides both halves of what a throw becomes:
- `envelope` — what the caller receives;
- `log` — the line whoever HANDLES the throw writes for it.
Two halves, one branching table, because a second copy of the table is how a
caller-facing status and its log line drift apart
(`.claude/rules/change-discipline.md` § One rail per concern).
Pure: it decides, it does not log. [map](#ErrorMapper+map) is the wrapper's
own path and writes the line; [toCallerEnvelope](#toCallerEnvelope) is the path for a
service that already logs the failure itself and needs the envelope only.
**Kind**: global function
| Param | Type | Description |
| --- | --- | --- |
| err | \* | Every `meta` it builds carries the same trace fields: `err`, `exception.message` and `exception.type` (see [errorLogFields](#errorLogFields)), plus BOTH ids of the request, so a search by either one finds the whole trace. |
| [context] | Object | |
| [context.operation] | string | |
| [context.correlation_id] | string | |
| [context.workflow_id] | string | |
## toCallerEnvelope(err, [context]) ⇒ [ErrorEnvelope](#ErrorEnvelope)
The envelope a caller receives for `err` — and NOTHING else. No logger, no
log line, no other side effect: a service that already logged the failure
itself calls this instead of instantiating an [ErrorMapper](#ErrorMapper), so one
failure stays one log line (measured: the converter logged every 5xx twice,
BIZ-converter 2026-09-14).
Same mapping table as [map](#ErrorMapper+map), because it IS the same
function underneath — the two differ only in whether the log half is used.
Contract: api/docs/biz/70-contracts/error-handling.md;
the table: api/docs/biz/10-invocation/handler-dispatch.md § `ErrorMapper` — throw-to-envelope.
**Kind**: global function
| Param | Type | Description |
| --- | --- | --- |
| err | \* | Anything a handler threw. Never rethrown. |
| [context] | Object | |
| [context.operation] | string | |
| [context.correlation_id] | string | |
| [context.workflow_id] | string | |
## \_buildDefaultAjv() ⇒ object
Build the default Ajv instance used when the caller does not inject one.
Change the option set only together with the documents named under See.
**Kind**: global function
**Returns**: object - Configured Ajv instance with ajv-formats applied.
**See**
- api/docs/biz/10-invocation/handler-dispatch.md
- api/docs/governance/confirmations/input-validation-single-rail.md (003)
## \_summariseAjvError(phase, errors) ⇒ string
Summarise the first ajv error into a human-readable string.
Shape: `string | 'input' or 'output'. |
| errors | Array.<object> | ajv error array (fn.errors). |
## \_describeNonAjv(value) ⇒ string
Name what was handed in where an Ajv instance was expected, for the refusal
message. It describes the value, never prints it: the caller knows what it
passed, and a schema compiler's innards are not error-message material.
**Kind**: global function
**Returns**: string - A short noun phrase, e.g. `null`, `number`, `object without compile()`.
| Param | Type | Description |
| --- | --- | --- |
| value | \* | The rejected `options.ajv`. |
## linkAbortSignal(callerSignal, controller) ⇒ function
Tie the caller's own abort signal, when one came with the message, to the
controller this wrapper owns for the attempt: the caller aborting aborts the
attempt too, with the caller's reason (d.1264b).
**Kind**: global function
**Returns**: function - removes the link, or null when there is none
| Param | Type |
| --- | --- |
| callerSignal | AbortSignal \| undefined |
| controller | AbortController |
## readConnOrchOrchestratorContractVersion() ⇒ Object
The wrapper's v3 invocation model wires OrchestratorConnector with invoker RPC,
which the orchestrator has carried since the major above. If npm resolves an
older one (stale tree / lockfile), WorkflowOrchestrator throws
"apiMapper is required" — fail here with an explicit contract error instead.
**Kind**: global function
## describeValidationFinding(finding) ⇒ string
One finding of `ValidationOrchestrator` as a sentence an operator can act on.
`results.errors` is a MIXED array and always has been: steps 2, 4, 5 and 7 push
sentences (the manifest's own `describeFinding`, a cookbook failure), while step
1 — `ServiceStructureValidator` — pushes objects `{ type, path, message, fix }`.
Interpolating that array into a template literal turned every object into
`[object Object]`, so the code (`MISSING_COOKBOOKS`), the path and the way out
were dropped at the last step before the log (`architecture-principles.md` §5;
measured by W591 on a boot whose `tests/cookbooks` was empty).
A sentence travels verbatim — the step that produced it already wrote it in the
`[Context] Problem - Expected/Fix` shape. An object is rendered into that shape
here. Anything else is serialized rather than described: a formatter that threw
would replace the failure it was called to report.
**Kind**: global function
| Param | Type | Description |
| --- | --- | --- |
| finding | string \| object | one entry of `result.errors` |
## describeValidationFailure(errors) ⇒ string
The message the two Tier-1 throw sites raise — the startup path (FÁZE 0.2,
`_ensureValidationProof`) and the hourly revalidation (`_executeRevalidation`).
ONE helper, because one wording of one fact is one rail
(`.claude/rules/change-discipline.md` § One rail per concern).
**Kind**: global function
| Param | Type | Description |
| --- | --- | --- |
| errors | Array.<(string\|object)> | `result.errors` of a failed validation |
## markBootDisposition(error, disposition) ⇒ Error
Stamp the disposition on an error and hand it back, so a `throw` stays one
expression.
**Kind**: global function
**Returns**: Error - the same error
| Param | Type | Description |
| --- | --- | --- |
| error | Error | |
| disposition | string | one of `BOOT_DISPOSITION` |
## failedStaticValidationSteps(result) ⇒ Array.<string>
Which static steps of this result failed.
All five report `{ valid, errors }`; only step 5 answers with `success`, and it
is deliberately not in the list. A step that did not run at all is absent from
`result.steps` — the run fails fast after steps 1 and 3 — and an absent step has
no verdict to read.
**Kind**: global function
**Returns**: Array.<string> - names of the failed static steps, empty when there are none
| Param | Type | Description |
| --- | --- | --- |
| result | object | the value `ValidationOrchestrator.validate()` resolved to |
## markWrapperRaised(err) ⇒ Error
Stamp an error the wrapper is about to raise from inside a handler's call.
**Kind**: global function
**Returns**: Error - The same error, marked.
| Param | Type | Description |
| --- | --- | --- |
| err | Error | The error being thrown. |
## isWrapperRaised(err) ⇒ boolean
Did this wrapper raise the error itself?
**Kind**: global function
| Param | Type |
| --- | --- |
| err | \* |
## ContextBuildResult : Object
What build() resolves to.
**Kind**: global typedef
**See**: api/docs/biz/10-invocation/operation-context.md § Release
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| ctx | OperationContext | Context for this one invocation. |
| release | function | Idempotent teardown hook. Callers MUST await it in a finally block. |
## ErrorEnvelope : Object
MQ response envelope produced by map(). Never null — map() never throws.
**Kind**: global typedef
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| status | number | HTTP-shaped status carried on the envelope. |
| error | [ErrorEnvelopeBody](#ErrorEnvelopeBody) | The error body. |
## ErrorEnvelopeBody : Object
The `error` member of an [ErrorEnvelope](#ErrorEnvelope).
**Kind**: global typedef
**See**: api/docs/biz/70-contracts/error-handling.md
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| code | string | Stable error code (e.g. INTERNAL_ERROR). |
| message | string | Human-readable message; masked for unbranded errors. |
| [details] | \* | Present only for branded business errors. |
| [correlation_id] | string | Echoed from meta when supplied. |
| [type] | string | Error class the thrower declared (`DECLINED`, ...). Present only where `details` is: a masked path carries neither. Absent, never `null`, when the thrower declared none. |
## WorkflowRpcReplyBody : Object
Body published to a caller's reply queue by _publishWorkflowRpcReply().
**Kind**: global typedef
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| status | string | Outcome marker for the RPC caller. |
| [output] | object | Handler output on success. |
| [error] | object | Error envelope on failure. |
| [correlation_id] | string | |
| [workflow_id] | string | |
## OperationEnvelope : Object
What invokeOperation() resolves to. Never rejects — failures arrive as `error`.
**Kind**: global typedef
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| status | number | HTTP-shaped status for this invocation. |
| [result] | \* | Handler result on success. |
| [error] | Object | Error body produced by ErrorMapper on failure. |