graphops: admit the wildcard owned-Link declaration "*": { max } (bdp#1 item 5)

A Bead Type's ownsOutgoing MAY carry the reserved key "*" with a max,
declaring every outgoing Link Type not listed explicitly as owned; max
bounds the whole wildcard-owned set; explicit entries take precedence for
the Types they name (operator ruling, 2026-09-08).

OwnedLinkDecl is now a sum — explicit (NewOwnedLinkDecl) or wildcard
(NewWildcardOwnedLinkDecl; Wildcard() tells them apart) — modelled as the
reserved key inside the declaration list: the canonical form serializes
it as the "*" key of ownsOutgoing, sorted first (0x2A precedes every URL),
so the fingerprint is the wire form's once the pin moves, the duplicate
law refuses two wildcards unchanged, and a consumer walking OwnsOutgoing()
cannot overlook it. Owns resolves explicit-then-wildcard and Owns("*") is
false. max is required on the wildcard exactly as on an explicit entry; a
label on it is refused. ValidateTypeURL refuses "*" by name, so it is
never a Link's type, an endpoint or descriptor conformsTo entry, an id or
a propertiesSchema. CheckBeadRecord's acceptance law: groups ascend by
Link Type URL, none keyed "*", exactly one group (possibly empty) per
explicit declaration, and a group for any other Type only under a
wildcard and only when it holds a Link.

The wire stays pinned: internal/httpapi/bdpwire is unchanged in
production. The bundle at 0b7d86e7 keys ownsOutgoing and ownedLinks by
absoluteHttpUrl, so "*" is schema-invalid on the wire until the pin
moves; the strict decoder holds shape, not key grammar, and decodes the
key. A test-only tripwire (TestWildcardOwnedLinkKeyIsNotInThePinnedBundle)
asserts both facts and fails the day the pin admits the key, retiring the
run-ahead note on WildcardOwnedLinkKey with it.

DECISIONs recorded: reserved-key representation; no label on the
wildcard; the wildcard max bounds the Links owned by virtue of the
wildcard (explicit Types keep their own maxes); Owns("*") is false;
ValidateTypeURL refuses "*" by name; Max is not checked by
CheckBeadRecord (it is the serving LIMIT law).

graphops stays at 100% statement coverage; golangci-lint 0 issues;
bdpwire parity tests pass; make api-check passes.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Donna Box 2026-09-08 11:01:14 -03:00
commit 1cbb5e6e3c
6 changed files with 440 additions and 51 deletions

View file

@ -1421,6 +1421,14 @@ func validateCanonicalHTTPURL(s, what string, echo bool) (urlParts, error) {
// a Type ID, a propertiesSchema or a discovery member may be. A query is
// permitted; a fragment is not.
func ValidateTypeURL(s string) error {
if s == WildcardOwnedLinkKey {
// DECISION: refused by name, not by accident of the URL grammar.
// "*" is an ownsOutgoing KEY (bdp#1 item 5), never a Type — not a
// Link's type, not a descriptor's or an endpoint's conformsTo
// entry, not an id or a propertiesSchema — and the diagnostic
// says which of the two the author reached for.
return fmt.Errorf("%w: %q is the wildcard owned-Link key, not a Type URL", ErrValidation, s)
}
_, err := validateCanonicalHTTPURL(s, "URL", true)
return err
}

View file

@ -682,6 +682,7 @@ func TestValidateTypeURL(t *testing.T) {
"https://work.example/<x>", "mailto:a@b", "https://work.example:x/", "https://work.example:/",
"https://:8080/", "https://work.example/x\n", "1http://x/",
"https://work.example:0443/t", "https://0x7f000001/t", "https://work%2Eexample/t", "https://[::ffff:1.2.3.4]/t",
graphops.WildcardOwnedLinkKey, // the ownsOutgoing wildcard key is never a Type
}
for _, u := range reject {
wantValidation(t, graphops.ValidateTypeURL(u), "Type URL "+u)

View file

@ -76,9 +76,11 @@ type IncidentRequest struct {
// per call from this workspace's authoritative state.
type Reader interface {
// Bead returns one Bead with its complete ownedLinks expansion, assembled
// in the same snapshot: one group per owned Link Type the Bead's Type
// declares, in code-unit order of Type URL, empty groups included, each
// group's Links in code-unit order of path. A path that never existed or
// in the same snapshot — the groups BeadRecord documents: one per Link
// Type the Bead's Type declares explicitly, empty groups included, plus
// one per wildcard-owned Type actually present, in code-unit order of
// Type URL, each group's Links in code-unit order of path (the law is
// CheckBeadRecord). A path that never existed or
// is not visible is ErrNotFound; a path in a gone state is a *GoneError,
// which also matches ErrNotFound.
Bead(ctx context.Context, req BeadRequest) (BeadRecord, error)

View file

@ -656,18 +656,50 @@ func (c EndpointConstraint) EffectiveExternal() ExternalPolicy {
return c.external
}
// OwnedLinkDecl is one ownsOutgoing entry of a Bead Type Descriptor: the owned
// Link Type, the required bound on the owned set, and an optional display
// label that appears only in the descriptor, never in a Resource record.
// WildcardOwnedLinkKey is the reserved ownsOutgoing key "*" (bdp#1 item 5,
// ruled 2026-09-08): a Bead Type MAY carry the entry "*": { max }, declaring
// every outgoing Link Type it does not list explicitly as owned. It is a KEY,
// never a Type: ValidateTypeURL refuses it, so no Link's type, no descriptor
// or endpoint conformsTo entry, no descriptor id and no ownedLinks group key
// can spell it.
//
// THE DOMAIN RUNS AHEAD OF THE PINNED WIRE HERE. The bundle vendored at
// bdpwire.Pin (0b7d86e7) keys ownsOutgoing — and a record's ownedLinks — by
// absoluteHttpUrl, so a descriptor carrying this key is schema-invalid on the
// wire until the pin moves to the bdp change that lands the ruling. The
// refusal is the bundle's: bdpwire's strict decoder holds member shape, not
// key grammar, and decodes the key. internal/httpapi/bdpwire's
// TestWildcardOwnedLinkKeyIsNotInThePinnedBundle asserts both facts and is
// the tripwire that retires this note when the pin moves.
const WildcardOwnedLinkKey = "*"
// OwnedLinkDecl is one ownsOutgoing entry of a Bead Type Descriptor. It is a
// SUM: an EXPLICIT declaration names one owned Link Type and may carry a
// display label (descriptor-only, never in a Resource record); the WILDCARD
// declaration, keyed WildcardOwnedLinkKey, owns every outgoing Link Type the
// descriptor does not name explicitly and carries no label. Both carry the
// required bound.
//
// DECISION: the wildcard is the reserved key INSIDE the declaration list, not
// a separate descriptor member. The canonical form then falls out of the
// existing map ("*" sorts first — 0x2A precedes every URL's "h" — so the
// fingerprint is the wire form's once the pin moves), the duplicate law
// covers "two wildcards" unchanged, and — the reason that matters most — a
// consumer walking OwnsOutgoing() to assemble ownedLinks cannot overlook it:
// it meets a declaration whose Wildcard() is true, and a record that keyed a
// group by it fails CheckBeadRecord. A separate accessor would let that
// consumer silently serve an incomplete record.
type OwnedLinkDecl struct {
typeURL string
label string
typeURL string // the owned Link Type, or WildcardOwnedLinkKey
label string // "" when absent; always "" on the wildcard
max int
}
// NewOwnedLinkDecl builds a declaration. Max is REQUIRED and positive — the
// installer refuses an owning declaration without a bound, because the owned
// plane must always be servable inline. label "" means absent.
// NewOwnedLinkDecl builds an explicit declaration. Max is REQUIRED and
// positive — the installer refuses an owning declaration without a bound,
// because the owned plane must always be servable inline. label "" means
// absent. The wildcard key is refused here (ValidateTypeURL): the wildcard
// is built by NewWildcardOwnedLinkDecl, never by naming "*" as a Type.
func NewOwnedLinkDecl(linkTypeURL, label string, max int) (OwnedLinkDecl, error) {
if err := ValidateTypeURL(linkTypeURL); err != nil {
return OwnedLinkDecl{}, fmt.Errorf("ownsOutgoing key: %w", err)
@ -681,13 +713,49 @@ func NewOwnedLinkDecl(linkTypeURL, label string, max int) (OwnedLinkDecl, error)
return OwnedLinkDecl{typeURL: linkTypeURL, label: label, max: max}, nil
}
// TypeURL is the owned Link Type.
// 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.
//
// DECISION: no label. The ruling spells the entry as "*": { max }, and a
// label is display documentation for one named Type; the wildcard names
// none, so a label on it is refused — conservative, because admitting one
// 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.
func NewWildcardOwnedLinkDecl(max int) (OwnedLinkDecl, error) {
if max < 1 {
return OwnedLinkDecl{}, fmt.Errorf("%w: ownsOutgoing %s: max must be a positive integer", ErrValidation, WildcardOwnedLinkKey)
}
return OwnedLinkDecl{typeURL: WildcardOwnedLinkKey, max: max}, nil
}
// Wildcard reports whether d is the wildcard declaration.
func (d OwnedLinkDecl) Wildcard() bool { return d.typeURL == WildcardOwnedLinkKey }
// TypeURL is the owned Link Type — or WildcardOwnedLinkKey for the wildcard
// declaration, which names no Type: check Wildcard() before using the value
// as a URL.
func (d OwnedLinkDecl) TypeURL() string { return d.typeURL }
// Label returns the display label and whether one is present.
// Label returns the display label and whether one is present; never present
// on the wildcard.
func (d OwnedLinkDecl) Label() (string, bool) { return d.label, d.label != "" }
// Max is the largest owned set the Type permits.
// 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.
func (d OwnedLinkDecl) Max() int { return d.max }
// TypeDescriptor is one installed Type contract: the closed BDP v0 descriptor
@ -703,7 +771,7 @@ type TypeDescriptor struct {
conformsTo []string
propertiesSchema string // "" when absent
source, target EndpointConstraint
ownsOutgoing []OwnedLinkDecl // sorted by TypeURL in code-unit order
ownsOutgoing []OwnedLinkDecl // sorted by key in code-unit order: the wildcard ("*") first when present, then Type URLs
canonical []byte
fingerprint string
}
@ -730,8 +798,10 @@ type TypeDescriptorSpec struct {
// Bead Type. A pointer to the zero EndpointConstraint is the constraint
// that requires nothing.
Source, Target *EndpointConstraint
// OwnsOutgoing declares the owned Link Types of a Bead Type; empty means
// the member is absent. Must be empty for a Link Type.
// 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.
OwnsOutgoing []OwnedLinkDecl
}
@ -739,7 +809,9 @@ 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, and one declaration per owned Link Type.
// only when it describes Beads, one declaration per owned Link Type and at
// most one wildcard (bdp#1 item 5, ahead of the pinned bundle — see
// WildcardOwnedLinkKey).
func NewTypeDescriptor(spec TypeDescriptorSpec) (TypeDescriptor, error) {
if err := ValidateTypeURL(spec.ID); err != nil {
return TypeDescriptor{}, fmt.Errorf("descriptor id: %w", err)
@ -800,7 +872,8 @@ func NewTypeDescriptor(spec TypeDescriptorSpec) (TypeDescriptor, error) {
return TypeDescriptor{}, fmt.Errorf("%w: descriptor %s: ownsOutgoing entry %d is not a constructed declaration", ErrValidation, spec.ID, i)
}
if i > 0 && owns[i-1].typeURL == decl.typeURL {
return TypeDescriptor{}, fmt.Errorf("%w: descriptor %s owns %s twice", ErrValidation, spec.ID, decl.typeURL)
// The same law refuses two wildcards: both are keyed "*".
return TypeDescriptor{}, fmt.Errorf("%w: descriptor %s: ownsOutgoing declares %s twice", ErrValidation, spec.ID, decl.typeURL)
}
}
d.ownsOutgoing = owns
@ -871,6 +944,8 @@ func descriptorCanonicalJSON(d TypeDescriptor) []byte {
}
if len(d.ownsOutgoing) > 0 {
w.OwnsOutgoing = make(map[string]ownedLinkWire, len(d.ownsOutgoing))
// The wildcard's key is "*" (WildcardOwnedLinkKey), the wire spelling
// the ruling gives it; CanonicalizeJSON sorts it before every URL.
for _, decl := range d.ownsOutgoing {
w.OwnsOutgoing[decl.typeURL] = ownedLinkWire{Label: optionalString(decl.label), Max: decl.max}
}
@ -910,8 +985,10 @@ var descriptorMembers = map[string]memberShape{
// the bundle gives it and is never null (absent and null are different
// things, and the bundle admits only absence), the required members are
// present, a Bead Type carries no endpoint constraint and a Link Type no
// ownsOutgoing, propertiesSchema when present is an absolute URL, and every
// law NewTypeDescriptor enforces holds.
// 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.
//
// 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
@ -1047,9 +1124,12 @@ func parseEndpointConstraint(canonical []byte, member string) (EndpointConstrain
return NewEndpointConstraint(conformsTo, external)
}
func parseOwnedLinkDecl(url string, canonical []byte) (OwnedLinkDecl, error) {
// parseOwnedLinkDecl reads one ownsOutgoing entry. The key is the wildcard
// (WildcardOwnedLinkKey) or a Link Type URL; the value's shape is the same
// for both, except that the wildcard refuses a label.
func parseOwnedLinkDecl(key string, canonical []byte) (OwnedLinkDecl, error) {
fail := func(format string, args ...any) (OwnedLinkDecl, error) {
return OwnedLinkDecl{}, fmt.Errorf("%w: descriptor: ownsOutgoing %s: %s", ErrValidation, url, fmt.Sprintf(format, args...))
return OwnedLinkDecl{}, fmt.Errorf("%w: descriptor: ownsOutgoing %s: %s", ErrValidation, key, fmt.Sprintf(format, args...))
}
if canonical[0] != '{' {
return fail("declaration must be an object, never null")
@ -1082,7 +1162,13 @@ func parseOwnedLinkDecl(url string, canonical []byte) (OwnedLinkDecl, error) {
if !hasMax {
return fail("max is required")
}
return NewOwnedLinkDecl(url, label, max)
if key == WildcardOwnedLinkKey {
if label != "" {
return fail("the wildcard declaration carries no label")
}
return NewWildcardOwnedLinkDecl(max)
}
return NewOwnedLinkDecl(key, label, max)
}
// typeURLList validates a Type-ID array — canonical URLs, no duplicates —
@ -1132,22 +1218,40 @@ func (t TypeDescriptor) Source() (EndpointConstraint, bool) { return t.source, t
// Target returns the target constraint and whether the Type describes Links.
func (t TypeDescriptor) Target() (EndpointConstraint, bool) { return t.target, t.describes == KindLink }
// OwnsOutgoing returns a copy of the owned-Link declarations, in code-unit
// order of Link Type URL — the order ownedLinks groups are served in.
// OwnsOutgoing returns a copy of the owned-Link declarations in code-unit
// order of key: the wildcard first when present ("*" sorts before every
// URL), then the explicit declarations by Link Type URL — the order their
// ownedLinks groups are served in, with the wildcard's own groups (one per
// wildcard-owned Type actually present) interleaved among them by URL.
func (t TypeDescriptor) OwnsOutgoing() []OwnedLinkDecl {
return append([]OwnedLinkDecl(nil), t.ownsOutgoing...)
}
// Owns returns the declaration for linkTypeURL and whether this Type owns it.
// Owns returns the declaration under which this Type owns Links of Type
// linkTypeURL and whether it owns them: the explicit declaration naming the
// 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.
//
// 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
// the wildcard declaration there would hand a caller a "Type" it could key
// a group by.
func (t TypeDescriptor) Owns(linkTypeURL string) (OwnedLinkDecl, bool) {
if linkTypeURL == WildcardOwnedLinkKey {
return OwnedLinkDecl{}, false
}
var wildcard OwnedLinkDecl
for _, decl := range t.ownsOutgoing {
if decl.typeURL == linkTypeURL {
switch {
case decl.typeURL == linkTypeURL:
return decl, true
case decl.Wildcard():
wildcard = decl
}
}
return OwnedLinkDecl{}, false
return wildcard, wildcard.Wildcard()
}
// CanonicalJSON returns a copy of the descriptor's canonical bytes: the closed
@ -1644,52 +1748,91 @@ func (m LedgerManifest) Covers(events []LedgerEvent) error {
}
// OwnedLinkGroup is one ownedLinks entry: the owned Link Type and the owned
// Links of one Bead under it, complete records in code-unit order of path. An
// owned Type with no Links is an EMPTY group, never an absent one.
// Links of one Bead under it, complete records in code-unit order of path.
// The key is always a Link Type URL, never WildcardOwnedLinkKey. An
// 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").
type OwnedLinkGroup struct {
TypeURL string
Links []Link
}
// BeadRecord is a Bead with its complete ownedLinks expansion, assembled in
// the same snapshot: one group per owned Link Type the Bead's Type declares,
// in code-unit order of TypeURL, empty groups included; nil when the Type owns
// nothing. Every projection — singleton, collection item, selection item —
// returns records, because the Bead's revision covers its owned Links.
// the same snapshot: one group per Link Type the Bead's Type declares
// explicitly, empty groups included, plus — under a wildcard declaration —
// 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.
type BeadRecord struct {
Bead Bead
OwnedLinks []OwnedLinkGroup
}
// CheckBeadRecord verifies a record against the owned-Link declarations of the
// Bead's Type: exactly one group per declaration, in code-unit order, and 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.
// Bead's Type (its OwnsOutgoing, in any order): the groups ascend in code-unit
// 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
// 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.
func CheckBeadRecord(record BeadRecord, owns []OwnedLinkDecl) error {
if len(record.OwnedLinks) != len(owns) {
return fmt.Errorf("%w: bead %s: %d ownedLinks groups for %d owned Types", ErrValidation, record.Bead.Path(), len(record.OwnedLinks), len(owns))
fail := func(format string, args ...any) error {
return fmt.Errorf("%w: bead %s: %s", ErrValidation, record.Bead.Path(), fmt.Sprintf(format, args...))
}
sorted := append([]OwnedLinkDecl(nil), owns...)
sort.SliceStable(sorted, func(i, j int) bool {
return CompareCodeUnits(sorted[i].typeURL, sorted[j].typeURL) < 0
var explicit []OwnedLinkDecl
wildcard := false
for _, decl := range owns {
if decl.Wildcard() {
wildcard = true
continue
}
explicit = append(explicit, decl)
}
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
for i, group := range record.OwnedLinks {
if group.TypeURL != sorted[i].typeURL {
return fmt.Errorf("%w: bead %s: ownedLinks group %d is %s, want %s", ErrValidation, record.Bead.Path(), i, group.TypeURL, sorted[i].typeURL)
if group.TypeURL == WildcardOwnedLinkKey {
return fail("ownedLinks group %d is keyed by the wildcard; groups are keyed by Link Type URL", i)
}
if i > 0 && CompareCodeUnits(record.OwnedLinks[i-1].TypeURL, group.TypeURL) >= 0 {
return fail("ownedLinks groups are not in ascending code-unit order at %s", group.TypeURL)
}
// Groups ascend, so an explicit declaration below this key that is
// still unmatched has no group at all.
if next < len(explicit) && CompareCodeUnits(explicit[next].typeURL, group.TypeURL) < 0 {
return fail("no ownedLinks group for explicitly owned %s", explicit[next].typeURL)
}
switch {
case next < len(explicit) && explicit[next].typeURL == group.TypeURL:
next++ // the explicit declaration's group, empty or not
case !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)
}
for j, link := range group.Links {
if link.TypeURL() != group.TypeURL {
return fmt.Errorf("%w: bead %s: owned Link %s has type %s under group %s", ErrValidation, record.Bead.Path(), link.Path(), link.TypeURL(), group.TypeURL)
return fail("owned Link %s has type %s under group %s", link.Path(), link.TypeURL(), group.TypeURL)
}
if !link.Source().InScope() || link.Source().Path() != record.Bead.Path() {
return fmt.Errorf("%w: bead %s: owned Link %s has another source", ErrValidation, record.Bead.Path(), link.Path())
return fail("owned Link %s has another source", link.Path())
}
if j > 0 && CompareCodeUnits(group.Links[j-1].Path(), link.Path()) >= 0 {
return fmt.Errorf("%w: bead %s: owned Links under %s are not in ascending code-unit order", ErrValidation, record.Bead.Path(), group.TypeURL)
return fail("owned Links under %s are not in ascending code-unit order", group.TypeURL)
}
}
}
if next < len(explicit) {
return fail("no ownedLinks group for explicitly owned %s", explicit[next].typeURL)
}
return nil
}

View file

@ -853,9 +853,19 @@ func assertClosedDescriptorShape(t *testing.T, canonical []byte) {
if len(*shape.OwnsOutgoing) == 0 {
t.Errorf("ownsOutgoing must be omitted rather than empty")
}
for url, decl := range *shape.OwnsOutgoing {
for key, decl := range *shape.OwnsOutgoing {
// The bundle keys ownsOutgoing by absoluteHttpUrl; the domain
// runs ahead of it by exactly one key, the wildcard "*", which
// carries no label (graphops.WildcardOwnedLinkKey).
if key == graphops.WildcardOwnedLinkKey {
if decl.Label != nil {
t.Errorf("ownsOutgoing %s: the wildcard carries no label", key)
}
} else if err := graphops.ValidateTypeURL(key); err != nil {
t.Errorf("ownsOutgoing key %q is neither a Type URL nor the wildcard: %v", key, err)
}
if decl.Max == nil || *decl.Max < 1 || (decl.Label != nil && *decl.Label == "") {
t.Errorf("ownsOutgoing %s: max must be a positive integer and label nonempty when present", url)
t.Errorf("ownsOutgoing %s: max must be a positive integer and label nonempty when present", key)
}
}
}
@ -875,12 +885,14 @@ func TestTypeDescriptorRoundTripsThroughItsCanonicalForm(t *testing.T) {
beadShaped, _ := graphops.NewEndpointConstraint([]string{a}, graphops.ExternalBead)
cites8, _ := graphops.NewOwnedLinkDecl(c, "cites — α", 8)
blocks2, _ := graphops.NewOwnedLinkDecl(b, "", 2)
wild5, _ := graphops.NewWildcardOwnedLinkDecl(5)
for name, spec := range map[string]graphops.TypeDescriptorSpec{
"link with zero endpoints": {ID: "https://work.example/types/l0", Name: "L0", Describes: graphops.KindLink, Source: &graphops.EndpointConstraint{}, Target: &graphops.EndpointConstraint{}},
"link with constructed anything": {ID: "https://work.example/types/l1", Name: "L1", Describes: graphops.KindLink, Source: &anyBead, Target: &anyBead},
"link with policies": {ID: "https://work.example/types/l2", Name: "L2", Description: "d", Describes: graphops.KindLink, ConformsTo: []string{b, a}, PropertiesSchema: "https://work.example/schemas/l2", Source: &none, Target: &beadShaped},
"bead minimal": {ID: "https://work.example/types/b0", Name: "B0", Describes: graphops.KindBead},
"bead owning": {ID: "https://work.example/types/b1", Name: "B1 ✓", Description: "owns", Describes: graphops.KindBead, ConformsTo: []string{c, a, b}, OwnsOutgoing: []graphops.OwnedLinkDecl{cites8, blocks2}},
"bead owning by wildcard": {ID: "https://work.example/types/b2", Name: "B2", Describes: graphops.KindBead, OwnsOutgoing: []graphops.OwnedLinkDecl{blocks2, wild5}},
} {
built, err := graphops.NewTypeDescriptor(spec)
if err != nil {
@ -1057,3 +1069,184 @@ func TestErrorsAreOneVocabulary(t *testing.T) {
t.Fatal("wrapping keeps the relation")
}
}
// 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
// vendored in internal/httpapi/bdpwire keys ownsOutgoing by absoluteHttpUrl
// until the pin moves (graphops.WildcardOwnedLinkKey; the tripwire is
// bdpwire's TestWildcardOwnedLinkKeyIsNotInThePinnedBundle) — so the
// canonical form below is what the wire WILL carry, pinned byte-exactly with
// "*" 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)
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 (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}})
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"
if got := string(built.CanonicalJSON()); got != wantCanonical {
t.Fatalf("canonical wildcard descriptor\n got %s\nwant %s", got, wantCanonical)
}
if built.Fingerprint() != wantFingerprint || built.Fingerprint() != sha256Hex([]byte(wantCanonical)) {
t.Fatalf("fingerprint %s, want the golden %s", built.Fingerprint(), wantFingerprint)
}
assertClosedDescriptorShape(t, built.CanonicalJSON())
if owns := built.OwnsOutgoing(); len(owns) != 2 || !owns[0].Wildcard() || owns[1].TypeURL() != cites {
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 {
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 {
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}}}`))
if err != nil {
t.Fatal(err)
}
if parsed.Fingerprint() != wantFingerprint || string(parsed.CanonicalJSON()) != wantCanonical {
t.Fatalf("parsed wildcard descriptor: %s", parsed.CanonicalJSON())
}
// A wildcard alone owns everything, at its bound.
alone, err := graphops.ParseTypeDescriptor([]byte(`{"id":"https://work.example/types/memory","name":"Memory","describes":"bead","conformsTo":[],"ownsOutgoing":{"*":{"max":1}}}`))
if err != nil {
t.Fatal(err)
}
const wantAlone = `{"conformsTo":[],"describes":"bead","id":"https://work.example/types/memory","name":"Memory","ownsOutgoing":{"*":{"max":1}}}`
if got := string(alone.CanonicalJSON()); got != wantAlone || alone.Fingerprint() != "44ac14cf761e1c41d7c7a2f0c927c0456ae37b0a81c3f777d8f9fe059ddc4321" {
t.Fatalf("canonical wildcard-only descriptor: %s %s", got, alone.Fingerprint())
}
if got, ok := alone.Owns(cites); !ok || !got.Wildcard() || got.Max() != 1 || len(alone.OwnsOutgoing()) != 1 {
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}})
if _, ok := plain.Owns(relates); ok {
t.Fatal("no wildcard: an unnamed Type is not owned")
}
// Refusals through the parser: max is required on the wildcard exactly
// as on an explicit entry, a label on it is refused, and "*" is not a
// Type anywhere a Type URL is read.
for name, in := range map[string]string{
"wildcard without max": `{"id":"https://work.example/types/x","name":"X","describes":"bead","conformsTo":[],"ownsOutgoing":{"*":{}}}`,
"wildcard max zero": `{"id":"https://work.example/types/x","name":"X","describes":"bead","conformsTo":[],"ownsOutgoing":{"*":{"max":0}}}`,
"wildcard max negative": `{"id":"https://work.example/types/x","name":"X","describes":"bead","conformsTo":[],"ownsOutgoing":{"*":{"max":-1}}}`,
"wildcard max fractional": `{"id":"https://work.example/types/x","name":"X","describes":"bead","conformsTo":[],"ownsOutgoing":{"*":{"max":1.5}}}`,
"wildcard with label": `{"id":"https://work.example/types/x","name":"X","describes":"bead","conformsTo":[],"ownsOutgoing":{"*":{"label":"any","max":1}}}`,
"wildcard with empty label": `{"id":"https://work.example/types/x","name":"X","describes":"bead","conformsTo":[],"ownsOutgoing":{"*":{"label":"","max":1}}}`,
"wildcard unknown member": `{"id":"https://work.example/types/x","name":"X","describes":"bead","conformsTo":[],"ownsOutgoing":{"*":{"max":1,"min":0}}}`,
"wildcard entry null": `{"id":"https://work.example/types/x","name":"X","describes":"bead","conformsTo":[],"ownsOutgoing":{"*":null}}`,
"wildcard on a Link Type": `{"id":"https://work.example/types/x","name":"X","describes":"link","conformsTo":[],"source":{"conformsTo":[]},"target":{"conformsTo":[]},"ownsOutgoing":{"*":{"max":1}}}`,
"wildcard as id": `{"id":"*","name":"X","describes":"bead","conformsTo":[]}`,
"wildcard as parent": `{"id":"https://work.example/types/x","name":"X","describes":"bead","conformsTo":["*"]}`,
"wildcard as propertiesSchema": `{"id":"https://work.example/types/x","name":"X","describes":"bead","conformsTo":[],"propertiesSchema":"*"}`,
"wildcard as source parent": `{"id":"https://work.example/types/x","name":"X","describes":"link","conformsTo":[],"source":{"conformsTo":["*"]},"target":{"conformsTo":[]}}`,
"wildcard as target parent": `{"id":"https://work.example/types/x","name":"X","describes":"link","conformsTo":[],"source":{"conformsTo":[]},"target":{"conformsTo":["*"]}}`,
} {
if _, err := graphops.ParseTypeDescriptor([]byte(in)); !errors.Is(err, graphops.ErrValidation) {
t.Errorf("descriptor %s: want ErrValidation, got %v", name, err)
}
}
// Refusals at the constructors: the key is never a Type anywhere.
if _, err := graphops.NewWildcardOwnedLinkDecl(0); !errors.Is(err, graphops.ErrValidation) {
t.Errorf("wildcard max zero: %v", err)
}
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) {
t.Errorf("two wildcards: %v", err)
}
if _, err := graphops.NewEndpointConstraint([]string{graphops.WildcardOwnedLinkKey}, ""); !errors.Is(err, graphops.ErrValidation) {
t.Errorf("wildcard in an endpoint constraint: %v", err)
}
rev := graphops.MintRevision()
if _, err := graphops.NewBead(graphops.BeadSpec{Path: "beads/m", TypeURL: graphops.WildcardOwnedLinkKey, Revision: rev}); !errors.Is(err, graphops.ErrValidation) {
t.Errorf("wildcard as a Bead's type: %v", err)
}
self, _ := graphops.NewInScopeRef("beads/m", "")
if _, err := graphops.NewLink(graphops.LinkSpec{Path: "links/m/1", TypeURL: graphops.WildcardOwnedLinkKey, Revision: rev, Source: self, Target: self}); !errors.Is(err, graphops.ErrValidation) {
t.Errorf("wildcard as a Link's type: %v", err)
}
if err := graphops.ValidateTypeURL(graphops.WildcardOwnedLinkKey); !errors.Is(err, graphops.ErrValidation) || !strings.Contains(err.Error(), "wildcard owned-Link key") {
t.Errorf(`ValidateTypeURL("*") must refuse by name: %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 "*".
func TestCheckBeadRecordUnderAWildcard(t *testing.T) {
rev := graphops.MintRevision()
bead, _ := graphops.NewBead(graphops.BeadSpec{Path: "beads/m", TypeURL: "https://work.example/types/memory", Revision: rev})
self, _ := graphops.NewInScopeRef("beads/m", "")
other, _ := graphops.NewInScopeRef("beads/e", "")
mk := func(path, typeURL string, source graphops.Ref) graphops.Link {
l, err := graphops.NewLink(graphops.LinkSpec{Path: path, TypeURL: typeURL, Revision: rev, Source: source, Target: other})
if err != nil {
t.Fatal(err)
}
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)
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)}}
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)}}},
"a wildcard group before the explicit group": {blocksGroup, {TypeURL: cites}},
"a wildcard group after the explicit group": {{TypeURL: cites}, relatesGroup},
} {
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)}}},
} {
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)
}
}
// 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.
if err := graphops.CheckBeadRecord(graphops.BeadRecord{Bead: bead}, []graphops.OwnedLinkDecl{wildcard}); err != nil {
t.Errorf("lone wildcard, nothing present: %v", err)
}
}

View file

@ -0,0 +1,42 @@
package bdpwire
import (
"regexp"
"testing"
)
// THE DOMAIN RUNS AHEAD OF THE PINNED WIRE on the wildcard owned-Link
// declaration (bdp#1 item 5, ruled 2026-09-08): graphops admits the
// ownsOutgoing key "*" (graphops.WildcardOwnedLinkKey), while the bundle at
// Pin keys ownsOutgoing — and a record's ownedLinks — by absoluteHttpUrl, so
// a descriptor carrying "*" is schema-invalid on the wire until the pin moves
// to the bdp change that lands the ruling. This is the tripwire: it asserts
// the pinned facts, so the day the pin admits the key it fails and the
// run-ahead note in graphops retires with it.
//
// The refusal is the BUNDLE's, not the decoder's. The strict decoder holds
// member shape — names, types, nulls, integers — and not key grammar (it
// checks no ownedLinks key either), so it decodes the key; that is asserted
// too, so nobody moves the wire's key rule into the decoder, where the pin
// bump would then have to undo it. Test-only: no production change here.
func TestWildcardOwnedLinkKeyIsNotInThePinnedBundle(t *testing.T) {
defs := loadBundleDefs(t)
pattern := regexp.MustCompile(asString(t, asMap(t, defs["absoluteHttpUrl"], "absoluteHttpUrl")["pattern"], "absoluteHttpUrl.pattern"))
if pattern.MatchString("*") {
t.Fatalf("absoluteHttpUrl %s admits \"*\"", pattern)
}
for _, m := range []struct{ def, member string }{{"typeDescriptor", "ownsOutgoing"}, {"beadRecord", "ownedLinks"}} {
props := asMap(t, asMap(t, defs[m.def], m.def)["properties"], m.def+".properties")
names := asMap(t, asMap(t, props[m.member], m.member)["propertyNames"], m.member+".propertyNames")
if ref := names["$ref"]; ref != "#/$defs/absoluteHttpUrl" {
t.Fatalf("%s.%s.propertyNames = %v at pin %s: the pinned wire now admits a non-URL key — retire graphops's run-ahead note (WildcardOwnedLinkKey) and this tripwire together", m.def, m.member, names, Pin)
}
}
var d TypeDescriptor
if err := Unmarshal([]byte(`{"id":"`+typeURL+`","name":"X","describes":"bead","conformsTo":[],"ownsOutgoing":{"*":{"max":1}}}`), &d); err != nil {
t.Fatalf("the strict decoder holds shape, not key grammar; the wire's key rule lives in the bundle, not here: %v", err)
}
if decl, ok := d.OwnsOutgoing["*"]; !ok || decl.Max != 1 {
t.Fatalf("decoded ownsOutgoing = %+v", d.OwnsOutgoing)
}
}