[takashi-matsuyama]

Summary

@basou/core now ships JSON Schema artifacts for every on-disk .basou/ document, generated from the canonical Zod schemas (zod v4's built-in z.toJSONSchema) so they cannot drift from validation. Non-JavaScript / cross-language tooling and editors can now validate .basou/ files directly. This is the schema-reference artifact unblocked by the @basou/sdk v0.2 keystone (per the operator's own plan: deferred until a programmatic consumer existed).

One schema per document — manifest, session, event (a oneOf over the event type), task, approval, status, task-index, session-import — each a draft 2020-12 document with a stable $id (https://basou.dev/schemas/0.1.0/<name>.schema.json), published under the package's ./schemas/* export (e.g. @basou/core/schemas/session.schema.json) and listed in files.

Design (operator-confirmed)

• Zod is the single source of truth; JSON Schema is generated + drift-guarded (not hand-authored).
• 8 document schemas (full on-disk set + import transport).
• Prefixed-id fields carry a faithful ULID pattern via .meta() on the shared id factory — metadata only, validation behavior unchanged (the .refine still gates acceptance). Verified to accept all 79 real local session ids and reject malformed ones.
• $id uses basou.dev (a stable identifier; need not resolve).

Correctness (from adversarial review)

Artifacts are generated in io: "input" mode, so they describe what a consumer authors on disk, not Zod's parsed output:

• a field with a .default() (e.g. events_log) stays optional, not required;
• a non-strict object allows additive fields (no additionalProperties: false), while the .strict() event variants (e.g. adapter_output) keep additionalProperties: false.

Without this, the artifacts would falsely reject valid on-disk files — the opposite of their purpose.

Generation & guards

• pnpm --filter @basou/core gen:schemas builds, then regenerates the committed packages/core/schemas/*.json from buildJsonSchemas().
• A drift-guard test asserts every committed file matches the Zod source byte-for-byte (a schema change without regeneration fails CI).
• An ajv draft-2020-12 round-trip test validates a representative document per schema, plus the input-mode cases and that the ULID pattern rejects a malformed id (this is what would have caught the input-vs-output bug).
• The generated schemas/ dir is excluded from biome (a generated artifact, like dist).

Compatibility

Additive: new ./schemas/* export, gen:schemas script, and ajv/ajv-formats devDependencies. No @basou/core runtime-API or on-disk-format change. Branches from main (which now carries #40 + #41).

Test plan

• pnpm -r build && pnpm typecheck && pnpm test && pnpm lint all green (core 732 + sdk 17 + cli 417; lint clean apart from pre-existing unrelated warnings).
• Regeneration is deterministic (re-running gen:schemas yields no diff).
• ajv round-trip confirms each emitted schema compiles and accepts real documents.

🤖 Generated with Claude Code