@siax/schemas (0.1.0)
Installation
@siax:registry=https://git.cloud.siax.io/api/packages/sax3l/npm/npm install @siax/schemas@0.1.0"@siax/schemas": "0.1.0"About this package
@siax/schemas
P003 (Master Execution Contract) canonical schema catalog: 26 siax.* JSON
Schema (draft 2020-12) documents in ../../schema/, each
with a typed accessor (JSDoc @typedef) and a zero-dependency validation
function here in packages/schemas/. Plus one P000 (Emergency Estate Write
Safety) addition, siax.repository-identity, and one P012 (Network/DB/
Event/Idempotency/SLO Standards) addition, siax.network-policy — see the
table below — bringing REGISTRY's real count to 28.
Zero dependencies. Same convention as packages/doctor: Node ESM
(.mjs), Node ≥ 20, node:test + node:assert/strict for tests, no
external packages. See docs/architecture/decisions/ADR-003-… for why this
package does not use TypeScript or Zod despite both being reasonable choices
in the abstract — that ADR is the place to challenge the call, not this file.
Layout
packages/schemas/
src/
lib/
json-schema-validator.mjs # shared draft-2020-12 SUBSET engine (see its header for exact keyword coverage)
load-schema.mjs # readFileSync+JSON.parse loader, same pattern as doctor.mjs
siax.<name>.mjs # one thin module per canonical schema: SCHEMA + @typedef + validate<Name>()
index.mjs # re-exports everything + REGISTRY (name -> {schema, validate})
test/
json-schema-validator.test.mjs
schemas.test.mjs # one test per schema: a valid AND an invalid example
scripts/
typecheck.mjs # structural self-check (schema <-> module <-> REGISTRY), see its header
The 26 canonical schemas (+ 1 P000 addition, + 1 P012 addition)
| Schema | Concept |
|---|---|
siax.repo.v3 |
Repo identity/tier/production-contract descriptor — additive successor of siax.repo.schema.json (v2) |
siax.repository-identity |
P000. Focused write-safety identity record consumed by authorizeRepositoryWrite (packages/write-guard) — a narrower sibling of siax.repo.v3, not a replacement. |
siax.capability |
A reusable platform function (siax-capability: "one capability, six surfaces") |
siax.surface |
One concrete (capability × API/CLI/MCP/UI/Job/SDK) exposure |
siax.engine |
Underlying compute/data engine (Postgres, NATS, Trino, ...) |
siax.application |
A deployable runtime unit hosting 0..N capabilities |
siax.adapter |
Integration glue between a capability and a provider |
siax.provider |
An external or internal service provider behind an adapter |
siax.business-blueprint |
Customer VIBE desired-state document — successor of siax.blueprint |
siax.change-set |
Diff between current/desired state, pre-ACT0-deploy — successor of siax.changeset |
siax.extension-plan |
A Product-Firewall repo's opt-in plan to consume a platform capability |
siax.deployment |
Canonical deploy descriptor (framework/build/start/port/healthcheck) |
siax.environment |
One named (repo, dev|test|staging|prod) environment record |
siax.event |
AUD0 audit/domain event envelope. P012: field shape RECONCILED to AUD0's own real wire contract (snake_case) — the P003 camelCase shape had zero real producers; see packages/event-client/README.md |
siax.artifact |
ST0RE artifact registry entry |
siax.job |
N0D job contract |
siax.workflow |
ACT0 workflow definition (trigger + steps + approval gates) |
siax.pricing |
Price list for a capability (not a transaction — see B00K for that) |
siax.meter |
Aggregated usage-metering fact for a tenant/capability/period |
siax.license-assessment |
Standalone license-gate record |
siax.source-bundle |
Source→production provenance (repo, commit SHA, build) |
siax.production-evidence |
One entry in the central production-evidence matrix |
siax.slo |
A measurable reliability target. P012: metric enum EXPANDED (latency-p50/p95, rpo, rto, capacity) — see packages/doctor/src/commands/slo.mjs |
siax.backup |
Backup policy (frequency/retention/target/encryption) |
siax.restore-evidence |
Structured proof a restore was actually performed (result: "fail" is a valid, expected value) |
siax.secret-reference |
A reference to an Infisical key — the schema has no value field, by design |
siax.workload-identity |
A non-human principal's identity and scopes |
siax.network-policy |
P012. A default-deny (service, port) reachability rule + who's allowed to reach it — the estate had zero network-policy-as-code before this pass, see packages/network-policy/README.md |
Four of these (repo.v3, business-blueprint, change-set) are evolutions
of pre-existing schema/siax.{repo,blueprint,changeset}.schema.json files.
Per CONTRIBUTING.md ("ALDRIG ändra schemans $id-URL:er"), those files are
untouched — every new/evolved schema here lives at its own new $id.
siax.deployment/siax.environment similarly coexist with, rather than
replace, siax.config.schema.json and doctor's REPO-06 control.
Usage
import { validateRepoV3 } from '@siax/schemas';
// or, to iterate everything:
import { REGISTRY } from '@siax/schemas';
const { valid, errors } = validateRepoV3(candidate);
if (!valid) throw new Error(errors.join('; '));
Testing
node --test packages/schemas/test/*.test.mjs # this package only
node packages/schemas/scripts/typecheck.mjs # structural self-check
Or from the repo root: pnpm test / pnpm typecheck (see root package.json).
Schema versioning: the compatibility snapshot (P003 gap-closing pass)
schemas.test.mjs proves one valid + one invalid example per schema still
behave as expected — it does NOT notice if a schema's top-level SHAPE
itself silently changed (a required field added/removed, a top-level
property added/removed, additionalProperties flipped, $id/title
renamed). test/schema-compatibility.test.mjs closes that gap: it
fingerprints every REGISTRY schema (src/lib/schema-fingerprint.mjs) and
compares it against a committed snapshot,
test/fixtures/schema-compat-snapshot.json. Any drift fails the test suite
by name.
After a DELIBERATE schema change:
node packages/schemas/scripts/update-schema-snapshot.mjs # or: pnpm --filter @siax/schemas update-schema-snapshot
review the diff in schema-compat-snapshot.json, commit it, and add a
CHANGELOG.md line describing whether the change is breaking.
Generated docs (P003 gap-closing pass)
docs/generated/*.md — one markdown fields/types/required reference table
per schema, plus an index (docs/generated/README.md) — is rendered
DIRECTLY from schema/*.schema.json by src/lib/doc-gen.mjs
(pure render functions, unit-tested in test/doc-gen.test.mjs) and written
to disk by scripts/generate-docs.mjs. Before this pass, every piece of
schema documentation in this repo (this README's field table included) was
hand-written and could drift from the schema without anything noticing.
node packages/schemas/scripts/generate-docs.mjs # or: pnpm --filter @siax/schemas docs:generate
test/docs-generated.test.mjs regenerates every doc IN MEMORY and compares
it byte-for-byte against the committed files — a schema change that forgets
to regenerate docs fails the test suite, it does not just go stale quietly.
DoD evidence — Simon's exact 15-field requirement
siax.dod-evidence (schema/siax.dod-evidence.schema.json +
src/siax.dod-evidence.mjs) is the one record type for Repository / Branch
/ Commit SHA / Changed files / Test command / Test result / Positive-path
test / Negative-path test / Type-lint-build result / CI result / Security
impact / Rollback method / PR-MR / Masterplan issue / Final state
(OBSERVED/DISPATCHED/IMPLEMENTED/VERIFIED/BLOCKED/
OWNER_DECISION_REQUIRED). It composes existing vocabulary rather than
duplicating it — see the schema's own description — and its
ciResult/finalState=VERIFIED invariants are enforced the same way
siax.gate-result's aggregateResult already is.
The schema alone only proves a record is internally consistent, not that it
is genuine. bin/dod-evidence.mjs is the CI half that closes that gap:
# produce a record for the current checkout — reads git for real, runs the
# given commands for real, never accepts exitCode/changedFiles/commitSha as
# free-form input:
node packages/schemas/bin/dod-evidence.mjs emit \
--base <base-sha> --test-cmd "<cmd>" --build-cmd "<cmd>" \
--claims claims.json --out dod/<id>.evidence.json
# the actual trust boundary — re-derives every mechanical fact from THIS
# checkout's real git state and RE-EXECUTES every claimed command, failing
# on the smallest mismatch:
node packages/schemas/bin/dod-evidence.mjs verify \
--base <base-sha> --file dod/<id>.evidence.json
.gitea/workflows/dod-evidence.yml runs verify on pull_request,
opt-in: it only acts on PRs that changed a dod/*.evidence.json file.
Honesty contract
Same as packages/doctor: a green validate() result means "conforms to
the JSON Schema subset this engine implements" — it is not a claim that the
described repo/capability/deployment is actually correct, running, or safe.
json-schema-validator.mjs's header documents exactly which draft-2020-12
keywords are supported; an unsupported keyword in a schema fails silently
open rather than throwing, so any new schema added to this catalog must
ship with its own valid+invalid test in schemas.test.mjs — passing tests
are the actual proof, not "the JSON Schema looks right".