docs(v2): API reference cleanup and working examples (2/3)

.audit/pro-2457-api-reference-decisions.tsv

@@ -0,0 +1,31 @@
+ts	phase	decision	why	evidence	result
+2026-10-21T18:37:14.055494+00:00	frame	Review all 53 V2 API pages and both public schema exports	The user needs readable docs and SDK contracts without internal fields	pages.json	baseline captured
+2026-10-21T18:37:14.055690+00:00	workspace	Use a separate application checkout under the T3 worktrees directory	/workspace is read-only on this Mac; avoid changing the existing application branch	/Users/soham/.t3/worktrees/hydradb-application/pr310-public-api-20261021	clean branch from staging 2e8622bc4
+2026-10-21T18:37:14.055696+00:00	research	Keep the memory deletion runtime unchanged	Current handler already returns per-ID results; stale docs caused the mismatch	application/internal/api/handler/context.go:1203	focused HTTP tests passed
+2026-10-21T18:37:14.055712+00:00	design	Derive docs and SDK from the same released contract	The current pre-withholding fork leaks different fields into each export	application/scripts/openapi/main.go:110	implementation pending
+2026-10-21T18:48:09.016388+00:00	design	Keep attributes and temporal_now excluded despite the second design reviewer's contrary advice	The user explicitly said both fields must be hidden and metadata remains supported	user instruction; pr310-public-contract-design-grok-20261022-r1	original contract requirements retained
+2026-10-21T18:48:49.641525+00:00	harness	Add a CI check for public query fields, nested graph types, page bindings, JSON examples, and empty anchors	Recurring schema and documentation mistakes should fail a check rather than rely on another instruction	.github/verify_v2_public_contract.py	old schema fails 12 requested contract checks
+2026-10-21T18:48:49.641822+00:00	verification	Reserve full 53-page browser coverage for the final regenerated schema	Complete source baseline and reproduced visual bugs cover the original state without duplicating the final run	baseline-docs.json; browser-baseline-grok/raw.jsonl	initial browser pass bounded
+2026-10-21T18:56:05.856360+00:00	baseline	Treat initial browser receipts as issue evidence rather than a clean before snapshot	48 pages loaded but two served pages did not match the on-disk baseline; final coverage will use one server	browser-baseline-grok/_coverage.json	INCONCLUSIVE for complete baseline parity
+2026-10-21T18:58:44.126111+00:00	review	Remove query fusion and temporal-filter diagnostic blocks from both public outputs	These fields expose internal ranking accounting; keep the returned dated facts and durations	application/internal/domain/search/app_search_fusion.go; application/internal/domain/search/temporal.go	runtime unchanged; export update in progress
+2026-10-21T19:09:54.812201+00:00	verification	Restart the docs preview after changing the OpenAPI snapshot	The preview still showed the old non-nullable error field after the JSON file changed	api-reference/v2/openapi.json; final-dev.log	endpoint browser checks wait for fresh preview
+2026-10-21T19:29:18.118553+00:00	review	Keep unknown-ID subgraph behavior out of the prose	The user explicitly requested removing that Notes section; restoring it would undo the requested simplification	pr310-public-editorial-review-grok-20261022-r1; endpoint/subgraph.mdx	review finding dismissed with user instruction
+2026-10-21T19:29:18.119007+00:00	review	Fix five editorial review findings and strengthen the contract guard	Preserve canonical metadata, correct title fields, keep indexing batch behavior, and validate nested schemas	pr310-public-editorial-review-codex-20261022-r1; pr310-public-contract-fix-verifier-20261022-r2	all findings fixed; final request-example guard verified in r3
+2026-10-21T19:29:18.119013+00:00	verification	Validate all handwritten response payloads against their endpoint schemas	JSON syntax alone missed real nullable response fields	verify_v2_public_contract.py; application/scripts/openapi/public_shapes.go	58 response examples pass after source schema correction
+2026-10-21T19:29:18.119017+00:00	verification	Inspect every V2 API page against the final schema	The user requested browser inspection of each page, including nested fields	.audit/pro-2457-api-browser.json	53 pages pass; 44 endpoint bindings; two edited pages rechecked
+2026-10-21T19:29:18.119021+00:00	verification	Exercise generated TypeScript deserialization in SDK helper tests	Typed relation fields use camelCase and previously lost relationship labels	application/scripts/fern/test_helpers.py	six formatter tests pass including generated serializers
+2026-10-21T19:29:18.119024+00:00	verification	Report full local SDK generation as failed	Both Fern container runs exited 137 despite producing the model and serializer files	/tmp/pr310-sdk-generation-parent-rerun.log; application/.audit/public-api-handoff.txt	not a full generation pass; no SDK was published
+2026-10-21T19:29:18.119029+00:00	verification	Keep V1 and archive anchor warnings outside this V2 task	The final link scan found four pre-existing anchor warnings outside V2	/tmp/pr310-public-contract-20261021/final-links.log	no V2 link findings; Mintlify validation and hygiene pass
+2026-10-21T19:33:31.128304+00:00	verification	Remove the remaining unknown-ID subgraph sentence from the source export	The user requested omitting this implementation quirk	application/scripts/openapi/docs_view_text_core.go; .audit/pro-2457-api-browser.json	only unbound alias description changed; 44 bound operations and schemas unchanged
+2026-10-21T19:36:49.010049+00:00	verification	Diagnose SDK generation failure with a retained container	Avoid guessing that exit 137 means memory exhaustion	docker inspect f003e9d47066 State.OOMKilled=true ExitCode=137	confirmed local Docker OOM; bounded generator heap trial in progress
+2026-10-21T19:46:55.137877+00:00	review	Fix the two independent source review warnings	Preserve free-text dates and null names, and model null webhook/catalog values accurately	application commit 69b4ad16b; failing then passing focused fixtures	generator tests and eight SDK helper tests pass
+2026-10-21T19:46:55.138179+00:00	verification	Complete SDK generation with a bounded Node heap	The retained stock container confirms Docker OOM; the same pinned generator filesystem completes within a smaller heap	.audit/pro-2457-sdk-generation.json	full Fern CLI generation and generated-code checks pass; no published config change
+2026-10-21T19:46:55.138184+00:00	verification	Recheck all pages affected by nullable schema corrections	Operation and referenced-schema comparison identifies five pages with changed rendered contracts	.audit/pro-2457-api-browser.json	five new browser checks pass; all 53 raw receipts match summary
+2026-10-21T19:46:55.138188+00:00	status	Resolve earlier implementation-pending and export-in-progress log entries	Those rows describe the state when recorded, not the final result	application commit 69b4ad16b; docs current snapshot	shared source policy, nested types, public descriptions and docs snapshot implemented
+2026-10-21T20:02:56.000358+00:00	review	Restore provider catalog authentication in the source annotation	The auth-only router requires a token; the generated contract omitted it	application commit a3272cf71; local HTTP generated-client test	old SDK test fails without auth; regenerated SDK sends Bearer token
+2026-10-21T20:02:56.000948+00:00	review	Publish two corpus choices outside Query	Keep released endpoint instructions and generated fields consistent; graph all does not combine corpora	withholdUnifiedSurface; TestReleasedContextSelectorsAndProviderAuth	knowledge and memory published; Query retains all
+2026-10-21T20:02:56.000955+00:00	review	Correct generated response semantics and examples	Batch success can differ from request acceptance; memory deletion is a count; successful webhook errors are null	application commit a3272cf71	source descriptions and examples corrected
+2026-10-21T20:02:56.000959+00:00	review	Preserve metadata limits and connected graph examples	Shortening must retain enforced limits, distinct entity names and matching relation endpoints	TestPublishedQueryGraphExamplesStayConnected; shared metadataFiltersDescription	500 values per list and 64 KiB retained; scoped graph examples stay connected
+2026-10-21T20:02:56.000963+00:00	verification	Recheck all nine pages affected by the review fixes	Compare each operation and its schema references to avoid assuming the rest changed	.audit/pro-2457-api-browser.json	nine browser rechecks pass; 53 total receipts remain consistent
+2026-10-21T20:09:27.184100+00:00	review	Use one corpus description for the graph routes	The path alias retained a third choice after its enum was narrowed	application commit 1db00c82f; docs CI guard; subgraph browser recheck	both subgraph forms and relations now use the same two-choice description; no schema shape change
+2026-10-21T20:18:39.372933+00:00	compatibility	Preserve combined List and Delete requests	Existing split-database handlers support all without the unified feature flag. Hide unified while retaining all for these two endpoints. Graph reads keep knowledge and memory.	Source regression red then green; 10 SDK tests pass; complete Fern generation passes; two changed pages browser-checked.	Fixed published enum regression.

