Prune the committed spec lock to granted operations + transitive refs #134

New issue

Closed

opened 2026-06-11 00:46:58 +00:00 by coilysiren · 0 comments

coilysiren commented

2026-06-11 00:46:58 +00:00

Owner

Follow-up split from the now-closed lock-pruning sub-item in #106.

The committed spec lock (<spec>.lock.json) is currently the full ~828KB upstream Swagger dump. It is not the consumer's source, it churns the whole blob on every lock, and its provenance is weak (upstream is unversioned). Prune it to only the granted operations plus their transitively-referenced definitions, so the committed artifact becomes small, reviewable, and semantically the consumer's own contract.

Plan

New specverb.Prune(spec, guardfile) ([]byte, error): resolve each grant via the expansion table to an operationId, findOp to (path, method), keep only those path/method operation objects, transitively close $ref: #/definitions/X, preserve top-level metadata, emit indented JSON.
Operate on raw JSON (not the lossy typed reader) to keep full fidelity of the retained subset.
specdrv.Lock: prune the fetched spec before writing the lock, embedding, and the reference doc.
specdrv.Skew: prune the live spec with the same algorithm before diffing, so drift is reported only for operations the consumer actually exposes (ungranted upstream churn is noise).
Re-lock ward so forgejo.swagger.lock.json shrinks to the granted slice.

Origin objection: ward#62 spec-lock bloat, reasserted by Kai.

Follow-up split from the now-closed lock-pruning sub-item in https://forgejo.coilysiren.me/coilyco-flight-deck/cli-guard/issues/106. The committed spec lock (`<spec>.lock.json`) is currently the full ~828KB upstream Swagger dump. It is not the consumer's source, it churns the whole blob on every `lock`, and its provenance is weak (upstream is unversioned). Prune it to only the granted operations plus their transitively-referenced definitions, so the committed artifact becomes small, reviewable, and semantically the consumer's own contract. ## Plan - New `specverb.Prune(spec, guardfile) ([]byte, error)`: resolve each grant via the expansion table to an operationId, `findOp` to (path, method), keep only those path/method operation objects, transitively close `$ref: #/definitions/X`, preserve top-level metadata, emit indented JSON. - Operate on raw JSON (not the lossy typed reader) to keep full fidelity of the retained subset. - `specdrv.Lock`: prune the fetched spec before writing the lock, embedding, and the reference doc. - `specdrv.Skew`: prune the live spec with the same algorithm before diffing, so drift is reported only for operations the consumer actually exposes (ungranted upstream churn is noise). - Re-lock ward so `forgejo.swagger.lock.json` shrinks to the granted slice. Origin objection: ward#62 spec-lock bloat, reasserted by Kai.

coilysiren referenced this issue from a commit

2026-06-11 00:55:54 +00:00

feat(specverb): prune committed spec lock to granted operations

coilysiren closed this issue

2026-06-11 00:55:54 +00:00

coilysiren referenced this issue from coilyco-flight-deck/ward

2026-06-11 01:09:34 +00:00

Re-lock ward-kdl: pruned spec lock + v2 dep lock #84