graphops: the wildcard's max bounds the whole owned set (OW1 = A, bdp#22)

The operator's ruling of 2026-09-08 (gastownhall/bdp#22, OW1 = A) reads
"max bounds the whole owned set" literally: the wildcard owned-Link
declaration's max bounds a Bead's WHOLE owned set - every owned Link
across every owned Link Type, the explicitly declared Types' Links
included. P0 had taken the narrower reading (DECISION 4: the wildcard's
max bounds only the Links owned by virtue of the wildcard); this flips it.

- Descriptor validation: under a wildcard, an explicit declaration whose
  max exceeds the wildcard's is refused by NewTypeDescriptor - and by
  ParseTypeDescriptor through it - with ErrValidation naming the Type
  and both numbers; equal and lower are admitted; a descriptor without a
  wildcard is unaffected. A validation rule beyond the schema bundle,
  which cannot relate two entries' numbers.
- CheckBeadRecord now checks the bounds: under a wildcard the owned Links
  of all groups together number at most the wildcard's max (the bound
  the batched read enforces with LIMIT wildcard.max + 1), and each
  explicit group at most its own max. DECISION recorded: both bounds are
  acceptance facts - one law whether or not a wildcard is present, and
  the conservative choice.
- Doc comments on NewWildcardOwnedLinkDecl (DECISION 4 rewritten with
  the ruling reference), Max, TypeDescriptorSpec.OwnsOutgoing,
  NewTypeDescriptor, ParseTypeDescriptor, Owns, Fingerprint,
  OwnedLinkGroup and BeadRecord state the whole-set reading. The
  canonical form is untouched, so every descriptor the rule admits
  fingerprints exactly as before.

Tests: explicit max above the wildcard's refused at the constructor and
the parser in every authored order; equal and lower admitted and
round-tripping; no-wildcard descriptors unaffected; records at and over
the whole-set max, at and over an explicit max, wildcard-only Links at
and over the bound, a lone wildcard at and over its bound, with the
refusals' wording pinned. Two fixtures the ruling made invalid (explicit
8 over wildcard 5; explicit 2^53+2 over wildcard 2^53) are re-cut to
valid combinations with the golden fingerprint recomputed; the
wildcard-only golden is unchanged. Coverage stays at 100%.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Donna Box 2026-09-08 11:46:43 -03:00
commit ec692e146a
2 changed files with 257 additions and 64 deletions

View file

