Skip to content

docs(spec): reframe 7-segment key format as SDK convention; add server-side requirements - #17

Open
27Bslash6 wants to merge 1 commit into
mainfrom
agent/winston/d4fd98ea
Open

docs(spec): reframe 7-segment key format as SDK convention; add server-side requirements#17
27Bslash6 wants to merge 1 commit into
mainfrom
agent/winston/d4fd98ea

Conversation

@27Bslash6

Copy link
Copy Markdown
Contributor

Companion to cachekit-io/saas#231 (closes cachekit-io/saas#91).

The CachekitIO validator is now security-only; the 7-segment grammar is Python SDK convention, not a server contract.

  • cache-key-format.md: new Server-Side Requirements section documenting exactly what the server enforces (percent-decoded transport, 400-char cap, [a-zA-Z0-9_.:-] charset, .. rejection, ns:/nsapi: namespace shape, write-space split), plus a note on the Full Key Structure marking it SDK-internal.
  • interop-mode.md: status DRAFT → SERVER-SUPPORTED — the validator accepts {ns}:{op}:{hash} keys (scoped to the default namespace); SDK-side generation remains pending (design: cross-SDK interop mode for cache key and value format #1).
  • test-vectors/cache-keys.json: key_format/note fields updated with the convention-vs-contract framing. No vector values changed — cross-SDK byte compatibility untouched.

…r-side requirements

The CachekitIO validator is now security-only (saas#91): percent-decode,
length cap, charset whitelist, '..' rejection, ns:/nsapi: namespace
shape. The 7-segment grammar is Python SDK convention, not a server
contract — TS/Rust {ns}:{hash} and interop-mode keys are valid on the
wire.

- cache-key-format.md: new Server-Side Requirements section + note on
  the Full Key Structure
- interop-mode.md: status DRAFT -> SERVER-SUPPORTED (SDK generation
  still pending, Issue #1)
- test-vectors/cache-keys.json: key_format/note fields updated

Co-authored-by: multica-agent <github@multica.ai>
@27Bslash6

Copy link
Copy Markdown
Contributor Author

Conflict with main in two files, both substantive content disagreements rather than non-overlapping additions:

  • spec/interop-mode.md: HEAD's status line says "SERVER-SUPPORTED... SDK-side generation not yet implemented"; main's says "SPECIFIED (interop/v1)... NOT yet implemented in any SDK." Different factual claims about the same status — picking one drops the other.
  • test-vectors/cache-keys.json: differing generator version, ci_verification field, note, and key_format text between branches — same fields edited with different content on each side.

Neither is a safe automatic union; needs a human call.

@27Bslash6

Copy link
Copy Markdown
Contributor Author

Auto-rebase attempted: merging origin/main produced conflicts in spec/interop-mode.md (contradictory status claims — this PR says "SERVER-SUPPORTED", main says "SPECIFIED, NOT yet implemented") and test-vectors/cache-keys.json. Picking a side changes the spec's meaning — needs a human call. Left the branch untouched.

@27Bslash6

Copy link
Copy Markdown
Contributor Author

Auto-rebase attempted a merge of main but hit conflicts in spec/interop-mode.md and test-vectors/cache-keys.json. The doc conflict is a direct contradiction, not a union — this branch says interop-mode status is "SERVER-SUPPORTED" while main says "SPECIFIED, NOT yet implemented in any SDK." Picking one over the other is a factual call I can't make safely, so I left it for a human.

@27Bslash6

Copy link
Copy Markdown
Contributor Author

Auto-rebase sweep: merging main conflicts on two files with genuinely contradictory content, not additive changes:

  • spec/interop-mode.md: this branch marks interop-mode as "SERVER-SUPPORTED"; main marks it "SPECIFIED (interop/v1) — normative, NOT yet implemented" with different linked references. Picking either overwrites a real status claim from the other side.
  • test-vectors/cache-keys.json: this branch vs main disagree on generator version (v0.5.0 vs v0.12.0), key_format description, and whether a ci_verification field exists.

Needs a human call on which status/version is current. Left unresolved.

@27Bslash6

Copy link
Copy Markdown
Contributor Author

Merge conflict against main in two files, both genuine content disagreements rather than additive unions:

  • spec/interop-mode.md: this branch claims Status is SERVER-SUPPORTED (SDK-side generation not yet implemented), main claims SPECIFIED/normative and NOT yet implemented in any SDK — contradictory implementation-status claims.
  • test-vectors/cache-keys.json: differing generator version (v0.5.0 vs v0.12.0) and differing note/key_format metadata for the same vector set.

Picking a side asserts one version's facts over the other without verifying against the actual cachekit-py implementation — needs a human call.

@27Bslash6

Copy link
Copy Markdown
Contributor Author

Auto-rebase sweep: merging main into this branch conflicts in spec/interop-mode.md (contradictory Status callouts — one claims SERVER-SUPPORTED with SDK generation pending, the other claims SPECIFIED/not-yet-implemented) and test-vectors/cache-keys.json (differing generator version, key_format, and note text, plus a ci_verification field only on one side). Both are substantive content conflicts, not a non-overlapping union — needs a human call on which claims are current.

@27Bslash6

Copy link
Copy Markdown
Contributor Author

Auto-rebase check: base main has moved (main HEAD 936f22f) and this branch now conflicts in spec/interop-mode.md (contradictory status lines — "SERVER-SUPPORTED" here vs "SPECIFIED, not yet implemented" on main) and test-vectors/cache-keys.json (differing generator/ci_verification/note/key_format metadata). Both are genuine content disagreements, not independent additions — needs a human call, not safe to auto-resolve.

@27Bslash6

Copy link
Copy Markdown
Contributor Author

Auto-rebase attempted, left for a human: merging main conflicts in spec/interop-mode.md (competing "Status" blurbs — SERVER-SUPPORTED w/ server-side-requirements link vs. SPECIFIED/normative-not-implemented) and test-vectors/cache-keys.json (different generator versions and note/key_format text). Both are real content conflicts, not a non-overlapping union — needs a call on which description is current.

@27Bslash6

Copy link
Copy Markdown
Contributor Author

Auto-rebase attempted a merge from main but hit a genuine content conflict in spec/interop-mode.md: this branch's status line says interop SDK-side generation is "not yet implemented", while main now says it's "shipped opt-in in all three SDKs" — contradictory claims, not a non-overlapping union. test-vectors/cache-keys.json also conflicts. Needs a human call on which status text is current. Left branch untouched (no push).

@27Bslash6

Copy link
Copy Markdown
Contributor Author

Auto-rebase: could not safely resolve merge conflicts against main (base @ 44ee4370f0604f2336833ac57d843d9747f9a691).

Conflicting paths:

  • spec/interop-mode.md — the branches disagree on the actual status of Interop Mode: this PR's version still says SDK-side generation is "not yet implemented," while main now documents it as "SPECIFIED (interop/v1) — normative, and shipped opt-in in all three SDKs." Resolving this means asserting which claim is currently true, not a mechanical merge — needs a human call.
  • test-vectors/cache-keys.json — overlapping edit tied to the same status change, same reasoning applies.

Leaving the branch untouched; no push made.

@27Bslash6

Copy link
Copy Markdown
Contributor Author

Attempted auto-rebase onto main — conflicts in spec/interop-mode.md and test-vectors/cache-keys.json. Both are competing rewrites of the same status/note text: this branch reframes the interop status as "SERVER-SUPPORTED, SDK-side not yet implemented" and pins generator: cachekit-py v0.5.0, while main has since advanced to "SPECIFIED, shipped opt-in in all three SDKs" with generator: v0.12.0 and a new ci_verification field. Picking either side drops real content from the other — needs a human call on how to reconcile.

@27Bslash6

Copy link
Copy Markdown
Contributor Author

Merge conflict against main in spec/interop-mode.md and test-vectors/cache-keys.json. main has since rewritten the status block (SERVER-SUPPORTED → SPECIFIED/normative, shipped opt-in across all three SDKs) — resolving means picking one side's status claim over the other's, not a non-overlapping union. Needs a human call on which status text is current.

@27Bslash6

Copy link
Copy Markdown
Contributor Author

Auto-rebase sweep: merging main still conflicts in spec/interop-mode.md and test-vectors/cache-keys.json — both remain genuine content disagreements, not a non-overlapping union. main now asserts interop-mode is shipped opt-in in all three SDKs (Python 0.14.0+, TS 0.1.3+, Rust 0.4.0+), while this branch still claims SDK-side generation is "not yet implemented." The test vectors disagree on generator version (v0.5.0 vs v0.12.0) and main adds a ci_verification field this branch lacks. Picking either side asserts a factual claim about SDK implementation status I can't verify — needs a human call. Left branch untouched, no push.

@27Bslash6

Copy link
Copy Markdown
Contributor Author

Auto-rebase check: merging main conflicts on spec/interop-mode.md and test-vectors/cache-keys.json. Both are substantive, contradictory edits (this branch's status blurb says SDK-side interop generation "is not yet implemented"; main's says it's "shipped opt-in in all three SDKs") — not a non-overlapping union, needs a human call on which status is current.

@27Bslash6

Copy link
Copy Markdown
Contributor Author

Flagging for manual resolution. Conflicting paths: spec/interop-mode.md, test-vectors/cache-keys.json. The interop-mode.md status block is a factual contradiction, not a textual one: this PR asserts the CachekitIO validator accepts interop-format keys (security-only validation), while main's rewritten interop/v1 spec (#16) warns the deployed validator rejects them pending saas#91 — which closed hours before that warning was written, so which claim reflects the deployed validator is unverified. Even the cleanly-merging spec/cache-key-format.md hunks would contradict main's interop-mode.md warning. This PR likely needs re-authoring against the interop/v1 spec rather than a mechanical merge; resolving either way risks publishing wrong normative claims, so leaving the branch untouched.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant