Documentation
¶
Index ¶
Constants ¶
const ( // WriteEvidenceComplete signals the originating write succeeded and // (if applicable) any pending relation candidates were stored. WriteEvidenceComplete = "goncho_write_complete" // WriteEvidenceCancelled signals the submission was cancelled before the // write started; storage was not mutated. WriteEvidenceCancelled = "goncho_write_cancelled" // WriteEvidenceRelationFailed signals the originating write succeeded but // candidate detection failed; no relations were stored. The write is // authoritative and is not rolled back. WriteEvidenceRelationFailed = "goncho_relation_detection_failed" // WriteEvidenceWriteFailed signals the originating write itself failed; // no relations are recorded and the caller must retry or surface the // underlying error. WriteEvidenceWriteFailed = "goncho_write_failed" )
Write evidence codes returned by Submit. Keep these in sync with operator docs; they are part of the public contract.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CandidateDetector ¶
type CandidateDetector interface {
Detect(ctx context.Context, w MemoryWrite, prior []MemoryWrite) ([]RelationCandidate, error)
}
CandidateDetector inspects a write against existing memories and returns pending relation candidates. Returning an error must not cause the originating write to fail; callers record the failure as evidence and proceed.
type MemoryStore ¶
type MemoryStore interface {
Apply(ctx context.Context, w MemoryWrite) error
List(ctx context.Context) ([]MemoryWrite, error)
}
MemoryStore is the seam the write queue uses to persist memories. Apply must be safe to call from a single goroutine; the queue serializes calls.
type MemoryWrite ¶
MemoryWrite is the Goncho-native shape submitted to the serialized write queue. It is intentionally narrower than the full Honcho message envelope: the queue only needs a stable ID and the content/tags the detector can inspect to surface relation candidates.
type RelationCandidate ¶
type RelationCandidate struct {
From string // memory ID the relation originates from
To string // memory ID the relation targets
Verb RelationVerb // canonical Goncho relation vocabulary
Note string // free-form note for later human/LLM judgment
EvidenceIDs []string // durable evidence IDs supporting the candidate edge
}
RelationCandidate is one PENDING relation between two memories awaiting later judgment. The detector returns these synchronously after a write completes; storage must not block the originating write.
type RelationStore ¶
type RelationStore interface {
SavePending(ctx context.Context, candidates []RelationCandidate) error
}
RelationStore persists pending relation candidates. Implementations must treat the candidates as PENDING — no judgment, no LLM, no resolution.
type RelationVerb ¶
type RelationVerb string
RelationVerb names a Goncho-native relation between two memories. The vocabulary is intentionally Honcho-compatible and does not surface Engram-specific identifiers in any public Gormes/Honcho API.
const ( // RelationRelated is the catch-all "see also" link between two memories. RelationRelated RelationVerb = "related" // RelationConflicts marks a contradiction that may need human or judge // resolution; the original write still succeeds and the candidate is // stored as PENDING. RelationConflicts RelationVerb = "conflicts_with" // RelationSupersedes marks the new memory as replacing an older one. RelationSupersedes RelationVerb = "supersedes" // RelationCompatible marks two memories as not in conflict and reinforcing. RelationCompatible RelationVerb = "compatible" // RelationScoped marks a relation that only holds inside a narrower scope // (e.g. one session or one peer card slot). RelationScoped RelationVerb = "scoped" // RelationNotConflict explicitly records that a candidate inspected by the // detector was found to be not in conflict, useful for audit trails. RelationNotConflict RelationVerb = "not_conflict" )
Canonical Goncho relation vocabulary. New verbs must be added here so the pending-relation path remains deterministic and reviewable.
type WriteEvidence ¶
type WriteEvidence struct {
Code string
WriteOK bool
Candidates []RelationCandidate
Err error
}
WriteEvidence is the Goncho-native operator evidence for one Submit call. It is the only return shape from the queue; callers MUST inspect Code and WriteOK before treating Candidates as authoritative.
type WriteQueue ¶
type WriteQueue struct {
// contains filtered or unexported fields
}
WriteQueue serializes memory writes and records pending relation candidates without blocking the originating write. The queue uses a single mutex to guarantee mutex-serialized order; concurrent submitters are safe but the deterministic acceptance test exercises sequential submission so the recorded order is reproducible.
func NewWriteQueue ¶
func NewWriteQueue(store MemoryStore, detector CandidateDetector, relations RelationStore) *WriteQueue
NewWriteQueue constructs a queue from the three required seams. Pass nil for relations if relation candidate storage is intentionally disabled; in that case detected candidates are still attached to the returned evidence for the caller to inspect.
func (*WriteQueue) Cancel ¶
func (q *WriteQueue) Cancel(id string) bool
Cancel marks the given write ID as cancelled. Returns true if the cancellation was registered before the write started, false if the write has already begun, completed, or the ID was already consumed.
func (*WriteQueue) Submit ¶
func (q *WriteQueue) Submit(ctx context.Context, w MemoryWrite) WriteEvidence
Submit serializes the write through the queue. The originating memory write is authoritative: relation detection runs after a successful write and its failure is recorded as evidence without rolling the write back.
Source Files