@ -718,11 +718,12 @@ func NewOwnedLinkDecl(linkTypeURL, label string, max int) (OwnedLinkDecl, error)
// NewWildcardOwnedLinkDecl builds the wildcard declaration: every outgoing
// Link Type the descriptor does not name explicitly is owned, and max bounds
// the WHOLE wildcard-owned set — every such Link of one Bead together, not
// each Type separately, since the Types are open-ended and a per-Type bound
// would bound nothing inline. Max is required and positive exactly as on an
// explicit declaration; the installer's "no owning declaration without a
// bound" law covers both.
// the Bead's WHOLE OWNED SET — every owned Link of one Bead across every
// owned Link Type together, the explicitly declared Types' Links included —
// not each Type separately, since the Types are open-ended and a per-Type
// bound would bound nothing inline. Max is required and positive exactly as
// on an explicit declaration; the installer's "no owning declaration without
// a bound" law covers both.
//
// DECISION: no label. The ruling spells the entry as "*": { max }, and a
// label is display documentation for one named Type; the wildcard names
@ -730,13 +731,20 @@ func NewOwnedLinkDecl(linkTypeURL, label string, max int) (OwnedLinkDecl, error)
// later is a widening while refusing one later would break installed
// descriptors.
//
// DECISION: "max bounding the whole owned set" is read as the set of Links
// owned BY VIRTUE OF the wildcard. An explicitly declared Type is bounded by
// its own max ("explicit entries take precedence for the types they name"),
// so a Bead's inline owned plane is bounded by the explicit maxes plus the
// wildcard max. The other reading — the wildcard max caps everything owned,
// explicit Types included — is the one the bdp spec PR for item 5 would have
// to state; this package takes the per-declaration reading until it does.
// DECISION (OW1 = A, operator ruling 2026-09-08, gastownhall/bdp#22): "max
// bounds the whole owned set" is the LITERAL whole set. P0's first reading
// took the narrower set — the Links owned by virtue of the wildcard alone,
// each explicit Type bounded only by its own max — and was flipped: the
// wildcard's max is the ONE number that bounds a Bead's inline owned plane,
// and an explicit declaration's max is a tighter per-Type bound inside it
// ("explicit entries take precedence for the types they name" says which
// declaration owns a Type, not that the Type escapes the bound). It follows
// that an explicit max above the wildcard's promises what the wildcard
// forbids, so such a descriptor is invalid and is not installed:
// NewTypeDescriptor, and ParseTypeDescriptor through it, refuse it naming
// the Type and both numbers — a descriptor-validation rule beyond the
// schema bundle, which cannot relate two entries' numbers. Equal is
// admitted: the explicit Type may then fill the whole set by itself.
func NewWildcardOwnedLinkDecl(max int) (OwnedLinkDecl, error) {
if err := validateOwnedMax(WildcardOwnedLinkKey, max); err != nil {
return OwnedLinkDecl{}, err
@ -778,8 +786,11 @@ func (d OwnedLinkDecl) TypeURL() string { return d.typeURL }
func (d OwnedLinkDecl) Label() (string, bool) { return d.label, d.label != "" }
// Max is the largest owned set the declaration permits: the Links of the one
// named Type for an explicit declaration, every wildcard-owned Link together
// for the wildcard.
// named Type for an explicit declaration; for the wildcard, the Bead's whole
// owned set — every owned Link across every owned Type, the explicitly
// declared Types' Links included (OW1 = A). In a descriptor that exists no
// explicit Max exceeds the wildcard's, so the wildcard's Max alone sizes the
// inline owned plane of a Bead whose Type carries one.
func (d OwnedLinkDecl) Max() int { return d.max }
// TypeDescriptor is one installed Type contract: the closed BDP v0 descriptor
@ -824,8 +835,8 @@ type TypeDescriptorSpec struct {
Source, Target *EndpointConstraint
// OwnsOutgoing declares the owned Link Types of a Bead Type: explicit
// declarations and at most one wildcard (NewWildcardOwnedLinkDecl), in
// any order; empty means the member is absent. Must be empty for a Link
// Type.
// any order, no explicit max above the wildcard's (OW1 = A); empty means
// the member is absent. Must be empty for a Link Type.
OwnsOutgoing []OwnedLinkDecl
}
@ -833,9 +844,11 @@ type TypeDescriptorSpec struct {
// pinned spec and schema bundle: a canonical Type ID, a nonempty name, a
// category, unique canonical parent IDs that do not include the Type itself,
// endpoint constraints exactly when the Type describes Links, ownsOutgoing
// only when it describes Beads, one declaration per owned Link Type and at
// only when it describes Beads, one declaration per owned Link Type, at
// most one wildcard (bdp#1 item 5, ahead of the pinned bundle — see
// WildcardOwnedLinkKey).
// WildcardOwnedLinkKey), and — under a wildcard — no explicit declaration
// whose max exceeds the wildcard's, since the wildcard's max bounds the
// whole owned set (OW1 = A; see NewWildcardOwnedLinkDecl).
func NewTypeDescriptor(spec TypeDescriptorSpec) (TypeDescriptor, error) {
if err := ValidateTypeURL(spec.ID); err != nil {
return TypeDescriptor{}, fmt.Errorf("descriptor id: %w", err)
@ -900,6 +913,17 @@ func NewTypeDescriptor(spec TypeDescriptorSpec) (TypeDescriptor, error) {
return TypeDescriptor{}, fmt.Errorf("%w: descriptor %s: ownsOutgoing declares %s twice", ErrValidation, spec.ID, decl.typeURL)
}
}
// The whole-set rule (OW1 = A): the wildcard's max bounds every owned
// Link of a Bead, explicit Types' Links included, so an explicit max
// above it is refused. The wildcard sorts first ("*" precedes every
// URL), so it is owns[0] when present.
if len(owns) > 0 && owns[0].Wildcard() {
for _, decl := range owns[1:] {
if decl.max > owns[0].max {
return TypeDescriptor{}, fmt.Errorf("%w: descriptor %s: ownsOutgoing %s: max %d exceeds the wildcard's max %d, which bounds the whole owned set (OW1 = A)", ErrValidation, spec.ID, decl.typeURL, decl.max, owns[0].max)
}
}
}
d.ownsOutgoing = owns
}
d.canonical = descriptorCanonicalJSON(d)
@ -1012,7 +1036,10 @@ var descriptorMembers = map[string]memberShape{
// ownsOutgoing, propertiesSchema when present is an absolute URL, an
// ownsOutgoing key is a canonical Link Type URL or the wildcard "*"
// (WildcardOwnedLinkKey — read ahead of the pinned bundle, which admits
// only URLs there), and every law NewTypeDescriptor enforces holds.
// only URLs there), and every law NewTypeDescriptor enforces holds — the
// whole-set max rule among them: an explicit entry's max above the
// wildcard's is refused (OW1 = A), a rule the schema bundle cannot state
// because it relates two entries' numbers.
//
// DECISION: description "" is read as absent. The bundle permits the empty
// string, the canonical form has no way to carry it apart from absence, and
@ -1258,7 +1285,12 @@ func (t TypeDescriptor) OwnsOutgoing() []OwnedLinkDecl {
// Type when there is one, else the wildcard declaration when there is one,
// else none — "explicit entries take precedence for the types they name".
// It is the owned-Link trigger law in predicate form: a mutation of a Link
// whose Type the source's Bead Type owns versions the source.
// whose Type the source's Bead Type owns versions the source. Precedence
// says WHICH declaration owns a Type, not what bounds it: the returned
// explicit declaration's Max bounds that Type's Links, and when the
// descriptor also carries a wildcard, the wildcard's Max bounds the Bead's
// whole owned set, those Links included (OW1 = A) — a caller sizing the
// owned plane reads the wildcard's Max from OwnsOutgoing, not a sum.
//
// DECISION: Owns(WildcardOwnedLinkKey) is false. "*" is a key, not a Type;
// no Link carries it, so nothing is owned under it BY NAME, and answering
@ -1295,6 +1327,11 @@ func (t TypeDescriptor) CanonicalJSON() []byte { return append([]byte(nil), t.ca
// conformsTo sets (the descriptor's and each endpoint's) are sorted by code
// unit in the canonical form, so the authored order is NOT significant to
// it: two descriptors that differ only in parent order are one contract.
// Validation rules beyond the schema do not reach it either: the whole-set
// max rule (OW1 = A) decides which descriptors EXIST, not how one is spelled,
// so a descriptor it admits fingerprints exactly as it did before the ruling
// — the installer's idempotence key is stable across it — and a descriptor
// it refuses is never built and has no fingerprint here at all.
func (t TypeDescriptor) Fingerprint() string { return t.fingerprint }
// IsZero reports a descriptor no constructor produced.
@ -1779,7 +1816,10 @@ func (m LedgerManifest) Covers(events []LedgerEvent) error {
// explicitly declared Type with no Links is an EMPTY group, never an absent
// one; a Type owned only through the wildcard has a group exactly when the
// Bead has a Link of it (bdp#1 item 5: "one entry per owned type actually
// present, plus an empty entry for each explicitly declared type").
// present, plus an empty entry for each explicitly declared type"). An
// explicit group holds at most its declaration's Max Links; under a
// wildcard declaration the Links of ALL of a Bead's groups together —
// explicit groups included — number at most the wildcard's Max (OW1 = A).
type OwnedLinkGroup struct {
TypeURL string
Links []Link
@ -1791,7 +1831,12 @@ type OwnedLinkGroup struct {
// one group per wildcard-owned Link Type the Bead actually has Links of, all
// in code-unit order of TypeURL; nil when nothing is owned or present. Every
// projection — singleton, collection item, selection item — returns records,
// because the Bead's revision covers its owned Links.
// because the Bead's revision covers its owned Links. The expansion is
// bounded, which is what makes it servable inline: each explicit group by
// its declaration's Max, and — under a wildcard — the whole expansion, every
// group together, by the wildcard's Max (OW1 = A), the one bound the store's
// batched owned-Links read enforces with LIMIT max + 1 and the one
// CheckBeadRecord refuses a record for exceeding.
type BeadRecord struct {
Bead Bead
OwnedLinks []OwnedLinkGroup
@ -1802,20 +1847,41 @@ type BeadRecord struct {
// order of Link Type URL with no repeats and none keyed by the wildcard; there
// is exactly one group, possibly empty, per explicit declaration; a group for
// any other Type exists only under a wildcard declaration and only when it
// holds a Link; and in every group each Link's Type equals the group key, its
// holds a Link; in every group each Link's Type equals the group key, its
// source is the Bead, and the Links ascend in code-unit order of path with no
// repeats. It is the acceptance law the plan states and the storage
// transactions run. The bounds (Max) are not checked here: they are the
// serving transaction's LIMIT law, not a fact about an assembled record.
// repeats; and the record is within its bounds — an explicit group holds at
// most its declaration's Max Links, and under a wildcard declaration the
// Links of all groups together number at most the wildcard's Max, the whole
// owned set (OW1 = A). It is the acceptance law the plan states and the
// storage transactions run.
//
// DECISION: the bounds ARE checked here, both of them. Before OW1 = A this
// law left Max to the serving transaction's LIMIT max + 1 — "not a fact
// about an assembled record" — and the ruling made the wildcard's Max
// exactly such a fact: the whole-set bound is what a Bead's inline owned
// plane may hold, so a record over it is one the descriptor says cannot
// exist, and serving it would serve a contract violation. The store's
// batched owned-Links read for a wildcard owner selects every owned Link of
// the Bead, all Types together, under LIMIT wildcard.max + 1 (B4) and
// refuses to assemble when the extra row comes back; this law is the pure
// restatement of that same bound over what was assembled, so the two never
// disagree. The explicit per-Type bound is checked too, for consistency —
// one acceptance law whether or not a wildcard is present, rather than a
// Max that is a fact under a wildcard and a mere LIMIT hint without one —
// and because it is the conservative choice: dropping a check later widens
// what is accepted, adding one later would refuse records that once passed.
// The declarations are a descriptor's own (no explicit Max exceeds the
// wildcard's there), so the two checks are independent and either may be
// the one that fires.
func CheckBeadRecord(record BeadRecord, owns []OwnedLinkDecl) error {
fail := func(format string, args ...any) error {
return fmt.Errorf("%w: bead %s: %s", ErrValidation, record.Bead.Path(), fmt.Sprintf(format, args...))
}
var explicit []OwnedLinkDecl
wildcard := false
var wildcard OwnedLinkDecl // the zero declaration when there is none
for _, decl := range owns {
if decl.Wildcard() {
wildcard = true
wildcard = decl
continue
}
explicit = append(explicit, decl)
@ -1823,7 +1889,8 @@ func CheckBeadRecord(record BeadRecord, owns []OwnedLinkDecl) error {
sort.SliceStable(explicit, func(i, j int) bool {
return CompareCodeUnits(explicit[i].typeURL, explicit[j].typeURL) < 0
})
next := 0 // the first explicit declaration not yet matched by a group
next := 0 // the first explicit declaration not yet matched by a group
total := 0 // owned Links across all groups: the whole owned set
for i, group := range record.OwnedLinks {
if group.TypeURL == WildcardOwnedLinkKey {
return fail("ownedLinks group %d is keyed by the wildcard; groups are keyed by Link Type URL", i)
@ -1838,12 +1905,18 @@ func CheckBeadRecord(record BeadRecord, owns []OwnedLinkDecl) error {
}
switch {
case next < len(explicit) && explicit[next].typeURL == group.TypeURL:
next++ // the explicit declaration's group, empty or not
case !wildcard:
// The explicit declaration's group, empty or not, within its
// own per-Type bound.
if len(group.Links) > explicit[next].max {
return fail("ownedLinks group %s holds %d Links, over its declared max %d", group.TypeURL, len(group.Links), explicit[next].max)
}
next++
case !wildcard.Wildcard():
return fail("ownedLinks group %s is not an owned Type", group.TypeURL)
case len(group.Links) == 0:
return fail("empty ownedLinks group %s: a wildcard-owned Type has a group only when a Link is present", group.TypeURL)
}
total += len(group.Links)
for j, link := range group.Links {
if link.TypeURL() != group.TypeURL {
return fail("owned Link %s has type %s under group %s", link.Path(), link.TypeURL(), group.TypeURL)
@ -1859,6 +1932,9 @@ func CheckBeadRecord(record BeadRecord, owns []OwnedLinkDecl) error {
if next < len(explicit) {
return fail("no ownedLinks group for explicitly owned %s", explicit[next].typeURL)
}
if wildcard.Wildcard() && total > wildcard.max {
return fail("%d owned Links across all groups, over the wildcard's whole-set max %d", total, wildcard.max)
}
return nil
}

View file

@ -988,7 +988,17 @@ func TestCheckBeadRecord(t *testing.T) {
if err := graphops.CheckBeadRecord(graphops.BeadRecord{Bead: bead}, nil); err != nil {
t.Fatalf("a Type owning nothing has no groups: %v", err)
}
// Each explicit group is within its declaration's max: at the max is
// admitted, one over is refused (OW1 = A made Max an acceptance fact).
atMax := graphops.BeadRecord{Bead: bead, OwnedLinks: []graphops.OwnedLinkGroup{
{TypeURL: blocks, Links: []graphops.Link{mk("links/b/1", blocks, self), mk("links/b/2", blocks, self)}},
good.OwnedLinks[1],
}}
if err := graphops.CheckBeadRecord(atMax, owns); err != nil {
t.Fatalf("explicit groups at their max refused: %v", err)
}
for name, rec := range map[string]graphops.BeadRecord{
"over max": {Bead: bead, OwnedLinks: []graphops.OwnedLinkGroup{{TypeURL: blocks, Links: []graphops.Link{mk("links/b/1", blocks, self), mk("links/b/2", blocks, self), mk("links/b/3", blocks, self)}}, good.OwnedLinks[1]}},
"missing group": {Bead: bead, OwnedLinks: good.OwnedLinks[1:]},
"wrong order": {Bead: bead, OwnedLinks: []graphops.OwnedLinkGroup{good.OwnedLinks[1], good.OwnedLinks[0]}},
"wrong type": {Bead: bead, OwnedLinks: []graphops.OwnedLinkGroup{{TypeURL: blocks}, {TypeURL: cites, Links: []graphops.Link{mk("links/c/1", blocks, self)}}}},
@ -1074,8 +1084,10 @@ func TestErrorsAreOneVocabulary(t *testing.T) {
// The wildcard owned-Link declaration (bdp#1 item 5, ruled 2026-09-08):
// "*": { max } owns every outgoing Link Type not named explicitly, max bounds
// the whole wildcard-owned set, and explicit entries take precedence for the
// Types they name. THE DOMAIN RUNS AHEAD OF THE PINNED WIRE HERE — the bundle
// the Bead's WHOLE owned set — explicit Types' Links included, so no explicit
// max may exceed it (OW1 = A; TestWildcardMaxBoundsTheWholeOwnedSet) — and
// explicit entries take precedence for the Types they name. THE DOMAIN RUNS
// AHEAD OF THE PINNED WIRE HERE — the bundle
// vendored in internal/httpapi/bdpwire keys ownsOutgoing by absoluteHttpUrl
// until the pin moves (graphops.WildcardOwnedLinkKey; the tripwire is
// bdpwire's TestWildcardOwnedLinkKeyIsNotInThePinnedBundle) — so the
@ -1083,23 +1095,25 @@ func TestErrorsAreOneVocabulary(t *testing.T) {
// "*" sorted first: 0x2A precedes every URL's "h".
func TestWildcardOwnedLinkDeclaration(t *testing.T) {
const memory, cites, relates = "https://work.example/types/memory", "https://work.example/types/cites", "https://work.example/types/relates"
any5, err := graphops.NewWildcardOwnedLinkDecl(5)
any8, err := graphops.NewWildcardOwnedLinkDecl(8)
if err != nil {
t.Fatal(err)
}
if _, hasLabel := any5.Label(); !any5.Wildcard() || any5.TypeURL() != graphops.WildcardOwnedLinkKey || any5.Max() != 5 || hasLabel {
t.Fatalf("wildcard declaration: %+v", any5)
if _, hasLabel := any8.Label(); !any8.Wildcard() || any8.TypeURL() != graphops.WildcardOwnedLinkKey || any8.Max() != 8 || hasLabel {
t.Fatalf("wildcard declaration: %+v", any8)
}
if (graphops.OwnedLinkDecl{}).Wildcard() {
t.Fatal("the zero declaration is not the wildcard")
}
cites8, _ := graphops.NewOwnedLinkDecl(cites, "cites", 8)
built, err := graphops.NewTypeDescriptor(graphops.TypeDescriptorSpec{ID: memory, Name: "Memory", Describes: graphops.KindBead, OwnsOutgoing: []graphops.OwnedLinkDecl{cites8, any5}})
// The explicit max sits under the wildcard's: the wildcard's 8 bounds the
// whole owned set, cites' 5 the cites Links inside it (OW1 = A).
cites5, _ := graphops.NewOwnedLinkDecl(cites, "cites", 5)
built, err := graphops.NewTypeDescriptor(graphops.TypeDescriptorSpec{ID: memory, Name: "Memory", Describes: graphops.KindBead, OwnsOutgoing: []graphops.OwnedLinkDecl{cites5, any8}})
if err != nil {
t.Fatal(err)
}
const wantCanonical = `{"conformsTo":[],"describes":"bead","id":"https://work.example/types/memory","name":"Memory","ownsOutgoing":{"*":{"max":5},"https://work.example/types/cites":{"label":"cites","max":8}}}`
const wantFingerprint = "c0ead94e2681b74dac89b402465ca0fb2654cdb092fb400f00254b63c19d92f9"
const wantCanonical = `{"conformsTo":[],"describes":"bead","id":"https://work.example/types/memory","name":"Memory","ownsOutgoing":{"*":{"max":8},"https://work.example/types/cites":{"label":"cites","max":5}}}`
const wantFingerprint = "9aba92834b71bd4153890415c243b3961058318602c478966ac5cde403862e26"
if got := string(built.CanonicalJSON()); got != wantCanonical {
t.Fatalf("canonical wildcard descriptor\n got %s\nwant %s", got, wantCanonical)
}
@ -1111,17 +1125,17 @@ func TestWildcardOwnedLinkDeclaration(t *testing.T) {
t.Fatalf("the wildcard sorts first, then Type URLs: %+v", owns)
}
// Explicit precedence, wildcard fallback, and "*" is never a Type.
if got, ok := built.Owns(cites); !ok || got.Wildcard() || got.Max() != 8 {
if got, ok := built.Owns(cites); !ok || got.Wildcard() || got.Max() != 5 {
t.Fatalf("Owns(cites) must be the explicit declaration: %+v %v", got, ok)
}
if got, ok := built.Owns(relates); !ok || !got.Wildcard() || got.Max() != 5 {
if got, ok := built.Owns(relates); !ok || !got.Wildcard() || got.Max() != 8 {
t.Fatalf("Owns(relates) must fall back to the wildcard: %+v %v", got, ok)
}
if _, ok := built.Owns(graphops.WildcardOwnedLinkKey); ok {
t.Fatal(`Owns("*") must be false: the wildcard key is not a Type`)
}
// The wire form, in either key order, parses to the same fingerprint.
parsed, err := graphops.ParseTypeDescriptor([]byte(`{"id":"https://work.example/types/memory","name":"Memory","describes":"bead","conformsTo":[],"ownsOutgoing":{"https://work.example/types/cites":{"max":8,"label":"cites"},"*":{"max":5}}}`))
parsed, err := graphops.ParseTypeDescriptor([]byte(`{"id":"https://work.example/types/memory","name":"Memory","describes":"bead","conformsTo":[],"ownsOutgoing":{"https://work.example/types/cites":{"max":5,"label":"cites"},"*":{"max":8}}}`))
if err != nil {
t.Fatal(err)
}
@ -1141,7 +1155,7 @@ func TestWildcardOwnedLinkDeclaration(t *testing.T) {
t.Fatalf("a lone wildcard owns every Type: %+v %v", got, ok)
}
// Without a wildcard an unnamed Type is still unowned: the pre-ruling law.
plain, _ := graphops.NewTypeDescriptor(graphops.TypeDescriptorSpec{ID: memory, Name: "Memory", Describes: graphops.KindBead, OwnsOutgoing: []graphops.OwnedLinkDecl{cites8}})
plain, _ := graphops.NewTypeDescriptor(graphops.TypeDescriptorSpec{ID: memory, Name: "Memory", Describes: graphops.KindBead, OwnsOutgoing: []graphops.OwnedLinkDecl{cites5}})
if _, ok := plain.Owns(relates); ok {
t.Fatal("no wildcard: an unnamed Type is not owned")
}
@ -1175,7 +1189,7 @@ func TestWildcardOwnedLinkDeclaration(t *testing.T) {
if _, err := graphops.NewOwnedLinkDecl(graphops.WildcardOwnedLinkKey, "", 1); !errors.Is(err, graphops.ErrValidation) || !strings.Contains(err.Error(), "wildcard") {
t.Errorf(`NewOwnedLinkDecl("*") must refuse and name the wildcard: %v`, err)
}
if _, err := graphops.NewTypeDescriptor(graphops.TypeDescriptorSpec{ID: memory, Name: "Memory", Describes: graphops.KindBead, OwnsOutgoing: []graphops.OwnedLinkDecl{any5, cites8, any5}}); !errors.Is(err, graphops.ErrValidation) {
if _, err := graphops.NewTypeDescriptor(graphops.TypeDescriptorSpec{ID: memory, Name: "Memory", Describes: graphops.KindBead, OwnsOutgoing: []graphops.OwnedLinkDecl{any8, cites5, any8}}); !errors.Is(err, graphops.ErrValidation) || !strings.Contains(err.Error(), "twice") {
t.Errorf("two wildcards: %v", err)
}
if _, err := graphops.NewEndpointConstraint([]string{graphops.WildcardOwnedLinkKey}, ""); !errors.Is(err, graphops.ErrValidation) {
@ -1194,9 +1208,80 @@ func TestWildcardOwnedLinkDeclaration(t *testing.T) {
}
}
// The wildcard's max bounds the Bead's WHOLE owned set (OW1 = A, operator
// ruling 2026-09-08, gastownhall/bdp#22): every owned Link across every owned
// Type, the explicitly declared Types' Links included. So an explicit
// declaration's max may not exceed the wildcard's — refused at both doors,
// naming the Type and both numbers — while equal and lower are admitted, and
// a descriptor without a wildcard is bounded per Type only, as before.
func TestWildcardMaxBoundsTheWholeOwnedSet(t *testing.T) {
const x, blocks, cites, relates = "https://work.example/types/x", "https://work.example/types/blocks", "https://work.example/types/cites", "https://work.example/types/relates"
spec := func(owns ...graphops.OwnedLinkDecl) graphops.TypeDescriptorSpec {
return graphops.TypeDescriptorSpec{ID: x, Name: "X", Describes: graphops.KindBead, OwnsOutgoing: owns}
}
any5, _ := graphops.NewWildcardOwnedLinkDecl(5)
blocks2, _ := graphops.NewOwnedLinkDecl(blocks, "", 2)
cites5, _ := graphops.NewOwnedLinkDecl(cites, "", 5)
cites8, _ := graphops.NewOwnedLinkDecl(cites, "cites", 8)
const wantRefusal = "ownsOutgoing https://work.example/types/cites: max 8 exceeds the wildcard's max 5"
// Refused at the constructor, whatever the authored order and however
// many compliant entries precede the offending one.
for name, owns := range map[string][]graphops.OwnedLinkDecl{
"explicit above the wildcard": {cites8, any5},
"wildcard first": {any5, cites8},
"a compliant entry before the offending one": {any5, blocks2, cites8},
} {
_, err := graphops.NewTypeDescriptor(spec(owns...))
if !errors.Is(err, graphops.ErrValidation) || !strings.Contains(err.Error(), wantRefusal) {
t.Errorf("%s: want ErrValidation naming the Type and both numbers, got %v", name, err)
}
}
// Refused at the JSON door with the same words, in either key order.
for name, in := range map[string]string{
"explicit above the wildcard": `{"id":"https://work.example/types/x","name":"X","describes":"bead","conformsTo":[],"ownsOutgoing":{"https://work.example/types/cites":{"label":"cites","max":8},"*":{"max":5}}}`,
"wildcard first": `{"id":"https://work.example/types/x","name":"X","describes":"bead","conformsTo":[],"ownsOutgoing":{"*":{"max":5},"https://work.example/types/blocks":{"max":2},"https://work.example/types/cites":{"max":8}}}`,
} {
_, err := graphops.ParseTypeDescriptor([]byte(in))
if !errors.Is(err, graphops.ErrValidation) || !strings.Contains(err.Error(), wantRefusal) {
t.Errorf("descriptor %s: want ErrValidation naming the Type and both numbers, got %v", name, err)
}
}
// Equal is admitted — the explicit Type may then fill the whole set by
// itself — and so is lower; the wildcard's max is the whole-set bound
// either way, and the canonical form re-admits, fingerprint intact.
for name, owns := range map[string][]graphops.OwnedLinkDecl{
"equal": {cites5, any5},
"lower": {blocks2, any5},
"both": {cites5, blocks2, any5},
} {
built, err := graphops.NewTypeDescriptor(spec(owns...))
if err != nil {
t.Errorf("%s: refused: %v", name, err)
continue
}
if got, ok := built.Owns(relates); !ok || !got.Wildcard() || got.Max() != 5 {
t.Errorf("%s: the wildcard's max is the whole-set bound: %+v %v", name, got, ok)
}
parsed, err := graphops.ParseTypeDescriptor(built.CanonicalJSON())
if err != nil || parsed.Fingerprint() != built.Fingerprint() {
t.Errorf("%s: the canonical form must re-admit with the same fingerprint: %v", name, err)
}
}
// Without a wildcard there is no whole-set bound to exceed: explicit
// maxes relate to nothing but their own Type.
if _, err := graphops.NewTypeDescriptor(spec(cites8, blocks2)); err != nil {
t.Errorf("no wildcard: explicit maxes are unrelated: %v", err)
}
if _, err := graphops.ParseTypeDescriptor([]byte(`{"id":"https://work.example/types/x","name":"X","describes":"bead","conformsTo":[],"ownsOutgoing":{"https://work.example/types/blocks":{"max":2},"https://work.example/types/cites":{"max":8}}}`)); err != nil {
t.Errorf("no wildcard, parsed: explicit maxes are unrelated: %v", err)
}
}
// CheckBeadRecord under a wildcard declaration (bdp#1 item 5): a group per
// wildcard-owned Type actually present, an empty group only for an explicit
// declaration, and never a group keyed "*".
// declaration, never a group keyed "*", and — OW1 = A — the whole owned set,
// every group together, within the wildcard's max, the explicit group also
// within its own.
func TestCheckBeadRecordUnderAWildcard(t *testing.T) {
rev := graphops.MintRevision()
bead, _ := graphops.NewBead(graphops.BeadSpec{Path: "beads/m", TypeURL: "https://work.example/types/memory", Revision: rev})
@ -1210,47 +1295,78 @@ func TestCheckBeadRecordUnderAWildcard(t *testing.T) {
return l
}
const blocks, cites, relates = "https://work.example/types/blocks", "https://work.example/types/cites", "https://work.example/types/relates"
citesDecl, _ := graphops.NewOwnedLinkDecl(cites, "", 8)
// The wildcard's 5 bounds the whole owned set; cites' 3 bounds the cites
// Links inside it (a descriptor that exists never has it the other way).
citesDecl, _ := graphops.NewOwnedLinkDecl(cites, "", 3)
wildcard, _ := graphops.NewWildcardOwnedLinkDecl(5)
owns := []graphops.OwnedLinkDecl{wildcard, citesDecl} // unsorted on purpose
blocksGroup := graphops.OwnedLinkGroup{TypeURL: blocks, Links: []graphops.Link{mk("links/b/1", blocks, self)}}
relatesGroup := graphops.OwnedLinkGroup{TypeURL: relates, Links: []graphops.Link{mk("links/r/1", relates, self), mk("links/r/2", relates, self)}}
many := func(prefix, typeURL string, n int) []graphops.Link {
links := make([]graphops.Link, 0, n)
for i := 1; i <= n; i++ {
links = append(links, mk(fmt.Sprintf("%s/%d", prefix, i), typeURL, self))
}
return links
}
blocksGroup := graphops.OwnedLinkGroup{TypeURL: blocks, Links: many("links/b", blocks, 1)}
relatesGroup := graphops.OwnedLinkGroup{TypeURL: relates, Links: many("links/r", relates, 2)}
for name, groups := range map[string][]graphops.OwnedLinkGroup{
"present wildcard groups around the empty explicit group": {blocksGroup, {TypeURL: cites}, relatesGroup},
"the explicit group alone": {{TypeURL: cites}},
"the explicit group with Links": {{TypeURL: cites, Links: []graphops.Link{mk("links/c/1", cites, self)}}},
"the explicit group with Links": {{TypeURL: cites, Links: many("links/c", cites, 1)}},
"a wildcard group before the explicit group": {blocksGroup, {TypeURL: cites}},
"a wildcard group after the explicit group": {{TypeURL: cites}, relatesGroup},
"the whole owned set at the wildcard's max": {blocksGroup, {TypeURL: cites, Links: many("links/c", cites, 2)}, relatesGroup},
"the explicit group at its own max": {{TypeURL: cites, Links: many("links/c", cites, 3)}, relatesGroup},
"wildcard-owned Links alone at the whole-set max": {{TypeURL: cites}, {TypeURL: relates, Links: many("links/r", relates, 5)}},
} {
if err := graphops.CheckBeadRecord(graphops.BeadRecord{Bead: bead, OwnedLinks: groups}, owns); err != nil {
t.Errorf("record %s refused: %v", name, err)
}
}
for name, groups := range map[string][]graphops.OwnedLinkGroup{
"a group keyed by the wildcard": {{TypeURL: graphops.WildcardOwnedLinkKey}, {TypeURL: cites}},
"an empty wildcard-owned group": {{TypeURL: blocks}, {TypeURL: cites}},
"no explicit group, a wildcard group before it": {blocksGroup},
"no explicit group, a wildcard group after it": {relatesGroup},
"groups out of order": {{TypeURL: cites}, blocksGroup},
"a repeated group": {{TypeURL: cites}, {TypeURL: cites}},
"a wildcard group holding another Type's Link": {{TypeURL: blocks, Links: []graphops.Link{mk("links/r/1", relates, self)}}, {TypeURL: cites}},
"a wildcard group holding another source's Link": {{TypeURL: blocks, Links: []graphops.Link{mk("links/b/1", blocks, other)}}, {TypeURL: cites}},
"a wildcard group with unsorted Links": {{TypeURL: cites}, {TypeURL: relates, Links: []graphops.Link{mk("links/r/2", relates, self), mk("links/r/1", relates, self)}}},
"a group keyed by the wildcard": {{TypeURL: graphops.WildcardOwnedLinkKey}, {TypeURL: cites}},
"an empty wildcard-owned group": {{TypeURL: blocks}, {TypeURL: cites}},
"no explicit group, a wildcard group before it": {blocksGroup},
"no explicit group, a wildcard group after it": {relatesGroup},
"groups out of order": {{TypeURL: cites}, blocksGroup},
"a repeated group": {{TypeURL: cites}, {TypeURL: cites}},
"a wildcard group holding another Type's Link": {{TypeURL: blocks, Links: []graphops.Link{mk("links/r/1", relates, self)}}, {TypeURL: cites}},
"a wildcard group holding another source's Link": {{TypeURL: blocks, Links: []graphops.Link{mk("links/b/1", blocks, other)}}, {TypeURL: cites}},
"a wildcard group with unsorted Links": {{TypeURL: cites}, {TypeURL: relates, Links: []graphops.Link{mk("links/r/2", relates, self), mk("links/r/1", relates, self)}}},
"the whole owned set over the wildcard's max": {blocksGroup, {TypeURL: cites, Links: many("links/c", cites, 3)}, relatesGroup},
"wildcard-owned Links alone over the whole-set max": {{TypeURL: cites}, {TypeURL: relates, Links: many("links/r", relates, 6)}},
"the explicit group over its own max, under the whole-set max": {{TypeURL: cites, Links: many("links/c", cites, 4)}},
} {
if err := graphops.CheckBeadRecord(graphops.BeadRecord{Bead: bead, OwnedLinks: groups}, owns); !errors.Is(err, graphops.ErrValidation) {
t.Errorf("record %s: want ErrValidation, got %v", name, err)
}
}
// The bound refusals name the set that overflowed, the count and the max.
over := graphops.BeadRecord{Bead: bead, OwnedLinks: []graphops.OwnedLinkGroup{blocksGroup, {TypeURL: cites, Links: many("links/c", cites, 3)}, relatesGroup}}
if err := graphops.CheckBeadRecord(over, owns); err == nil || !strings.Contains(err.Error(), "6 owned Links across all groups, over the wildcard's whole-set max 5") {
t.Errorf("whole-set refusal must name the count and the bound: %v", err)
}
overExplicit := graphops.BeadRecord{Bead: bead, OwnedLinks: []graphops.OwnedLinkGroup{{TypeURL: cites, Links: many("links/c", cites, 4)}}}
if err := graphops.CheckBeadRecord(overExplicit, owns); err == nil || !strings.Contains(err.Error(), "ownedLinks group https://work.example/types/cites holds 4 Links, over its declared max 3") {
t.Errorf("explicit refusal must name the group, the count and the bound: %v", err)
}
// Without a wildcard nothing changed: an unnamed Type's group is refused
// even when it holds that Type's Links.
if err := graphops.CheckBeadRecord(graphops.BeadRecord{Bead: bead, OwnedLinks: []graphops.OwnedLinkGroup{blocksGroup, {TypeURL: cites}}}, []graphops.OwnedLinkDecl{citesDecl}); !errors.Is(err, graphops.ErrValidation) {
t.Errorf("unnamed Type without a wildcard: want ErrValidation, got %v", err)
}
// A Type owning only through the wildcard, with nothing present, has no
// groups at all.
// groups at all; with Links present, the whole set is bounded exactly as
// when explicit declarations sit beside the wildcard.
if err := graphops.CheckBeadRecord(graphops.BeadRecord{Bead: bead}, []graphops.OwnedLinkDecl{wildcard}); err != nil {
t.Errorf("lone wildcard, nothing present: %v", err)
}
if err := graphops.CheckBeadRecord(graphops.BeadRecord{Bead: bead, OwnedLinks: []graphops.OwnedLinkGroup{blocksGroup, {TypeURL: relates, Links: many("links/r", relates, 4)}}}, []graphops.OwnedLinkDecl{wildcard}); err != nil {
t.Errorf("lone wildcard, whole set at its max: %v", err)
}
if err := graphops.CheckBeadRecord(graphops.BeadRecord{Bead: bead, OwnedLinks: []graphops.OwnedLinkGroup{blocksGroup, {TypeURL: relates, Links: many("links/r", relates, 5)}}}, []graphops.OwnedLinkDecl{wildcard}); !errors.Is(err, graphops.ErrValidation) {
t.Errorf("lone wildcard, whole set over its max: want ErrValidation, got %v", err)
}
}
// ownsOutgoing max obeys the binary64 admission law at both of its doors
@ -1277,11 +1393,12 @@ func TestOwnedLinkDeclMaxObeysTheBinary64Law(t *testing.T) {
t.Errorf("descriptor max %d: want the binary64 refusal at the member's pointer, got %v", max, err)
}
}
explicit, err := graphops.NewOwnedLinkDecl(c, "", 9007199254740994)
// Both admitted values, the explicit one under the wildcard's (OW1 = A).
explicit, err := graphops.NewOwnedLinkDecl(c, "", 9007199254740992)
if err != nil {
t.Fatal(err)
}
wildcard, err := graphops.NewWildcardOwnedLinkDecl(9007199254740992)
wildcard, err := graphops.NewWildcardOwnedLinkDecl(9007199254740994)
if err != nil {
t.Fatal(err)
}
@ -1289,7 +1406,7 @@ func TestOwnedLinkDeclMaxObeysTheBinary64Law(t *testing.T) {
if err != nil {
t.Fatal(err)
}
want := `{"conformsTo":[],"describes":"bead","id":"https://work.example/types/x","name":"X","ownsOutgoing":{"*":{"max":9007199254740992},"https://work.example/types/c":{"max":9007199254740994}}}`
want := `{"conformsTo":[],"describes":"bead","id":"https://work.example/types/x","name":"X","ownsOutgoing":{"*":{"max":9007199254740994},"https://work.example/types/c":{"max":9007199254740992}}}`
if got := string(built.CanonicalJSON()); got != want {
t.Fatalf("canonical form\n got %s\nwant %s", got, want)
}
@ -1301,7 +1418,7 @@ func TestOwnedLinkDeclMaxObeysTheBinary64Law(t *testing.T) {
for _, d := range parsed.OwnsOutgoing() {
maxes[d.TypeURL()] = d.Max()
}
if len(maxes) != 2 || maxes[c] != 9007199254740994 || maxes[graphops.WildcardOwnedLinkKey] != 9007199254740992 {
if len(maxes) != 2 || maxes[c] != 9007199254740992 || maxes[graphops.WildcardOwnedLinkKey] != 9007199254740994 {
t.Fatalf("max values after the round trip: %v", maxes)
}
}