Add D&D location identity contracts
This commit is contained in:
183
internal/modules/dnd/locations/identity/identity.go
Normal file
183
internal/modules/dnd/locations/identity/identity.go
Normal file
@@ -0,0 +1,183 @@
|
||||
// Package identity implements deterministic session-scoped location identity.
|
||||
package identity
|
||||
|
||||
import (
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"encoding/json"
|
||||
"sort"
|
||||
"strings"
|
||||
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/core/source"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
|
||||
"golang.org/x/text/cases"
|
||||
"golang.org/x/text/unicode/norm"
|
||||
)
|
||||
|
||||
const (
|
||||
// IdentityPolicy identifies the durable location ID derivation policy.
|
||||
IdentityPolicy = "dnd.locations.identity.v1"
|
||||
// Policy is an alias for IdentityPolicy.
|
||||
Policy = IdentityPolicy
|
||||
|
||||
idPrefix = "location:sha256:"
|
||||
)
|
||||
|
||||
// IssueCode identifies one deterministic registry identity problem.
|
||||
type IssueCode string
|
||||
|
||||
const (
|
||||
IssueEmptyCanonicalName IssueCode = "empty_canonical_name"
|
||||
IssueMissingEvidence IssueCode = "missing_evidence"
|
||||
IssueInvalidID IssueCode = "invalid_id"
|
||||
IssueIDMismatch IssueCode = "id_mismatch"
|
||||
IssueDuplicateID IssueCode = "duplicate_id"
|
||||
)
|
||||
|
||||
// Issue is an inspectable identity validation problem.
|
||||
type Issue struct {
|
||||
Code IssueCode
|
||||
RecordIndex int
|
||||
Value string
|
||||
}
|
||||
|
||||
func (i Issue) Error() string { return string(i.Code) }
|
||||
|
||||
// NormalizeDisplay returns the durable display form without changing spelling
|
||||
// or punctuation.
|
||||
func NormalizeDisplay(value string) string {
|
||||
return strings.Join(strings.Fields(value), " ")
|
||||
}
|
||||
|
||||
// ComparisonKey returns the stable key used for location identity comparisons.
|
||||
func ComparisonKey(value string) string {
|
||||
value = norm.NFKC.String(value)
|
||||
value = strings.Map(func(r rune) rune {
|
||||
switch r {
|
||||
case '\u2018', '\u2019', '\u02bc':
|
||||
return '\''
|
||||
default:
|
||||
return r
|
||||
}
|
||||
}, value)
|
||||
value = strings.Join(strings.Fields(value), " ")
|
||||
return cases.Fold().String(value)
|
||||
}
|
||||
|
||||
// DeriveID derives a location ID from name and the earliest canonical evidence
|
||||
// reference. It returns an empty string when either identity component is not
|
||||
// available, leaving validation to report the problem instead of manufacturing
|
||||
// an ID.
|
||||
func DeriveID(name string, refs []source.SourceRef) string {
|
||||
comparisonName := ComparisonKey(name)
|
||||
anchor, ok := earliestReference(refs)
|
||||
if comparisonName == "" || !ok {
|
||||
return ""
|
||||
}
|
||||
|
||||
input, err := json.Marshal([]any{
|
||||
IdentityPolicy,
|
||||
comparisonName,
|
||||
anchor.SourceID,
|
||||
anchor.StartUnitID,
|
||||
anchor.EndUnitID,
|
||||
})
|
||||
if err != nil {
|
||||
return ""
|
||||
}
|
||||
digest := sha256.Sum256(input)
|
||||
return idPrefix + hex.EncodeToString(digest[:])
|
||||
}
|
||||
|
||||
// IDFor is an alias for DeriveID.
|
||||
func IDFor(name string, refs []source.SourceRef) string { return DeriveID(name, refs) }
|
||||
|
||||
// IsValidID reports whether value has the exact durable location ID syntax.
|
||||
func IsValidID(value string) bool {
|
||||
if len(value) != len(idPrefix)+sha256.Size*2 || !strings.HasPrefix(value, idPrefix) {
|
||||
return false
|
||||
}
|
||||
for _, r := range value[len(idPrefix):] {
|
||||
if !((r >= '0' && r <= '9') || (r >= 'a' && r <= 'f')) {
|
||||
return false
|
||||
}
|
||||
}
|
||||
return true
|
||||
}
|
||||
|
||||
// ValidID is an alias for IsValidID.
|
||||
func ValidID(value string) bool { return IsValidID(value) }
|
||||
|
||||
// ValidateList validates the identity members of list.
|
||||
func ValidateList(list dnd.LocationList) []Issue { return ValidateRegistry(list.Locations) }
|
||||
|
||||
// ValidateRegistry validates location IDs without modifying records or their
|
||||
// source references. Equal comparison names are allowed because their evidence
|
||||
// anchors are part of the identity policy.
|
||||
func ValidateRegistry(locations []dnd.Location) []Issue {
|
||||
issues := make([]Issue, 0)
|
||||
idOwners := make(map[string][]int)
|
||||
|
||||
for recordIndex, location := range locations {
|
||||
if ComparisonKey(location.Name) == "" {
|
||||
issues = append(issues, Issue{Code: IssueEmptyCanonicalName, RecordIndex: recordIndex, Value: location.Name})
|
||||
}
|
||||
if _, ok := earliestReference(location.SourceRefs); !ok {
|
||||
issues = append(issues, Issue{Code: IssueMissingEvidence, RecordIndex: recordIndex})
|
||||
}
|
||||
|
||||
if !IsValidID(location.ID) {
|
||||
issues = append(issues, Issue{Code: IssueInvalidID, RecordIndex: recordIndex, Value: location.ID})
|
||||
} else if expected := DeriveID(location.Name, location.SourceRefs); location.ID != expected {
|
||||
issues = append(issues, Issue{Code: IssueIDMismatch, RecordIndex: recordIndex, Value: location.ID})
|
||||
}
|
||||
if location.ID != "" {
|
||||
idOwners[location.ID] = append(idOwners[location.ID], recordIndex)
|
||||
}
|
||||
}
|
||||
|
||||
for recordIndex, location := range locations {
|
||||
if location.ID != "" && len(idOwners[location.ID]) > 1 && idOwners[location.ID][0] != recordIndex {
|
||||
issues = append(issues, Issue{Code: IssueDuplicateID, RecordIndex: recordIndex, Value: location.ID})
|
||||
}
|
||||
}
|
||||
|
||||
return issues
|
||||
}
|
||||
|
||||
func earliestReference(refs []source.SourceRef) (source.SourceRef, bool) {
|
||||
canonical := canonicalReferences(refs)
|
||||
if len(canonical) == 0 {
|
||||
return source.SourceRef{}, false
|
||||
}
|
||||
return canonical[0], true
|
||||
}
|
||||
|
||||
func canonicalReferences(refs []source.SourceRef) []source.SourceRef {
|
||||
canonical := make([]source.SourceRef, 0, len(refs))
|
||||
for _, ref := range refs {
|
||||
if validIdentityReference(ref) {
|
||||
canonical = append(canonical, ref)
|
||||
}
|
||||
}
|
||||
sort.Slice(canonical, func(left, right int) bool {
|
||||
if canonical[left].SourceID != canonical[right].SourceID {
|
||||
return canonical[left].SourceID < canonical[right].SourceID
|
||||
}
|
||||
if canonical[left].StartUnitID != canonical[right].StartUnitID {
|
||||
return canonical[left].StartUnitID < canonical[right].StartUnitID
|
||||
}
|
||||
return canonical[left].EndUnitID < canonical[right].EndUnitID
|
||||
})
|
||||
unique := canonical[:0]
|
||||
for _, ref := range canonical {
|
||||
if len(unique) == 0 || unique[len(unique)-1] != ref {
|
||||
unique = append(unique, ref)
|
||||
}
|
||||
}
|
||||
return unique
|
||||
}
|
||||
|
||||
func validIdentityReference(ref source.SourceRef) bool {
|
||||
return strings.TrimSpace(ref.SourceID) == ref.SourceID && ref.SourceID != "" && ref.StartUnitID > 0 && ref.EndUnitID > 0
|
||||
}
|
||||
146
internal/modules/dnd/locations/identity/identity_test.go
Normal file
146
internal/modules/dnd/locations/identity/identity_test.go
Normal file
@@ -0,0 +1,146 @@
|
||||
package identity
|
||||
|
||||
import (
|
||||
"reflect"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/core/source"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
|
||||
)
|
||||
|
||||
func TestNormalizeDisplayOnlyChangesWhitespace(t *testing.T) {
|
||||
if got, want := NormalizeDisplay(" The\u2003Old\nTavern "), "The Old Tavern"; got != want {
|
||||
t.Fatalf("NormalizeDisplay() = %q, want %q", got, want)
|
||||
}
|
||||
}
|
||||
|
||||
func TestComparisonKeyNormalizesUnicodeWhitespaceAndApostrophes(t *testing.T) {
|
||||
for _, pair := range [][2]string{
|
||||
{" Caf\u00e9\u2003d\u2019Or ", "cafe\u0301 d'Or"},
|
||||
{"\uff34\uff48\uff45\u00a0\uff34\uff41\uff56\uff45\uff52\uff4e", "the tavern"},
|
||||
} {
|
||||
if left, right := ComparisonKey(pair[0]), ComparisonKey(pair[1]); left != right {
|
||||
t.Fatalf("ComparisonKey(%q) = %q, want value equal to %q", pair[0], left, pair[1])
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestDeriveIDUsesDocumentedCompactJSONInput(t *testing.T) {
|
||||
refs := []source.SourceRef{
|
||||
{SourceID: "session-alpha", StartUnitID: 9, EndUnitID: 9},
|
||||
{SourceID: "session-alpha", StartUnitID: 3, EndUnitID: 9},
|
||||
{SourceID: "session-alpha", StartUnitID: 3, EndUnitID: 9},
|
||||
}
|
||||
const want = "location:sha256:379bd996e754e143b47e6b613a95166e58c111c7451750df7066ca816bb1866c"
|
||||
|
||||
if got := DeriveID(" The\u2003Tavern ", refs); got != want {
|
||||
t.Fatalf("DeriveID() = %q, want %q", got, want)
|
||||
}
|
||||
if got := IDFor("The Tavern", refs); got != want {
|
||||
t.Fatalf("IDFor() = %q, want %q", got, want)
|
||||
}
|
||||
}
|
||||
|
||||
func TestDeriveIDUsesEarliestCanonicalEvidenceWithoutMutatingInput(t *testing.T) {
|
||||
refs := []source.SourceRef{
|
||||
{SourceID: "zeta", StartUnitID: 1, EndUnitID: 1},
|
||||
{SourceID: "alpha", StartUnitID: 8, EndUnitID: 8},
|
||||
{SourceID: "alpha", StartUnitID: 2, EndUnitID: 3},
|
||||
}
|
||||
wantRefs := append([]source.SourceRef(nil), refs...)
|
||||
|
||||
first := DeriveID("The Tavern", refs)
|
||||
second := DeriveID("The Tavern", []source.SourceRef{refs[2], refs[0], refs[1]})
|
||||
if first != second {
|
||||
t.Fatalf("DeriveID() changed when evidence order changed: %q != %q", first, second)
|
||||
}
|
||||
if !reflect.DeepEqual(refs, wantRefs) {
|
||||
t.Fatalf("DeriveID() mutated refs: got %#v, want %#v", refs, wantRefs)
|
||||
}
|
||||
}
|
||||
|
||||
func TestDeriveIDDistinguishesSameNameAtDifferentEvidenceAnchors(t *testing.T) {
|
||||
first := DeriveID("The Tavern", []source.SourceRef{{SourceID: "session", StartUnitID: 3, EndUnitID: 3}})
|
||||
second := DeriveID("the\u00a0tavern", []source.SourceRef{{SourceID: "session", StartUnitID: 18, EndUnitID: 18}})
|
||||
if first == "" || second == "" || first == second {
|
||||
t.Fatalf("same-name locations have IDs %q and %q, want distinct nonempty IDs", first, second)
|
||||
}
|
||||
}
|
||||
|
||||
func TestDeriveIDRejectsMissingIdentityComponents(t *testing.T) {
|
||||
for _, tt := range []struct {
|
||||
name string
|
||||
nameValue string
|
||||
refs []source.SourceRef
|
||||
}{
|
||||
{name: "blank name", nameValue: " \u2003 ", refs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}}},
|
||||
{name: "missing refs", nameValue: "The Tavern"},
|
||||
{name: "malformed ref", nameValue: "The Tavern", refs: []source.SourceRef{{SourceID: " ", StartUnitID: 1, EndUnitID: 1}}},
|
||||
} {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
if got := DeriveID(tt.nameValue, tt.refs); got != "" {
|
||||
t.Fatalf("DeriveID() = %q, want empty ID", got)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestIsValidID(t *testing.T) {
|
||||
valid := DeriveID("The Tavern", []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}})
|
||||
if !IsValidID(valid) || !ValidID(valid) {
|
||||
t.Fatalf("derived ID %q is not valid", valid)
|
||||
}
|
||||
for _, value := range []string{"", "location:sha256:", "location:sha256:" + strings.Repeat("A", 64), "location:sha256:" + strings.Repeat("0", 63)} {
|
||||
if IsValidID(value) {
|
||||
t.Fatalf("IsValidID(%q) = true, want false", value)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestValidateRegistryAllowsSameComparisonNameWithDifferentAnchors(t *testing.T) {
|
||||
firstRefs := []source.SourceRef{{SourceID: "session", StartUnitID: 2, EndUnitID: 2}}
|
||||
secondRefs := []source.SourceRef{{SourceID: "session", StartUnitID: 8, EndUnitID: 8}}
|
||||
locations := []dnd.Location{
|
||||
{ID: DeriveID("The Tavern", firstRefs), Name: "The Tavern", SourceRefs: firstRefs},
|
||||
{ID: DeriveID("the\u00a0tavern", secondRefs), Name: "the\u00a0tavern", SourceRefs: secondRefs},
|
||||
}
|
||||
if issues := ValidateRegistry(locations); len(issues) != 0 {
|
||||
t.Fatalf("ValidateRegistry() = %#v, want no issues", issues)
|
||||
}
|
||||
}
|
||||
|
||||
func TestValidateRegistryReportsIdentityProblemsDeterministicallyWithoutMutation(t *testing.T) {
|
||||
refs := []source.SourceRef{{SourceID: "session", StartUnitID: 2, EndUnitID: 2}}
|
||||
validID := DeriveID("The Tavern", refs)
|
||||
locations := []dnd.Location{
|
||||
{ID: validID, Name: "The Tavern", SourceRefs: refs},
|
||||
{ID: validID, Name: "Elsewhere", SourceRefs: refs},
|
||||
{ID: "bad", Name: "", SourceRefs: nil},
|
||||
}
|
||||
wantLocations := cloneLocations(locations)
|
||||
|
||||
issues := ValidateList(dnd.LocationList{Locations: locations})
|
||||
want := []Issue{
|
||||
{Code: IssueIDMismatch, RecordIndex: 1, Value: validID},
|
||||
{Code: IssueEmptyCanonicalName, RecordIndex: 2, Value: ""},
|
||||
{Code: IssueMissingEvidence, RecordIndex: 2},
|
||||
{Code: IssueInvalidID, RecordIndex: 2, Value: "bad"},
|
||||
{Code: IssueDuplicateID, RecordIndex: 1, Value: validID},
|
||||
}
|
||||
if !reflect.DeepEqual(issues, want) {
|
||||
t.Fatalf("ValidateList() = %#v, want %#v", issues, want)
|
||||
}
|
||||
if !reflect.DeepEqual(locations, wantLocations) {
|
||||
t.Fatalf("ValidateList() mutated locations: got %#v, want %#v", locations, wantLocations)
|
||||
}
|
||||
}
|
||||
|
||||
func cloneLocations(input []dnd.Location) []dnd.Location {
|
||||
output := make([]dnd.Location, len(input))
|
||||
copy(output, input)
|
||||
for index := range output {
|
||||
output[index].SourceRefs = append([]source.SourceRef(nil), input[index].SourceRefs...)
|
||||
}
|
||||
return output
|
||||
}
|
||||
@@ -20,6 +20,10 @@ const ItemEventListKind contracts.ArtifactKind = "dnd/item-event-list"
|
||||
|
||||
const EnemyEventListKind contracts.ArtifactKind = "dnd/enemy-event-list"
|
||||
|
||||
const LocationListKind contracts.ArtifactKind = "dnd/location-list"
|
||||
|
||||
const LocationOccurrenceListKind contracts.ArtifactKind = "dnd/location-occurrence-list"
|
||||
|
||||
type SpellList struct {
|
||||
SpellCasts []SpellCast `json:"spell_casts"`
|
||||
}
|
||||
@@ -144,3 +148,33 @@ type EnemyEvent struct {
|
||||
Kind EnemyEventKind `json:"kind"`
|
||||
SourceRefs []source.SourceRef `json:"source_refs"`
|
||||
}
|
||||
|
||||
type LocationList struct {
|
||||
Locations []Location `json:"locations"`
|
||||
}
|
||||
|
||||
type Location struct {
|
||||
ID string `json:"id"`
|
||||
Name string `json:"name"`
|
||||
SourceRefs []source.SourceRef `json:"source_refs"`
|
||||
}
|
||||
|
||||
type LocationOccurrenceKind string
|
||||
|
||||
const (
|
||||
LocationOccurrenceKindVisited LocationOccurrenceKind = "visited"
|
||||
LocationOccurrenceKindPlanned LocationOccurrenceKind = "planned"
|
||||
LocationOccurrenceKindRecalled LocationOccurrenceKind = "recalled"
|
||||
LocationOccurrenceKindMentioned LocationOccurrenceKind = "mentioned"
|
||||
)
|
||||
|
||||
type LocationOccurrenceList struct {
|
||||
Occurrences []LocationOccurrence `json:"occurrences"`
|
||||
}
|
||||
|
||||
type LocationOccurrence struct {
|
||||
LocationID string `json:"location_id"`
|
||||
Name string `json:"name"`
|
||||
Kind LocationOccurrenceKind `json:"kind"`
|
||||
SourceRefs []source.SourceRef `json:"source_refs"`
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user