.audit/pro-2457-sdk-generation.json

@@ -0,0 +1,22 @@
+{
+  "generator": "fernapi/fern-typescript-sdk:3.69.0",
+  "base_image_id": "sha256:abba03d3eb4400a0093ed4ed790a939164fcfcb1e75f314e60b0250262a54199",
+  "temporary_image_id": "sha256:de3e013e9871ae1718d5b6bec8b426f0f0fb2740a620331705d18b800ebba3fd",
+  "filesystem_layers_identical": true,
+  "entrypoint_identical": true,
+  "only_environment_difference": "NODE_OPTIONS=--max-old-space-size=384",
+  "ir_version": "v59",
+  "openapi_input_sha256": "0a9f515722c8c88e758e5e04d41fbdf5214e229b1bbe6e55c9587451d5214410",
+  "full_fern_cli_exit_code": 0,
+  "generated_code_checks": "passed",
+  "sdk_helper_tests": 10,
+  "sdk_helper_skips": 0,
+  "includes_generated_null_preservation_test": true,
+  "stock_generator_attempts": "Docker OOMKilled=true, exit 137",
+  "repository_generator_config_changed": false,
+  "sdk_published": false,
+  "local_generation_log": "/tmp/pr310-combined-sdk-generation.log",
+  "local_helper_log": "/tmp/pr310-combined-sdk-helper.log",
+  "includes_generated_provider_auth_http_test": true,
+  "includes_generated_combined_selector_test": true
+}