Skip to content

docs(adapters): define source adapter specification - #15

Merged
leej3 merged 17 commits into
mainfrom
codex/source-adapter-spec
Aug 20, 2026
Merged

docs(adapters): define source adapter specification#15
leej3 merged 17 commits into
mainfrom
codex/source-adapter-spec

Conversation

@leej3

@leej3 leej3 commented Aug 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

AI-generated draft — not reviewed by John

Summary

  • Establish docs/source-adapters.md as the normative host-neutral source-adapter specification.
  • Keep user-facing Things in metadata/records/ and machine PAV in mirrored metadata/overlays/annotations/ companions that join into the same semantic graph.
  • Define the compact decision-cache, DataLad, GitHub review, merge-history, upstream-alignment, and complexity boundaries.
  • Replace the superseded Milestone 5 inventory/transaction exploration with a concise implementation plan and acceptance matrix governed by the specification.
  • Activate Milestone 5 and record the accepted hosted-review and accept/reject/defer decisions in the human and engineering registers.

Review focus

  • The annotation-overlay format and joined validation/RDF boundary.
  • Complete accept, reject, defer, deletion, human-edit, and multiple-adapter behavior.
  • The merge-commit requirement needed to preserve DataLad and human-review commit objects.
  • The explicit prohibition on tracked inventories, manifests, sidecars, reconciliation reports, custom attestations, and expanded threat models.
  • The updated Milestone 5 implementation sequence and evidence matrix.

Scope

  • Replaces the exploratory source-adapter content with one normative specification.
  • Retains useful non-normative observations and a separate implementation-gap report.
  • Aligns Milestone 5, the human-review queue, the architecture roadmap, README, and agent current-work instructions.
  • Makes no runtime, adapter, template, consumer-content, or accepted Milestone 4 implementation change.

Validation

  • Snapper semantic-line-break formatting passed.
  • All relative Markdown links in the changed documents resolve.
  • git diff --check passed.
  • pixi run test-development: 40 tests passed.
  • Local test-engine reached 49 passing tests; its full-fidelity projection case was blocked by the hard-coded sibling consumer checkout currently being on the old unmerged 218-record adapter branch. Hosted clean-checkout CI is running.

leej3 and others added 17 commits August 20, 2026 09:28
@leej3 @codex
docs(adapters): draft source adapter specification
4d6d563 
Define the host-neutral adapter contract, the initial GitHub profile,
upstream reuse boundaries, and explicit complexity guardrails. Record the
remaining review questions without changing the earlier exploration document.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3 @codex
docs(adapters): refine source adapter contract
e346e33 
Specify complete deletion, human-review modification, immutable source,
assertion provenance, and commit-preservation behavior. Separate the target
contract from current implementation gaps and remove provisional versioning.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3 @codex
docs(adapters): simplify review and source evidence
7bbc233 
Treat deletion and review scope as ordinary pull-request changes, bind mutable
sources by identifier and content hash, and make DataLad optional for later
programmatic edits. Attribute each bot commit to its triggering human.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3 @codex
docs(adapters): make review DataLad recording opt-in
ad28a59 
Expose DataLad through the review-application Pixi task without making it
the default for human-driven edits. Remove the resolved choice from the open
questions.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3 @codex
docs(adapters): record DataLad and merge guidance
32ff2a5 
Require DataLad for Pixi-applied metadata changes and place the no-squash
requirement in the adapter pull-request opening text. Leave source-content
canonicalization as an explicit review question.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3 @codex
docs(adapters): preserve human-owned assertions
653250e 
Treat a reviewed human correction as an ownership transfer. Preserve it during
later source runs and surface upstream disagreement as a diagnostic rather
than a proposed reversion.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3 @codex
docs(adapters): define canonical review inputs
77b4a40 
Hash only normalized source facts that can affect proposed metadata and route
all adapter YAML through one schema-aware canonicalizer. Clarify human review
as the merge authority and define baseline interaction between adapters.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3 @codex
docs(adapters): clarify canonical merge behavior
d7e00bd 
Normalize the existing corpus once, preserve list order by default, and keep
semantic comparison separate from YAML serialization. Permit clean adapter
rebases while requiring conflicting proposals to rerun, and retain only the
most recently accepted source PAV.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3 @codex
docs(adapters): preserve exact DataLad commits
4131119 
Require merge commits or true fast-forwards for accepted adapter lineages.
Permit independent branches to merge in either order, regenerate overlapping
proposals, and treat the canonical corpus as an established precondition.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3 @codex
docs(adapters): use Git conflict boundaries
d39a6d8 
Let ordinary Git determine whether independent adapter proposals compose cleanly.
Require regeneration only after a merge conflict and avoid introducing a
separate semantic-conflict analyzer.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3 @codex
docs(adapters): tighten conformance boundaries
6e8a82e 
Make merge commits a downstream prerequisite, base review invalidation only on
changed output, and keep validation errors out of durable decision state.
Remove redundant commit trailers and move implementation gaps out of the
normative specification.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3 @codex
docs(adapters): align contract with upstream
68f215c 
Adopt Dump Things mapping order and list preservation, require complete
source and Things validation, and map the reused upstream primitives.
Record deliberate ownership, deletion, retained-proposal, and source
coordinate deviations.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3 @codex
docs(adapters): preserve unchanged provenance
1bf517e 
Compare assertion semantics independently of PAV. Preserve existing
ownership when an incoming assertion is identical, and transfer PAV only
with an accepted substantive assertion change.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3 @codex
docs(adapters): consolidate source adapter spec
c32a402 
Replace the exploratory source-adapters document with the reviewed
host-neutral contract and retain only useful non-normative design notes.
Store machine PAV in mirrored metadata provenance companions that join
with user-facing records for validation and RDF export.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3 @codex
docs(adapters): define annotation overlay
2fe0c17 
Name metadata/overlays/annotations as the sole semantic overlay for
adapter PAV companions. Reserve any additional overlay for a focused
specification change with deterministic join and validation rules.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3 @codex
docs(adapters): make specification normative
fcb5485 
Promote the reviewed source-adapter contract from a draft reference.
Require clarification before material ambiguity expands authority, durable
state, the threat model, or implementation architecture.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3 @codex
docs(milestone): align milestone 5 with spec
c8d1e32 
Replace the superseded inventory and transaction exploration with a
concise implementation and acceptance wrapper around the normative
source-adapter contract.

Record the accepted hosted review, disposition, merge-history, and
annotation-overlay decisions, and make Milestone 5 the active effort.

Co-Authored-By: Codex Desktop 26.814.41407 (runtime codex-cli 0.148.0-alpha.15) / gpt-5.6-sol <codex@openai.com>
Codex-Reasoning-Effort: ultra
@leej3

leej3 commented Aug 20, 2026

Copy link
Copy Markdown
Collaborator Author

"currently being on the old unmerged 218-record adapter branch" consumer will be updated rewritten by the implementation of this more precise spec.

@leej3
leej3 marked this pull request as ready for review August 20, 2026 18:15
@leej3
leej3 merged commit 829ee92 into main Aug 20, 2026
3 checks passed
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

@leej3