From a8918c6ff123c8541340bb00ad2a0eeb56dcdb0a Mon Sep 17 00:00:00 2001 From: Weksa Date: Tue, 10 Nov 2026 05:03:33 +0000 Subject: [PATCH] EditDraft and EntryDraft: the editor's JSON read once, ids and revisions the store's Co-Authored-By: Claude Sonnet 5.5 --- crates/weksa/src/encode.rs | 255 ++++++++++++++++++++++++++++++++-- crates/weksa/src/inventory.rs | 5 + 2 files changed, 251 insertions(+), 9 deletions(-) diff --git a/crates/weksa/src/encode.rs b/crates/weksa/src/encode.rs index 430f360..c8b37a2 100644 --- a/crates/weksa/src/encode.rs +++ b/crates/weksa/src/encode.rs @@ -1,15 +1,23 @@ -//! The encoder step: what a model's answer becomes. This is the one place JSON -//! is read (the xenos boundary): a model answers in JSON, `PacketDraft::parse` -//! reads it, and nothing is stored as JSON. The model writes meaning only; -//! `into_packet` sets the id, schema version, inventory revision, kind, +//! The encoder and editor steps: what a model's answer becomes. This is the one +//! place JSON is read (the xenos boundary): a model answers in JSON, +//! `PacketDraft::parse` or `EditDraft::parse` reads it (both through +//! `from_json`), and nothing is stored as JSON. The encoder writes meaning +//! only; `into_packet` sets the id, schema version, inventory revision, kind, //! provenance, constraints and extensions, and an empty trace, so a model that -//! saw a Validation item cannot hand its words to whoever reads packets. +//! saw a Validation item cannot hand its words to whoever reads packets. The +//! editor writes family, gloss, value kind and slots only; `into_revision` sets +//! every id and revision number. use std::fmt; +use std::num::NonZeroU32; +use serde::de::DeserializeOwned; use serde::{Deserialize, Serialize}; use crate::corpus::CorpusItemId; +use crate::inventory::{ + Change, Family, InvId, Inventory, InventoryEntry, InventoryRevision, Slot, ValueKind, +}; use crate::packet::{ Constraints, Context, Discourse, EncoderId, Grade, Packet, PacketId, PacketKind, Predication, Provenance, ProvenanceSource, Referent, Relation, SCHEMA_VERSION, Stance, Trace, @@ -58,12 +66,17 @@ impl fmt::Debug for DraftError { impl std::error::Error for DraftError {} +/// The one JSON read of a model's answer. +fn from_json(answer: &str) -> Result { + serde_json::from_str(answer.trim()).map_err(|e| DraftError { + line: e.line(), + column: e.column(), + }) +} + impl PacketDraft { pub fn parse(answer: &str) -> Result { - serde_json::from_str(answer.trim()).map_err(|e| DraftError { - line: e.line(), - column: e.column(), - }) + from_json(answer) } /// The draft that says what `packet` says. @@ -105,6 +118,87 @@ impl PacketDraft { } } +/// The most changes (adds and retires together) one edit may make. +pub const MAX_EDIT_CHANGES: usize = 8; + +/// One entry an edit adds, as the editor writes it: no id and no revision. +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct EntryDraft { + pub family: Family, + pub gloss: String, + #[serde(default)] + pub value_kind: Option, + #[serde(default)] + pub applies_to: Vec, +} + +/// An inventory edit as the editor writes it: entries to add and ids to retire. +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct EditDraft { + #[serde(default)] + pub add: Vec, + #[serde(default)] + pub retire: Vec, +} + +impl EditDraft { + pub fn parse(answer: &str) -> Result { + from_json(answer) + } + + /// The revision after `base` this edit asks for, and the entries it adds. + /// `None` when the edit makes no change or more than [`MAX_EDIT_CHANGES`]. + /// Every id is the store's: an added entry takes the next number of its + /// family after the highest in `inventory`, retired entries included, in + /// draft order. Nothing else is judged here: the gloss, the entry's shape, + /// whether a retire target is live and a repeated id are + /// `InventoryStore::admit_revision`'s to refuse. + pub(crate) fn into_revision( + self, + inventory: &Inventory, + base: u32, + ) -> Option<(InventoryRevision, Vec)> { + let count = self.add.len() + self.retire.len(); + if count == 0 || count > MAX_EDIT_CHANGES { + return None; + } + let n = base.checked_add(1)?; + let mut entries: Vec = Vec::new(); + for draft in self.add { + let highest = inventory + .entries() + .map(|e| e.id) + .chain(entries.iter().map(|e| e.id)) + .filter(|id| id.family() == draft.family) + .map(|id| id.n().get()) + .max() + .unwrap_or(0); + entries.push(InventoryEntry { + id: draft.family.id(NonZeroU32::new(highest.checked_add(1)?)?), + gloss: draft.gloss, + value_kind: draft.value_kind, + applies_to: draft.applies_to, + introduced_rev: n, + retired_rev: None, + }); + } + let changes = entries + .iter() + .map(|e| Change::Add(e.id)) + .chain(self.retire.into_iter().map(Change::Retire)) + .collect(); + let revision = InventoryRevision { + n, + parent: Some(base), + changes, + frozen: false, + }; + Some((revision, entries)) + } +} + /// `encoder:`, a digest of the model id and the prompt digest. pub fn encoder_id(model: &str, prompt_digest: &str) -> EncoderId { let digest = fnv1a64(format!("weksa-encoder-v1:{model}:{prompt_digest}").as_bytes()); @@ -228,4 +322,147 @@ mod tests { assert!(!text.contains("CANARY"), "{text}"); } } + + fn entry(id: &str, retired: Option) -> InventoryEntry { + let id = InvId::parse(id).unwrap(); + InventoryEntry { + id, + gloss: "g".into(), + value_kind: (id.family() == Family::Extension).then_some(ValueKind::Flag), + applies_to: vec![], + introduced_rev: 1, + retired_rev: retired, + } + } + + fn add(family: Family, gloss: &str) -> EntryDraft { + EntryDraft { + family, + gloss: gloss.into(), + value_kind: None, + applies_to: vec![], + } + } + + #[test] + fn ids_are_the_stores() { + // concept:1 live, concept:3 retired (the highest), frame:2 live; no role. + let inv = Inventory::new( + vec![ + entry("concept:1", None), + entry("concept:3", Some(2)), + entry("frame:2", None), + ], + vec![], + ); + let draft = EditDraft { + add: vec![ + add(Family::Concept, "first"), + add(Family::Role, "role"), + add(Family::Concept, "second"), + add(Family::Frame, "frame"), + ], + retire: vec![ + InvId::parse("concept:1").unwrap(), + InvId::parse("frame:2").unwrap(), + ], + }; + let (rev, entries) = draft.clone().into_revision(&inv, 6).unwrap(); + let ids: Vec = entries.iter().map(|e| e.id.to_string()).collect(); + // After the highest of the family, retired ones included, in draft order. + assert_eq!(ids, ["concept:4", "role:1", "concept:5", "frame:3"]); + assert_eq!((rev.n, rev.parent, rev.frozen), (7, Some(6), false)); + assert!( + entries + .iter() + .all(|e| e.introduced_rev == 7 && e.retired_rev.is_none()) + ); + let glosses: Vec<&str> = entries.iter().map(|e| e.gloss.as_str()).collect(); + assert_eq!(glosses, ["first", "role", "second", "frame"]); + // Adds in draft order, then the retires in draft order. + let changes: Vec = rev + .changes + .iter() + .map(|c| match c { + Change::Add(id) => format!("+{id}"), + Change::Retire(id) => format!("-{id}"), + }) + .collect(); + assert_eq!( + changes, + [ + "+concept:4", + "+role:1", + "+concept:5", + "+frame:3", + "-concept:1", + "-frame:2" + ] + ); + } + + #[test] + fn the_change_count_is_one_to_eight() { + let inv = Inventory::new(vec![entry("concept:1", None)], vec![]); + let adds = |n: usize| EditDraft { + add: (0..n) + .map(|i| add(Family::Concept, &format!("g{i}"))) + .collect(), + retire: vec![], + }; + assert!(adds(0).into_revision(&inv, 1).is_none()); + assert!(adds(1).into_revision(&inv, 1).is_some()); + assert_eq!(adds(8).into_revision(&inv, 1).unwrap().1.len(), 8); + assert!(adds(9).into_revision(&inv, 1).is_none()); + // Adds and retires count together. + let mixed = |a: usize, r: usize| EditDraft { + add: (0..a).map(|_| add(Family::Concept, "g")).collect(), + retire: vec![InvId::parse("concept:1").unwrap(); r], + }; + assert!(mixed(4, 4).into_revision(&inv, 1).is_some()); + assert!(mixed(4, 5).into_revision(&inv, 1).is_none()); + assert!(mixed(0, 9).into_revision(&inv, 1).is_none()); + // A repeated retire is the door's to refuse, not this fn's. + assert!(mixed(0, 2).into_revision(&inv, 1).is_some()); + } + + #[test] + fn an_edit_draft_reads_what_an_editor_may_write() { + let d = EditDraft::parse( + r#" {"add":[{"family":"Feature","gloss":"g","value_kind":{"Options":["a","b"]},"applies_to":["Referent"]}],"retire":["concept:2"]} "#, + ) + .unwrap(); + assert_eq!(d.add[0].family, Family::Feature); + assert_eq!(d.add[0].applies_to, [Slot::Referent]); + assert_eq!(d.retire, [InvId::parse("concept:2").unwrap()]); + // Both lists default; value_kind and applies_to default. + let d = EditDraft::parse(r#"{"add":[{"family":"Concept","gloss":"g"}]}"#).unwrap(); + assert_eq!(d.add[0].value_kind, None); + assert!(d.add[0].applies_to.is_empty() && d.retire.is_empty()); + assert_eq!(EditDraft::parse("{}").unwrap().add.len(), 0); + } + + #[test] + fn an_edit_draft_refuses_what_the_store_writes() { + // An id, a revision number or a retired mark is the store's to write. + for field in ["id", "introduced_rev", "retired_rev", "n", "parent"] { + let json = format!(r#"{{"add":[{{"family":"Concept","gloss":"g","{field}":1}}]}}"#); + assert!(EditDraft::parse(&json).is_err(), "{field} in an entry"); + } + for field in ["revision", "frozen", "changes"] { + let json = format!(r#"{{"add":[],"{field}":1}}"#); + assert!(EditDraft::parse(&json).is_err(), "{field} in an edit"); + } + // A family or a retire id that is not one. + assert!(EditDraft::parse(r#"{"add":[{"family":"Nope","gloss":"g"}]}"#).is_err()); + assert!(EditDraft::parse(r#"{"retire":["concept:0"]}"#).is_err()); + assert!(EditDraft::parse(r#"{"retire":[1]}"#).is_err()); + // Not JSON, not an object, an error that names no token. + let err = EditDraft::parse("{\n \"add\": CANARYTOKEN").unwrap_err(); + assert_eq!((err.line, err.column), (2, 10)); + for text in [err.to_string(), format!("{err:?}")] { + assert!(!text.contains("CANARY"), "{text}"); + } + assert!(EditDraft::parse("3").is_err() && EditDraft::parse("\"x\"").is_err()); + } } diff --git a/crates/weksa/src/inventory.rs b/crates/weksa/src/inventory.rs index 6c8b984..ec59b13 100644 --- a/crates/weksa/src/inventory.rs +++ b/crates/weksa/src/inventory.rs @@ -85,6 +85,11 @@ impl InvId { pub fn family(self) -> Family { self.family } + + /// The `n` of `:`. + pub fn n(self) -> NonZeroU32 { + self.n + } } impl fmt::Display for InvId {