feat(vim): epic charter and versioned semantic contract v1 (refs OpenCoven/psyche-build#222) - #296
Closed
CompleteDotTech wants to merge 2 commits into
Closed
Conversation
…#222) Additive epic-contract slice for the comprehensive opt-in Vim support epic (Bead psyche-no8): - docs/vim/VIM-EPIC-CHARTER.md: objective, invariants (opt-in, byte-exact terminal passthrough outside explicit chrome mode, host-authority routing for consequential actions), contract-surface ownership map, slice map for OpenCoven#223-OpenCoven#227 with bead acceptance criteria and current status, acceptance order note, and the post-release/OpenCovengh-246 disposition. - src/vim/semanticContract.ts: versioned v1 semantic contract - typed semantic-op union (motion/edit/search/ex/chrome/persistence/accessibility), bounded contexts and payloads, validateOpFixture()/validateOpFixtures() fail-closed validators, chromeModeGuard() classifying every event as terminal passthrough while chrome mode is inactive, and assertChromeOpReachable() fail-closed execution gate. - __tests__/vimSemanticContract.test.ts: 37 tests covering the validator and guard, including chrome-mode-off passthrough, unknown-op rejection, and bounded-payload rejection. Verification: vitest 37/37, tsc --noEmit clean, tsc -p tsconfig.test.json --noEmit clean, git diff --check clean. Refs OpenCoven#222
|
@CompleteDotTech is attempting to deploy a commit to the 0xBuns Team on Vercel. A member of the Team first needs to authorize it. |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds the v1, versioned Vim semantic contract module plus supporting documentation, establishing a shared vocabulary/fixture validator and chrome-mode guard that future platform adapters can implement consistently for the #222 epic.
Changes:
- Introduces
src/vim/semanticContract.tsdefining v1 contexts, op vocabulary, bounded payload limits, strict fixture validation, and a chrome-mode guard. - Adds a focused Vitest suite validating validator/guard invariants and failure-closed behavior.
- Documents the epic charter and captures an execution/verification working record for #222.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| src/vim/semanticContract.ts | New v1 semantic contract: vocabulary, bounds, strict validators, and chrome-mode guard utilities. |
| tests/vimSemanticContract.test.ts | New test suite covering validation rules and chrome-mode guard invariants. |
| docs/vim/VIM-EPIC-CHARTER.md | Epic charter documenting invariants, ownership boundaries, and slice map for the Vim epic. |
| docs/working-records/issue-222-vim-epic-contract.md | Working record capturing scope, risk class, commands run, results, and rollback plan. |
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+146
to
+152
| /** | ||
| * One normalized key input: the platform-agnostic key name (case-sensitive, | ||
| * e.g. `h`, `G`, `Enter`, `Esc`, `F6`) plus the active modifier chord, and — | ||
| * for terminal-originated events — the exact byte sequence that carried it. | ||
| * Raw platform events never reach this contract directly; adapters normalize | ||
| * first (raw event -> normalized key token -> semantic state machine). | ||
| */ |
Comment on lines
+503
to
+512
| function validateBoundedString( | ||
| value: unknown, | ||
| field: string, | ||
| maxLength: number, | ||
| allowEmpty = false, | ||
| ): asserts value is string { | ||
| if (typeof value !== 'string' || (!allowEmpty && value.length === 0) || value.length > maxLength) { | ||
| invalid(`${field} must be a string of length 1..${maxLength}`); | ||
| } | ||
| } |
CompleteDotTech
marked this pull request as ready for review
August 30, 2026 14:50
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Member
|
Closing as superseded by the canonical semantic core already on main. This PR introduces an incompatible second vim/v1 action schema and has unresolved normalization/binding contradictions; preserve the charter discussion only. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Outcome
Focused, additive epic-contract slice for #222 (
psyche-no8,comprehensive opt-in Vim support across Psyche; canonical outcome
#246). It delivers the one versioned semantic contract the five
slices share, plus the epic charter:
docs/vim/VIM-EPIC-CHARTER.md— objective, invariants (opt-in; terminal passthroughbyte-exact outside explicit chrome mode; host-owned consequential actions routed
through typed authority/confirmation/receipt/recovery paths — never editor
shortcuts), contract-surface ownership map, slice map [psyche-no8.1] Vim Slice 1: shared contract and desktop reference #223–[psyche-no8.5] Vim Slice 5: cross-platform acceptance and documentation #227 with acceptance
criteria quoted from the beads and current status, the acceptance-order note
(the beads' mirrored dependency edges are currently inverted; recorded by the
2026-08-30 backlog audit on [psyche-no8] Comprehensive opt-in Vim support across Psyche #222 — the acceptance plan requires
[psyche-no8.1] Vim Slice 1: shared contract and desktop reference #223 → [psyche-no8.2] Vim Slice 2: browser and web parity #224 → [psyche-no8.3] Vim Slice 3: Ink TUI parity #225 → [psyche-no8.4] Vim Slice 4: iOS keyboard parity #226 → [psyche-no8.5] Vim Slice 5: cross-platform acceptance and documentation #227), completion gates, and the post-release
disposition note (Deliver post-release cross-platform Vim and keyboard-mode parity #246 canonical).
src/vim/semanticContract.ts— versioned v1 semantic contract:VIM_SEMANTIC_CONTRACT_VERSION = 1; fixture versionvim/v1(identical to [psyche-no8.5] Vim Slice 5: cross-platform acceptance and documentation #227'sVIM_ACCEPTANCE_FIXTURE_VERSION, so fixture drift fails the gate); typedsemantic-op union over motion / edit / search / ex / chrome / persistence /
accessibility kinds; 13 bounded contexts; bounded payload limits;
validateOpFixture()/validateOpFixtures()strict fail-closed validators(unknown fields at any level, unknown contexts/dispositions/op kinds/op
names/Ex commands, unbounded payloads, duplicate ids, duplicate
(context, normalized-key) cases — all rejected);
chromeModeGuard()classifyingevery event as
terminal-passthroughwhile chrome mode is inactive (includingchrome-bound keys) and exposing chrome ops only in active chrome mode;
assertChromeOpReachable()fail-closed executor assertion;isChromeScopedOp()type guard.
__tests__/vimSemanticContract.test.ts— 37 tests: validator + guard behavior,chrome-mode-off passthrough invariant, unknown-op rejection, bounded-payload
rejection, byte-exact passthrough enforcement, per-context op-kind scoping, and
persistence ops required to carry
route: 'host-authority'.Scope and boundaries
packages/psyche-vim-core/**([psyche-no8.1] Vim Slice 1: shared contract and desktop reference #223's slice),docs/vim/ACCEPTANCE-MATRIX.mdand
src/vim/acceptanceManifest.ts([psyche-no8.5] Vim Slice 5: cross-platform acceptance and documentation #227's slice, on its own branch), or any otherslice's files.
protocol-fixtures/**, the settings schema, or any runtime adapteror entry point — the contract module is intentionally not consumed by any runtime
path yet; wiring it in is [psyche-no8.1] Vim Slice 1: shared contract and desktop reference #223–[psyche-no8.4] Vim Slice 4: iOS keyboard parity #226 implementation work.
index.ts/barrel files,.github/**,.beads/**,pnpm-lock.yaml,package.jsondependencies,docs/ROADMAP.md,docs/SUPPORT-MATRIX.md.documents (
protocol-fixtures/vim/v1/), settings schema, and desktop referenceadapter are [psyche-no8.1] Vim Slice 1: shared contract and desktop reference #223 (in progress); web/[psyche-no8.2] Vim Slice 2: browser and web parity #224, Ink/[psyche-no8.3] Vim Slice 3: Ink TUI parity #225, iOS/[psyche-no8.4] Vim Slice 4: iOS keyboard parity #226 are not started;
[psyche-no8.5] Vim Slice 5: cross-platform acceptance and documentation #227's acceptance manifest contract is delivered on branch
psyche/issue-227-vim-acceptance-docs(not yet merged) and its matrix executionawaits the platform slices.
fork
CompleteDotTech/psyche-buildwith real GitHub Actions CI; the branch is readyfor a maintainer one-click PR to upstream.
Risk class
runtime consumers), one test file, two docs files. No product behavior,
authority, persistence, or transport path is changed. Slices that later wire the
contract into product behavior own the corresponding R3 review for their surfaces.
Validation and evidence
Exact commands, run from the worktree on branch
psyche/issue-222-vim-epic-contract(head
e190cf7, parented onorigin/mainf12b753):npx pnpm install --frozen-lockfileDone in 752ms using pnpm v10.34.5npx pnpm exec vitest --run __tests__/vimSemanticContract.test.tsTest Files 1 passed (1),Tests 37 passed (37)npx pnpm exec tsc --noEmitsrctree)npx pnpm exec tsc -p tsconfig.test.json --noEmitsrc+__tests__)git diff --checkOne intermediate test run failed (1/36) during development: the new duplicate-case
rule correctly rejected two fixtures sharing
editor-command-line::<Enter>in oneset; the test data was split into two sets and all tests then passed.
Explicit gaps (not run here): real Vim/Neovim/tmux smoke sessions and tmux-dependent
repository gates (no tmux on this host; they belong to #227's acceptance matrix);
iOS/Swift and physical hardware-keyboard evidence (no Xcode/iOS tooling here);
desktop Tauri/cargo and browser automation (no cargo/rust here — CI supplies the
runners). This slice is isolated module evidence, not a user-path proof.
Working record
docs/working-records/issue-222-vim-epic-contract.md —
outcome, scope/boundaries, risk class, exact commands/results, exact head SHA, test
counts, proof gaps, rollback.
Generated outputs
None touched; no generator run.
src/utils/generated-agents-doc.ts,native/desktop/psyche-build-tauri/web/*.bundle.js,native/ios/Psyche.xcodeproj/**,generated
Info.plist, anddist/**are unchanged.Security and privacy
private repository contents, environment dumps, private URLs, or unredacted personal
paths are included in this PR or its files.
closed (
TypeError) instead of guessing, chrome-scoped ops are unreachable whilechrome mode is inactive, pending/unsupported sequences can never fall through into a
PTY or text input, and persistence ops must route through
host-authoritypaths rather than executing from editor shortcuts.Review focus
design's chrome table, editor practical-parity surface, and bounded Ex command set
without overreach into [psyche-no8.1] Vim Slice 1: shared contract and desktop reference #223's machine implementation.
inactive; consumed-without-side-effect behavior for unmapped keys while active;
fail-closed
assertChromeOpReachable.nature of chrome close.
Release and support impact
None on current behavior: the feature remains opt-in by default and this slice adds no
runtime code path, no persisted-format change, and no public API surface beyond the new
module. The epic is post-release work (canonical outcome #246);
support-matrix claims are unaffected until platform slices land behind their acceptance
gates.
Refs #222