internal

func NewDBPersistentRecordRepository ¶ added in v0.0.23

func NewDBPersistentRecordRepository(pool persistentRecordPool, metadataCache *schemameta.MetadataCache, opts ...RepoOption) *DBPersistentRecordRepository

func WithCloser ¶ added in v0.2.0

func WithCloser(c io.Closer) EntityManagerOption

WithCloser registers a resource the manager owns and must release on Close. Callers pass only non-nil resources; a typed-nil pointer boxed in io.Closer would not compare equal to nil here, so the guard lives at the call site.

func WithRelationIndex ¶ added in v0.2.0

func WithRelationIndex(idx *RelationIndex) EntityManagerOption

WithRelationIndex installs a relation index the caller has already built and validated, instead of letting the manager load its own.

It exists because the composition root has to check relation declarations before it builds anything, and a second, independent load afterwards is not guaranteed to see what the first one saw: forma.SchemaRegistry may serve documents from a database or over a network, so it can change or fail between the two reads. When it does, the manager's own load is the one that fails, and the caller is left holding a construction error over declarations its preflight had already approved. Handing the validated instance forward removes the second read entirely (#318 review).

A nil index is ignored rather than installed, so the option cannot become a way to switch stripping off by accident; the manager then self-loads as any direct constructor does. That self-load fails closed — NewEntityManager returns the error rather than warning and continuing with no index (#388) — so the option changes which read decides, never whether stripping happens.

func LoadRelationIndex ¶ added in v0.0.18

func LoadRelationIndex(registry forma.SchemaRegistry) (*RelationIndex, error)

LoadRelationIndex builds a relation index from the schema documents the registry serves, one per name in registry.ListSchemas(), and fails closed on a relation declaration the runtime cannot honour.

Building and validating are one call because they are one walk: the guard's question — does this schema require a property the strip removes? — can only be asked of the descriptors the walk has just built. There is no separate validate-only entry point, and a caller that wants the check runs this and keeps the index (see WithRelationIndex for why keeping it matters).

The registry, not SCHEMA_DIR, is the source, and that is the point: the runtime validator is built from the same pair of accessors (schemavalidate.New), so neither is reading a document the other cannot see. forma.SchemaRegistry is a public extension point whose implementations may load from files, a database, or anything else, and only what it registers is ever validated or written to.

Same accessors is not the same as same bytes, and the difference is why the factory builds this index exactly once and hands it to NewEntityManager (WithRelationIndex). A registry is free to answer differently on a later call — it may be reading a database — so two independent loads can disagree, and the losing one would be the manager's, silently disabling stripping after a successful preflight. What this function guarantees is that one *load* sees a consistent view; keeping the validator and the manager on that same load is the caller's job.

A failure here reaches every construction site, because NewEntityManager returns it rather than continuing with no index (#388, #318). It has to: one offending schema fails the whole registry load, and a manager over a nil index strips nothing for any schema, not just the offender. What NewEntityManager still cannot enforce is that its load and the caller's preflight are the same load — that is what WithRelationIndex is for. Both shipped construction sites (the factory and the production e2e harness) therefore call this at a position where returning an error aborts startup, and pass the result forward.

What aborts startup, exactly:

• a schema that declares a relation root the analysed fragment shows is required on every document — the root's own "required", or one in an allOf chain (see collectUnconditionalRootRequired for the fragment and why it is that small);
• a schema the registry lists but cannot then serve, or whose document does not decode into any (see loadSchemaRelations for the decode).

Nothing is refused for being unanalysable. Outside the fragment the walk has no opinion, and a schema is booted whether or not it composes its root object out of "not", "anyOf", "oneOf", "if"/"then"/"else", the dependent* family or a root "$ref". Some of those really do demand a stripped relation root, and those writes fail at runtime with an operator-facing explanation attached (explainStrippedRelationRoots) rather than at startup.

The second cause is fatal rather than skipped because every name walked here came from ListSchemas: it names a schema the runtime resolves, validates writes against, and strips relation subtrees for. A document that cannot be read at all is therefore a fault in the registry itself, not a stray file left beside the ones that matter.

The boundary is the decode into any, stated exactly that way because the two looser descriptions of it are both wrong. It is not JSON *shape*: a document that decodes but is not an object is accepted, since it declares no properties and so has no relation roots, and drawing the line there made booleans fatal — a boolean is a legal JSON Schema. Nor is it JSON *syntax*, which is narrower than what actually fails:

{"properties":{"a":{"type":"string"},"b":{"const":1e999}}}

is well-formed JSON — json.Valid answers true, and RFC 8259 puts no bound on a number's magnitude — yet decoding it into any fails with "cannot unmarshal number 1e999 into Go value of type float64". So the fatal class is syntax errors *plus* numbers outside float64's range.

Observation, not justification: schemavalidate.New rejects every document this cause is fatal on, and both shipped call sites run it first, so in the shipped ordering the cause is unreachable. Measured for both halves, and it holds for the whole class rather than for the cases someone thought to try:

• Syntax errors are target-independent. json.Unmarshal runs checkValid over the whole input before decoding anything (encoding/json/decode.go), so a malformed document fails unmarshalling into any target type.
• Overflow is caught because jsonschema.Schema decodes the same bytes the same way this loader does. Schema.UnmarshalJSON tries a bool first (schema.go:379, which is why booleans are legal schemas) and otherwise calls unmarshalStructWithMap, which decodes the document twice: into its own struct, and into a map[string]any (util.go:367 and :372). A JSON object therefore passes every value through the same any decode this loader performs, so a value that fails here fails there — in the struct pass for a keyword the library models ("properties", "enum"), in the map pass for one it does not ("x-junk"). A document that is neither an object nor a boolean is rejected outright by the struct pass, which is why "[1,2,3]" and "\"x\"" are refused by the validator even though this loader accepts them.

The relationship is one-directional and deliberately so: this loader's fatal class is a strict subset of what schemavalidate.New refuses. The reason to refuse remains that the schema is registered.

A registry that lists no schemas, and a nil registry, both yield an empty index and no error.

func WithPlanCache ¶ added in v0.2.0

func WithPlanCache(c *queryplan.Cache) RepoOption

WithPlanCache injects a shared plan cache (#142).

func NewSet ¶

func NewSet[T comparable]() *Set[T]

NewSet creates and returns a new empty Set.