Skip to content

feat(meshlink): wire codec scaffold + audit config alignment (#32-#35) - #36

Merged
trancee merged 19 commits into
mainfrom
audit/production-readiness
Aug 20, 2026
Merged

feat(meshlink): wire codec scaffold + audit config alignment (#32-#35)#36
trancee merged 19 commits into
mainfrom
audit/production-readiness

Conversation

@trancee

@trancee trancee commented Aug 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Wire Codec Scaffold + Audit Configuration Alignment

Implements Vertical slice 4 from the scaffold alignment plan, plus audit configuration fixes.

Wire Codec Scaffold (PR #35)

  • 7 source files: ByteOrder, FieldType, Field, WireFrame (model layer) + FrameReader, FrameWriter, FrameCodec (codec layer)
  • 7 test files: Full AAA test coverage for all wire codec types and operations (79 test methods)
  • FrameType.fromCode() companion method for wire code validation
  • Renamed sizeBytes to byteCount for clarity

Audit Configuration (PRs #32-#34)

  • Power-assert compiler plugin with 8 assertion functions
  • 9 wrong-package test files moved to correct packages; 5 missing tests added; JUnit5 useJUnitPlatform() made explicit
  • minSdk standardized from 26 to 21 across all module .gradle.kts files and doc references

Constitution Check (Principle-by-Principle I-V)

Principle I — Quality Gates: All gates green — Spotless, Detekt (zero suppressions), Kover (100% line + branch), BCV apiCheck, yamllint, markdownlint, spec validation.

Principle II — Spec Alignment: validate-specs.sh passes. No spec changes in this PR.

Principle III — Explicit API: explicitApi() unchanged. Public API surface changes only from the wire codec (new types). meshlink.api regenerated via jvmApiDump.

Principle IV — Test-Driven Development: AAA pattern throughout. Power-assert configured. 100% coverage for all new wire codec code.

Principle V — Documentation: Specs updated (specification-map.yaml traceability). Docs aligned with code changes.

Files in this PR

  • 18 new files in meshlink/src/{commonMain,commonTest}/kotlin/ch/trancee/meshlink/wire/
  • Modified: Enums.kt (added FrameType.fromCode()), EnumCoverageTest.kt (ByteOrder + fromCode tests), meshlink.api (regenerated), specification-map.yaml (traceability)
  • 14 audit config files (power-assert, JUnit5, minSdk, yamllint, validate-specs configs)

phil Wayfinder Agent @trancee
docs: add production-readiness audit report and findings
2deb915 
Audit MeshLink-template repository for spec-code-doc alignment and
production-readiness per the wayfinder map (#15). All 8 research
tickets resolved; 11 follow-up issues created (#25-#35).

Verdict: infrastructure is production-ready for implementation.
2 critical gaps (power-assert plugin missing, frames.yaml YAML error)
should be addressed before protocol-layer work begins.

Supporting evidence in research/*.md; cohesive report in
docs/reference/audit-production-readiness.md.

Co-authored-by: Wayfinder Agent <agent@omp.local>
@trancee trancee mentioned this pull request Aug 19, 2026
Closed
9 tasks
phil and others added 5 commits August 20, 2026 07:36
phil Your Agent @trancee
chore(meshlink): enable power-assert compiler plugin for test diagnos…
88243fb 
…tics

Configure org.jetbrains.kotlin.plugin.power-assert in :meshlink KMP
build, transforming kotlin.test assertions to produce rich diagnostics
on failure. Essential for security-critical crypto tests where opaque
boolean assertions make debugging difficult.

- Add kotlin-power-assert plugin to version catalog
- Declare in root build.gradle.kts with apply false
- Apply in meshlink/build.gradle.kts with transformed function list

Resolves #32

Co-authored-by: Your Agent <agent@example.com>
@trancee Your Agent
docs: mark power-assert finding #32 as resolved in audit report
8ab6f96 
Update audit-production-readiness.md to reflect that the power-assert
compiler plugin is now configured in meshlink/build.gradle.kts.
Reduces the critical-gaps count from 2 to 1 (frames.yaml remains).

Co-authored-by: Your Agent <agent@example.com>
@trancee Your Agent
fix: resolve YAML structural error in frame_type_enum
14d1348 
The frame_type_enum block in specs/codecs/frames.yaml had a mapping
key (description) followed by sequence items (- name:) at the same
indentation level, producing invalid YAML that silently passed all CI
gates (yamllint ignores specs/, validate-specs.sh only checks existence).

Fix: wrap the sequence items under a proper 'values:' sub-key, matching
the pattern used in enums.yaml's FrameType enum definition.

Verified with:
- python3 yaml.safe_load: 15 entries parse correctly
- yamllint: clean (exit 0)
- scripts/validate-specs.sh: all checks pass

Resolves #25

Co-authored-by: Your Agent <agent@example.com>
@trancee Your Agent
docs: mark frames.yaml finding #25 as resolved in audit report
c572b45 
Update audit-production-readiness.md to reflect that the YAML
structural error in frames.yaml frame_type_enum is fixed.
Both critical findings from the audit are now resolved.

Co-authored-by: Your Agent <agent@example.com>
@trancee Your Agent
feat: integrate validate-specs.sh into CI and git hooks
34717f3 
Previously validate-specs.sh only ran locally — CI ran yamllint
(ignoring specs/) and the Gradle build checked file existence only.
This is why the frames.yaml YAML structural error (#25) passed
all gates silently.

- Add Spec validation step to CI workflow (after YAML lint)
- Add spec validation to pre-commit hook (triggers on specs/,
  SPEC.md, docs/decisions/, docs/reference/ changes)
- Add spec validation to pre-push hook (same triggers, full verification)
- Add scripts/validate-specs.sh to bash -n hook validation list

Resolves #26

Co-authored-by: Your Agent <agent@example.com>
@trancee
trancee force-pushed the audit/production-readiness branch from 5b817b4 to 34717f3 Compare August 20, 2026 05:58
trancee and others added 10 commits August 20, 2026 08:23
@trancee Your Agent
feat: configure yamllint for specs/ + real enum validation
baa36fa 
Part 1: yamllint now covers spec files
- Created .yamllint-spec with relaxed line-length (specs use long
  inline strings up to 248 chars) but strict structural rules
- Added CI step: yamllint -c .yamllint-spec specs/
- Updated pre-commit/pre-push hooks to use .yamllint-spec for spec YAML
- Fixed 3 spec files missing trailing newlines (enums.yaml,
  specification-map.yaml, settings.yaml) — were invisible under
  the old specs/ ignore

Part 2: Real enum cross-check replaces no-op
- validate-specs.sh step 4 now extracts FrameCode constants from
  Enums.kt and FrameType codes from enums.yaml, compares them
  - Verified: 15 wire codes match between enums.yaml and Enums.kt

This closes the gap that allowed the frames.yaml YAML structural
error (#25) to pass all CI gates silently — yamllint now runs on
specs/ with structural checks enabled.

Resolves #27

Co-authored-by: Your Agent <agent@example.com>
@trancee Your Agent
docs: mark yamllint enum validation finding #27 as resolved
bfe7567 
Update audit-production-readiness.md to reflect that spec files are
now linted with yamllint (via .yamllint-spec) and enum cross-check
is real (not a no-op). Spec validation pipeline findings: 0 remaining.

Co-authored-by: Your Agent <agent@example.com>
@trancee Your Agent
fix: align SPEC.md ADR references, traceability table, and naming
b5c5818 
- Add 5 missing ADR references to SPEC.md content sections:
  meshlink-crypto-dependency.md (§12.4), mesh-size-limits.md (§8.10),
  persistence-strategy.md (§5.6), payload-identity-and-naming.md (§9.1),
  transfer-source-sink-contract.md (§9.2)
- Fix §7 traceability row: expand abbreviated ADR paths to full
  docs/decisions/... prefix; fix error-hierarchy.md to use
  docs/decisions/model/ (not crypto/)
- Add missing §10 Power row to traceability index table
- Update §5, §8, §9, §12 traceability rows to include newly-referenced ADRs
- Fix spec-anchor naming: setting-model → settings-model (SPEC.md
  §14.3 + specs/catalogs/settings.yaml) — aligns with ADR filename,
  TOC entry, and traceability map section anchor

Resolves #28

Co-authored-by: Your Agent <agent@example.com>
@trancee Your Agent
docs: mark SPEC.md content consistency finding #28 as resolved
68d53ab 
Co-authored-by: Your Agent <agent@example.com>
@trancee Your Agent
fix: complete spec-to-code traceability mapping
32197cd 
- Added 29 missing source files to cross_references code_files lists:
  2 in architecture, 19 in data-model, 1 in discovery-identity, 2 in
  transport-layer, 3 in security-layer (incl. PayloadDecision.kt),
  1 in routing-layer, 11 in transfer-layer, 1 in configuration-model
- Added peer-identity-model to spec_anchors_in_code (was in code,
  missing from map — PeerIdentity.kt had SPEC-ANCHOR but map didn't list it)
- Updated enums comment to list all 3 files: Enums.kt, PayloadDecision.kt,
  L2capState.kt (was only listing Enums.kt)
- All 42 source files now listed in at least one code_files entry (0 missing)
- validate-specs.sh: all 7 checks pass; yamllint: exit 0

Resolves #29

Co-authored-by: Your Agent <agent@example.com>
@trancee Your Agent
fix: complete spec-to-code traceability mapping
6cf6dd1 
- Added 29 missing source files to cross_references code_files lists:
  2 in architecture, 19 in data-model, 1 in discovery-identity, 2 in
  transport-layer, 3 in security-layer (incl. PayloadDecision.kt),
  1 in routing-layer, 11 in transfer-layer, 1 in configuration-model
- Added peer-identity-model to spec_anchors_in_code (was in code,
  missing from map — PeerIdentity.kt had SPEC-ANCHOR but map didn't list it)
- Updated enums comment to list all 3 files: Enums.kt, PayloadDecision.kt,
  L2capState.kt (was only listing Enums.kt)
- All 42 source files now listed in at least one code_files entry (0 missing)
- validate-specs.sh: all 7 checks pass; yamllint: exit 0

Resolves #29

Co-authored-by: Your Agent <agent@example.com>
@trancee Your Agent
fix: refine not_implemented precision for type vs integration status
984661b 
Split two over-broad not_implemented entries into types (implemented)
and functional integration (not_implemented):

- 'Message and transfer handles, sources, and sinks' →
  types moved to implemented; integration wiring stays not_implemented
- 'MeshLinkSettings DSL integration' →
  data model construction-time validation moved to implemented;
  DSL-to-MeshLink wiring stays not_implemented

This corrects the status to reflect that all type definitions are
real, tested implementations; only the MeshLink.kt wiring is pending.

Resolves #30

Co-authored-by: Your Agent <agent@example.com>
@trancee Your Agent
docs: mark not_implemented precision finding #30 as resolved
d8e097e 
Update audit report: finding #10 marked resolved, follow-up table
updated, conclusion updated to 4 remaining tickets.

Co-authored-by: Your Agent <agent@example.com>
@trancee MeshLink Audit Agent
fix: resolve all broken SPEC.md/doc cross-reference links (#31)
0d91b62 
- Add HTML anchor tags (<a id>) before Pandoc {#id} headings in SPEC.md
  to make custom anchors work on GitHub while preserving {#id} syntax for
  validate-specs.sh SPEC-ANCHOR validation
- Fix heading-name anchors across 15 docs/reference/*.md files: add
  section-number prefix (e.g. #security-layer → #7-security-layer)
- Fix 15 spec_section anchors in specification-map.yaml
- Fix 3 non-existent anchors: #public-api-surface→#meshlink-public-api,
  #error-hierarchy-sealed→#error-hierarchy,
  #transfer-session-state-transitions→#transfer-session-model
- Fix 2 sub-heading anchors: #key-rotation-protocol→#54-key-rotation-protocol,
  #advertisement-format→#41-advertisement-format
- Apply same fixes to 20 ADR files in docs/decisions/
- Add blank lines after HTML anchors to satisfy MD022 markdownlint rule

Co-authored-by: MeshLink Audit Agent <agent@meshlink.dev>
@trancee MeshLink Agent
chore(meshlink): complete power-assert, test organization, JUnit5, mi…
7177930 
…nSdk alignment (#32-#34)

- #32: Enable kotlin-power-assert plugin with 8 kotlin.test.* assertion functions
- #33: Move 9 wrong-package test files to correct modules; add 5 missing tests
       for 1:1 Foo.kt/FooTest.kt mapping; add explicit useJUnitPlatform()
- #34: Standardize minSdk from 26 to 21 across all 3 module build files and
       all doc references to match MeshLink-crypto dependency floor

Co-authored-by: MeshLink Agent <agent@trancee.io>
This was referenced Aug 20, 2026
Closed
Closed
Closed
@trancee trancee changed the title docs: add production-readiness audit report feat(meshlink): wire codec scaffold + audit config alignment (#32-#35) Aug 20, 2026
@trancee
trancee merged commit 21c0022 into main Aug 20, 2026
7 checks passed
@trancee
trancee deleted the audit/production-readiness branch August 20, 2026 17:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@trancee