Docs feedback and analytics boundary

The static docs site does not connect to Postgres. A trusted service boundary validates privacy-safe feedback and interaction signals, applies rate/size limits, and writes to Postgres suite schema docs. Runtime configuration for docs platform behavior is stored as audited settings in docs.platform_setting.

Canonical contract

• Contract: docs/contracts/docs-feedback-analytics-boundary.md in the repository.
• Migrations: migrations/0011_docs_feedback_analytics.sql, migrations/0011_docs_feedback_api.sql.
• Disposable test DB: tools/testdb.sh (Postgres 18 container on loopback; never production).
• DB tests: node --test tools/db/test_feedback_analytics.mjs.

Data model (suite)

Table	Purpose
docs.doc_page, docs.doc_version	Canonical page metadata and published versions
docs.doc_feedback	Bounded helpful/not-helpful submissions; no PII
docs.doc_signal	Privacy-safe search/docs signals; useful/helpful feedback emits signals
docs.doc_job, docs.doc_job_run	Publish/platform jobs and attempt history
docs.platform_setting, docs.platform_setting_history	Runtime-editable settings and revision history
docs.setting_audit_event	Immutable audit for setting/admin mutations
docs.doc_feedback_rollup	Materialized summary buckets for hot reads
docs.schema_migration	Migration ledger

Service boundary rules

• Static site calls HTTPS endpoints only; service uses prepared statements/SQL API functions.
• No PII, no raw IP/account identifiers in these tables, no secret values in settings history/audit (secret refs only).
• Feedback comments are optional, scrubbed, and capped at 500 characters.
• Setting updates require actor/request context and expected revision; audit/history rows commit with the setting change.
• var/docs-engine/cycles.db remains a local developer cache only; production runtime state is tracked for migration under DOCS-ENGINE-CYCLE-DB.

Operational verification

Contract and schema added on 2026-11-05 in worktree card/DOCS-FEEDBACK-ANALYTICS-DB. Verification commands and EXPLAIN evidence are recorded in docs/evidence/DOCS-FEEDBACK-ANALYTICS-DB.md.