diff --git a/graphops/laws.go b/graphops/laws.go index 42b020335..27995a388 100644 --- a/graphops/laws.go +++ b/graphops/laws.go @@ -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 } diff --git a/graphops/laws_test.go b/graphops/laws_test.go index 23bd806e3..8d0d1909e 100644 --- a/graphops/laws_test.go +++ b/graphops/laws_test.go @@ -682,6 +682,7 @@ func TestValidateTypeURL(t *testing.T) { "https://work.example/", "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) diff --git a/graphops/reader.go b/graphops/reader.go index 5e1f1ad2d..3611dfd9a 100644 --- a/graphops/reader.go +++ b/graphops/reader.go @@ -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) diff --git a/graphops/types.go b/graphops/types.go index ed1d56676..469041321 100644 --- a/graphops/types.go +++ b/graphops/types.go @@ -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 } diff --git a/graphops/types_test.go b/graphops/types_test.go index 855fd8af5..9518333b0 100644 --- a/graphops/types_test.go +++ b/graphops/types_test.go @@ -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) + } +} diff --git a/internal/httpapi/bdpwire/wildcard_pin_test.go b/internal/httpapi/bdpwire/wildcard_pin_test.go new file mode 100644 index 000000000..231c35353 --- /dev/null +++ b/internal/httpapi/bdpwire/wildcard_pin_test.go @@ -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) + } +}