Pre-publish docs sweep: README, AGENTS.md, licenses, inline doc fixes

- Add README.md reflecting the v0.1.0 state: 19 AlkType kinds, two
  layout modes, builder + AlkTypeEngine usage example (verified to
  compile and run), validation entry points, crate independence,
  untrusted-schemas guarantee, docs pointers. Mirrors the alkvault
  README structure.
- Add AGENTS.md with alktype-specific git workflow, project
  conventions (no comments, AlkTypeError, untrusted schemas, overflow
  safety, no async, no feature flags, wasm-clean, preserve_order
  load-bearing, no unsafe), verification commands, and ADR/OQ index.
  Blocks auto-commit on semver-relevant public API changes per the
  crates.io 0.1.0 contract.
- Add LICENSE-MIT and LICENSE-APACHE (dual MIT/Apache-2.0, matching
  alkvault and the Cargo.toml license field).
- Cargo.toml: add readme, keywords, categories, rust-version = "1.85".
- Fix broken intra-doc link in builder.rs: DiscriminatorKind ->
  crate::schema::DiscriminatorKind (cargo doc now warning-free).
- N1 (review #002): document is_rfc3339_timestamp as non-strict in the
  function doc comment. Lists the specific gaps (day-of-month per
  month, seconds range, leap seconds) and points consumers needing
  strict validation to chrono/time.
- N2 (review #002): document the FieldValue::Bytes-for-Record API
  asymmetry in the FieldValue enum doc and on read_record_value.
- .opencode/agents/implementation-specialist.md: point to AGENTS.md
  for full convention details (matches the alkvault pattern).
- review #002: mark N1/N2 resolved; all 7 findings now closed.

Verification:
- cargo test --release: 396 tests pass (310 crate + 86 integration)
- cargo clippy --all-targets -- -D warnings: clean
- cargo doc --no-deps: clean (no broken intra-doc link warnings)
- cargo build --target wasm32-unknown-unknown --release: clean
- cargo publish --dry-run --allow-dirty: clean
This commit is contained in:
2026-08-11 09:33:33 +00:00
parent 5f88bca0d8
commit fb3a27f974
10 changed files with 641 additions and 13 deletions

View File

@@ -1,5 +1,5 @@
---
status: resolved (M1, M2, L1, L2, L3); open (N1, N2)
status: resolved (M1, M2, L1, L2, L3, N1, N2)
last_updated: 2026-08-11
reviewed_artifacts:
- src/lib.rs
@@ -514,14 +514,20 @@ the `Validation` variant and `None` for the others. The existing
and `source_returns_some_for_validation_variant` (new). ~6 lines +
~10 lines of tests.
### Deferred
### Deferred → Resolved (docs sweep)
- **N1** (non-strict `is_rfc3339_timestamp`): documented as "simple"
in the existing doc comment. A strict implementation would add a
`chrono` or `time` dependency, not worth it for 0.1.0. Will add an
explicit "non-strict" note in the docs sweep.
- **N2** (`FieldValue::Bytes` for `Record`): API asymmetry, not a
bug. Revisit if the alkcall consumer finds it awkward.
- **N1** (non-strict `is_rfc3339_timestamp`): documented as non-strict
in the function's doc comment. Lists the specific gaps (day-of-month
per month, seconds range, leap seconds) and points consumers needing
strict validation to `chrono` or `time`. ~10 lines of doc in
`src/validation.rs`. A strict implementation would add a dependency,
not worth it for 0.1.0.
- **N2** (`FieldValue::Bytes` for `Record`): documented as a known
asymmetry in the `FieldValue` enum doc and on `read_record_value`.
Notes that every other composite kind returns a typed descriptor while
`Record` returns `Bytes`, and flags the possibility of a future
`FieldValue::Record` variant. ~12 lines of doc across
`src/sequential_reader.rs`.
### L2 (`unreachable!` → `Err`) — resolved (follow-up)
@@ -567,6 +573,5 @@ remaining hit at `offset_map.rs:688` is inside a `#[test]` fn,
guarded by `assert!(matches!(...))` on the line above).
After M1, M2, L1, L2, and L3, the remaining open findings (N1, N2)
are both deferrable to the docs sweep. The crate is ready for the
pre-publish docs sweep (README, inline doc cleanup for docs.rs) and
the final sanity check.
were resolved in the pre-publish docs sweep. All 7 findings are now
closed. The crate is ready for the final sanity check and publish.