Alexandria
Decisions (ADRs)

0009. Vocabulary Hub v0.2.1 Decisions (DP-1..15) & Open Questions (Q1..17)

Summary of design decisions (DP-1 to DP-15), integration architecture, and open specification questions (Q1 to Q17) for Vocabulary Hub v0.2.1.

0009. Vocabulary Hub v0.2.1 Design Decisions (DP-1..DP-15) & Open Questions (Q1..Q17)

  • Status: Superseded by 0010
  • Date: 2026-11-09

This record summarizes the 15 architectural decisions (DP-1 to DP-15), workspace integration choices, and specification resolutions (Q1 to Q17) documented in DECISIONS.md and OPEN_QUESTIONS.md.


1. Core Design Decisions (DP-1 to DP-15)

IDAreaDecisionImplementation Packages
DP-1Language, Module & DependenciesPromoted to the root module (github.com/ging/alexandria). vhub packages import only the Go standard library, modernc.org/sqlite (no cgo), github.com/santhosh-tekuri/jsonschema/v6 (offline Draft 2020-12), and gopkg.in/yaml.v3 (restricted to internal/dsl). Enforced in CI by internal/archtest.go.mod, internal/archtest
DP-2Persistence & Immutabilityalexandria-server uses embedded SQLite (modernc.org/sqlite) with BEFORE UPDATE and BEFORE DELETE triggers on releases, revocations, listings, and events (REQ-HUB-013). BlobStore is content-addressed on disk (<dir>/sha256/<hex>). alexandria-client persists continuity, packages, and agreements via atomic tmp + rename writes.internal/server/adapters/sqlite, internal/server/adapters/blob_fs, internal/client/adapters/store_fs
DP-3Authentication on /v1auth_static reads config/tokens.json (Bearer token -> {principal, roles[]}) and enforces the §3.6 authorization matrix (REQ-HUB-017). internal/server/module.go also exposes the http_v1.Authenticator port for external IAM injection.internal/server/adapters/auth_static, internal/server/module.go
DP-4Hub Key & DID Document (Q15)signer_file manages an Ed25519 PKCS#8 PEM key and supports controlled rotation (Rotate), publishing the new key in PublishedKeys() before signing (REQ-HUB-015). http_did serves GET /.well-known/did.json.internal/server/adapters/signer_file, internal/server/adapters/http_did
DP-5did:web Resolutiondid_web resolves did:web:<host> over HTTPS (https://<host>/.well-known/did.json). Cleartext http:// is permitted only when the host is 127.0.0.1 or localhost and -did.allow_insecure_localhost is explicitly enabled.internal/client/adapters/did_web
DP-6 & DSLProfile Compilers (poc & dsl)compiler_poc compiles simplified Part 5.1 JSON drafts; compiler_dsl ("compiler": "dsl") compiles alexandria.profiles/v1 YAML bundles (OdrlProfile + SpaceProfile) with N1–N5 validation and deterministic artifact generation.internal/dsl, internal/server/adapters/compiler_dsl, internal/server/adapters/compiler_poc
DP-7Client Evaluator (evaluator_poc)Executes json-schema artifacts offline, verifies that @context entries in shacl slots belong to the package manifest (CONTEXT_NOT_IN_PACKAGE, REQ-CLI-010), and skips RDF shacl graph execution with informational code POC_EVAL_UNSUPPORTED_ROLE.internal/client/adapters/evaluator_poc
DP-8Simulated Transparency Log (Q2, Q17)scitt_fake (server) and receipt_scitt_fake (client) issue and verify JCS-signed {digest, registered_at, log_id, sig} receipts behind the TransparencyLog and ReceiptVerifier ports.internal/server/adapters/scitt_fake, internal/client/adapters/receipt_scitt_fake
DP-9Injectable ClockNo production package outside internal/clock calls time.Now() (enforced by AST scan in internal/archtest). Provides system_clock and file_clock (-clock-file / VHUB_CLOCK_FILE) to replay multi-month lifecycles in seconds.internal/clock, internal/core/timex, internal/archtest
DP-10Default DSP Route Table (Q3)When routes is empty or omitted in config.json, alexandria-client loads the 16 normative DSP 2025-1 routes (config/routes.default.json) in observe mode.internal/client/domain/routes.go, config/routes.default.json
DP-11DSP Error Bodies & VHub-Verdict (Q4)In DSP 400 rejections, missing providerPid or consumerPid values default to the sentinel "urn:uuid:00000000-0000-0000-0000-000000000000". VHub-Verdict is serialized as an RFC 9651 List of Tokens in route.gates order.internal/client/domain/verdict.go
DP-12alexandria-server Config Schema (Q16)config/server.json is validated on startup against config/server.schema.json.internal/server/config, config/server.schema.json
DP-13Reconciliations R1–R11 & D-PVP-1 (Q9, Q12)Uses exclusively the F2–F5 nomenclature (new_content_from, enforced_from, revoked_from, state Revoked, single DID document key without roles.json or current.json, and mandatory url in application/ld+json manifest entries).internal/core, internal/server, internal/client
DP-14Deployment Preconditions (PRE-01..05)Assumed by environment in config/ and deploy/; client estimates clock skew via the Hub's HTTP Date header and emits CLOCK_SKEW_EXCEEDED when abs(skew) > clock_skew (REQ-CLI-025).internal/client/app/status.go, internal/server/adapters/httpx
DP-15Public /pub Caching (Q13)/pub is served without authentication: Cache-Control: public, max-age=31536000, immutable + ETag: "<hex-sha256>" on versioned/hash-addressed paths, and 303 See Other with Cache-Control: no-cache on /pub/{slug} and /pub/spaces/{slug}.internal/server/adapters/http_pub, internal/server/app/publication.go

2. Status of F7 Open Questions (Q1 to Q17)

IDQuestion in F7Blocks v1?Resolution in Alexandria
Q1Signature envelope {kid, alg, sig} over JCS vs JWS (RFC 7515) or VC Data IntegrityNoImplements {signed, signature: {kid, alg: "EdDSA", sig}} over JCS(signed) in internal/core/sign.
Q2Format and verification of SCITT transparency receiptsYesDP-8: Encapsulated behind TransparencyLog and ReceiptVerifier ports (scitt_fake / receipt_scitt_fake).
Q3Default route table alignment with DSP 2025-1 and EDC/FIWARE extensionsYesDP-10: 16 default DSP routes loaded in observe mode when routes is empty.
Q4Required PIDs in ContractNegotiationError / TransferError when absent in requestYesDP-11: Uses sentinel UUID "urn:uuid:00000000-0000-0000-0000-000000000000".
Q5Active catalog audit identityNoImplements passive catalog audit (§4.10, internal/client/app/audit.go, REQ-CLI-023).
Q6Pre-deployment agreements (import vs synthetic pre-hub version)NoImplements POST /agreements:import requiring the version to exist in known packages (REQ-CLI-026).
Q7Hub key compromise and absence of root of trust over did:webNoVerified at reception time (S2, S9, V1–V4) and never re-verified retroactively (REQ-CLI-024).
Q8Incorporating §2.10 delta parameters, LIFECYCLE_*, and D-PVP-1 into the DSL specYesImplemented in both compiler_dsl and compiler_poc.
Q9Aligning F0 with F2–F5 date and state nomenclatureYesDP-13: Exclusive use of F2–F5 nomenclature across code and schemas.
Q10Per-message latency budget when evaluating multiple versions in V_tNoClassify evaluates head first and only evaluates prior versions in V_t if head fails; exports vhub_client_request_duration_seconds.
Q11Garbage collection of retained packages and agreement expirationNoPackageStore.Retain retains all versions in versions[] plus any version referenced by registered agreements (REQ-CLI-017).
Q12Aligning Governance rev. 2 §16–§19 with R10 (single DID document key, no roles.json)YesDP-13: No roles.json or current.json exists in the codebase.
Q13Public /pub vs member-restricted /pubNoDP-15: /pub is public and immutable (REQ-HUB-011).
Q14DID methods beyond did:web (did:key, did:ebsi)NoSchema A.3 restricts Hub DID to did:web, while app.DIDResolver port allows injecting additional resolvers from internal/ssi-auth.
Q15Who serves the Hub's DID Document (G1)NoDP-4: alexandria-server serves GET /.well-known/did.json from Signer.PublishedKeys().
Q16alexandria-server configuration format (G2)NoDP-12: config/server.json validated against config/server.schema.json.
Q17TransparencyLog and ReceiptVerifier port interfaces (G5)YesDP-8: Defined in internal/server/app/ports.go and internal/client/app/ports.go.

On this page