Host integration guide

This guide extracts the ownership matrix and handoff procedures from the pre-CRM3 readiness specification so Basenet CRM3 and other opco hosts can integrate without opening the HTML spec.

Synthetic proof is not production validation. Conformance fixtures under examples/crm3/ and examples/packages/ contain no customer data and no live ModelGateway wiring. Host teams must replace synthetic fixtures with sanitized production data before claiming production readiness.

Ownership matrix

Beyond synthetic CRM3 (in-repo enablement)

Synthetic CRM3 under examples/crm3/ remains the language-neutral conformance proof. This repository also ships host-facing seams so Basenet (and other opcos) can progress without pulling host policy into portable core:

Honest remainder (host-only): live ModelGateway wiring, tenant/auth/SSO, retrieval authorization, approval/audit persistence, legal-policy review of customer fixtures, and production promotion controls stay in the Basenet host (see BLI-243 family). Do not import those concerns into templiqx-contracts / templiqx-core / templiqx-ports vocabulary.

ModelGateway consumer contract

The host implements RuntimeAdapter (or HTTP transport compatible with templiqx-runtime-http-mock) and runs the same scenario suite as the mock gateway.

Scenario inventory

Scenarios live under examples/crm3/scenarios/ with inventory at examples/crm3/scenarios/inventory.json. Each scenario has a manifest under examples/crm3/scenarios/<id>/manifest.json.

The complete adapter-parity inventory is:

HTTP conformance runner

Use tools/templiqx-http-conformance against the host adapter URL:

export TEMPLIQX_RUNTIME_URL=https://host-model-gateway.example/v1
export TEMPLIQX_RUNTIME_SCENARIO=intake-document-01
templiqx-http-conformance

Run every ID from the inventory, not a hand-maintained subset. The runner checks the declared status, diagnostic, schema result, output fingerprint, and receipt fingerprint. Compare the normalized aggregate receipt with scripts/golden/http-conformance.json. The mock gateway (tools/templiqx-mock-gateway) is the reference transport; it must not ship as a production adapter.

Rust / CLI / MCP parity

Run the full CRM3 conformance suite locally before pointing at the host:

cargo test -p templiqx-conformance --test crm3
just verify

CLI entrypoint:

templiqx --root examples crm3-conformance --workspace /tmp/templiqx-workspace

Fixture replacement checklist

When CRM3 host integration is ready:

1. Replace synthetic Dutch legal text in scenario manifests with sanitized CRM3 source fragments (legal review required).
2. Keep evidence offsets and grounding checks — draft output must remain tied to source fragments (no invented facts).
3. Run cargo test -p templiqx-conformance --test crm3 against host adapter with the same scenario IDs.
4. Update golden receipts only with GOLDEN_REVIEW: in the commit message.
5. Select a real second Blinqx opco package (post-CRM3, R13) after synthetic portability is proven via examples/packages/synthetic-opco/.

Deployment artifacts

Package trust handoff

Before handing a package to a host, export its canonical identity and run strict verification:

templiqx --root packages export-package-identity crm3
export TEMPLIQX_PACKAGE_SIGNING_KEY="<local-or-ci-secret>"
templiqx --root packages sign-package crm3 --key-id ci \
  --expected-fingerprint "<manifest-fingerprint-from-export>"
templiqx --root packages verify-package-trust crm3 --strict

The environment key and embedded sha256-keyed signature are development/CI controls only. Hosts must not treat them as production publisher identity. Production delivery separately verifies the OCI image digest and its keyless Cosign signature/attestation. Do not put signing keys in package files, command arguments, MCP requests, logs, receipts, or operation envelopes.

Verification entrypoints

just verify          # fmt, clippy, tests, boundaries, CI gates, qlty
just verify-deploy   # Docker, Compose, kind, supply chain (needs Docker)
just fresh-clone     # isolated worktree + empty Cargo cache

Authorized merge context

Packages may declare provenance.requires_authorized_context: "true". The host validator supplies an opaque AuthorizedMergeContext envelope on every render, eval, and compatibility preflight that binds merge data to tenant/matter scope:

Inject the envelope in request context under _templiqx_authorized_merge. The portable core fingerprints and binds the envelope but does not interpret tenant policy. Missing, mismatched, expired, or redacted context fails closed with stable diagnostics (TQX_AUTHORIZED_CONTEXT_*) before evaluation, rendering, or a production-ready compatibility report.

Sanitized examples live under examples/packages/*/fixtures/authorized-context.json. See Cross-opco reference packages.

Host-owned PDF conversion seam

PDF is not a default TempliqxService format selector. After the existing DOCX or HTML artifact is produced, the host invokes an optional conversion adapter that accepts a confined workspace artifact identity (source path, source hash, declared output identity) and returns payload-free renderer metadata: converter ID, version, environment identity, byte size, and output hash.

Minimum host contract:

• confined input/output paths under an ephemeral workspace
• no-network execution and least-privilege filesystem access
• resource limits, source-hash binding, output size/type checks
• cleanup on every outcome (success or failure)
• host-owned encrypted persistence, retention, and access controls

The repository records deterministic conversion fixture metadata for conformance; it does not ship a default PDF converter in templiqx-local, CLI, or MCP. See Document conversion ADR and Template compatibility report.

Explicitly host-blocked

• Real ModelGateway adapter implementation (Basenet host repo)
• Tenant / auth / approval / retrieval policy
• Production fixture ingestion and legal sanitization
• Real second opco selection (R13)
• Schema-valid human-review extraction without host bli-61 agreement (R15)

See Pre-CRM3 readiness and Deployment boundary for core boundaries.

Report-engine assembler handoff (BLI-230)

When assembling merge context for report definitions and grounded contracts, the host owns:

1. Evidence fragments — retrieve and authorize fragments, then pass the portable shape in evidence-fragment-v1alpha1 (identity, UTF-8 offsets, quote_sha256, optional revision checksum).
2. customFields resolution — resolve display names for relation_link values before render so the template engine stays IO-free (merge-data-v1alpha1).
3. Authorized query port — implement DataIntrospectPort / AuthorizedQueryPort behind host OData (or chosen query surface); Templiqx ships traits + synthetic fixtures only (examples/packages/basenet-legal/fixtures/authorized-query-response.json).
4. Revision checksum on fragments — bind DMS revision identity when available (BLI-68) so grounded drafts survive store mutations.

Receipt fingerprint as document_version.checksum (R10)

The Templiqx artifact fingerprint (SHA-256) is the host document-store checksum for generated reports: one document_version row per render, no parallel report-receipt table. See Report engine compatibility.

Host prerequisites (R12)

Tracked host dependencies Templiqx does not build:

Format coverage and non-claims live in Report engine compatibility. Legacy files under examples/legacy-corpus/v5-report-templates/ evidence formats only (DOCX/RTF/BIFF presence); they are Velocity-era binaries, not Templiqx definitions — do not treat them as round-trip fixtures.