[P0-03] Add shared document conformance fixtures and round-trip tests #11

New issue

Closed

opened 2026-07-22 00:09:17 +00:00 by lost-rob0t · 3 comments

lost-rob0t commented

2026-07-22 00:09:17 +00:00

(Migrated from github.com)

Problem

The server contains its own as-json/from-json implementation while the star-cl dependency also exposes encode/decode. Their behavior and tests have drifted. There is no language-neutral fixture suite proving equivalent field names, null behavior, lists, nested objects, revisions, timestamps, unknown fields, or migrations.

This violates the canonical auto-research document contract, which requires type, requiredness, null behavior, mutability, merge rules, migrations, and shared conformance fixtures.

Required changes

Define versioned canonical JSON fixtures for every maintained document type.
Include valid, minimally valid, fully populated, malformed, unknown-field, null, false, empty-list, nested-object, and CouchDB _rev cases.
Add encode→decode→encode semantic round-trip assertions.
Add fixtures shared with star-cl, Nim, and JavaScript implementations.
Record schema/document version and migration expectations.
Make conformance a required CI job.

Acceptance tests

Every supported dtype has at least one round-trip fixture.
Empty array, false, null, absent, and empty string remain distinguishable according to the contract.
Cross-language encoded output is semantically equivalent.
An implementation missing a required field or changing a key name fails CI.

## Problem The server contains its own `as-json`/`from-json` implementation while the `star-cl` dependency also exposes `encode`/`decode`. Their behavior and tests have drifted. There is no language-neutral fixture suite proving equivalent field names, null behavior, lists, nested objects, revisions, timestamps, unknown fields, or migrations. This violates the canonical auto-research document contract, which requires type, requiredness, null behavior, mutability, merge rules, migrations, and shared conformance fixtures. ## Required changes - Define versioned canonical JSON fixtures for every maintained document type. - Include valid, minimally valid, fully populated, malformed, unknown-field, null, false, empty-list, nested-object, and CouchDB `_rev` cases. - Add encode→decode→encode semantic round-trip assertions. - Add fixtures shared with `star-cl`, Nim, and JavaScript implementations. - Record schema/document version and migration expectations. - Make conformance a required CI job. ## Acceptance tests - Every supported dtype has at least one round-trip fixture. - Empty array, false, null, absent, and empty string remain distinguishable according to the contract. - Cross-language encoded output is semantically equivalent. - An implementation missing a required field or changing a key name fails CI.

lost-rob0t commented

2026-07-26 13:02:56 +00:00

(Migrated from github.com)

Implementation started in draft PR #63.

Current contract:

v0.9.0 is the sole read/write schema
v0.8.0 remains read/index-only through a CLOS schema-profile anti-corruption adapter
legacy flat-field mappings are derived from active document classes with closer-mop
the shared corpus covers all 49 v0.9 dtypes plus v0.8 index and malformed cases
CI now has Python corpus validation and an executable CLOS/MOP conformance stage

The PR is stacked on server v0.9 PR #54 and remains draft until the companion star-cl v0.9/codec gates are green.

Implementation started in draft PR #63. Current contract: - v0.9.0 is the sole read/write schema - v0.8.0 remains read/index-only through a CLOS schema-profile anti-corruption adapter - legacy flat-field mappings are derived from active document classes with `closer-mop` - the shared corpus covers all 49 v0.9 dtypes plus v0.8 index and malformed cases - CI now has Python corpus validation and an executable CLOS/MOP conformance stage The PR is stacked on server v0.9 PR #54 and remains draft until the companion `star-cl` v0.9/codec gates are green.

lost-rob0t commented

2026-07-26 13:19:55 +00:00

(Migrated from github.com)

PR #63 now has both required gates green.

Verified:

fixture contract passes with exact coverage of all 49 v0.9 dtypes
CLOS/MOP conformance passes
v0.8 flat documents project into the v0.9 index shape without becoming writable v0.9 documents
null, false, empty array, empty string, absent, and nested object remain distinguishable
invalid CouchDB revisions and unknown v0.9 top-level keys are rejected
companion star-cl v0.9 workflow passes after fixing its unbalanced normalize-required-data-v09 form

The PR remains draft because it is stacked on server PR #54 and star-cl PR #1.

PR #63 now has both required gates green. Verified: - fixture contract passes with exact coverage of all 49 v0.9 dtypes - CLOS/MOP conformance passes - v0.8 flat documents project into the v0.9 index shape without becoming writable v0.9 documents - null, false, empty array, empty string, absent, and nested object remain distinguishable - invalid CouchDB revisions and unknown v0.9 top-level keys are rejected - companion star-cl v0.9 workflow passes after fixing its unbalanced `normalize-required-data-v09` form The PR remains draft because it is stacked on server PR #54 and star-cl PR #1.

lost-rob0t commented

2026-07-26 13:45:56 +00:00

(Migrated from github.com)

Completed on the v0.9 server integration branch via merged PR #63.

Validation:

fixture-contract: passed
clos-conformance: passed
companion star-cl v0.9 contract: passed

Merge commit: c8bf5087f8f58364bca13e15c0de3f081fc70091.

Completed on the v0.9 server integration branch via merged PR #63. Validation: - fixture-contract: passed - clos-conformance: passed - companion star-cl v0.9 contract: passed Merge commit: `c8bf5087f8f58364bca13e15c0de3f081fc70091`.