storetest

func FuzzAttachmentKeyCollision ¶

func FuzzAttachmentKeyCollision(f *testing.F, factory FuzzFactory)

FuzzAttachmentKeyCollision verifies that attachment key construction rejects invalid property names and round-trips valid ones.

func FuzzCloneNestedValues ¶

func FuzzCloneNestedValues(f *testing.F, factory FuzzFactory)

FuzzCloneNestedValues verifies deep clone semantics for nested property values.

func FuzzConcurrentOps ¶

func FuzzConcurrentOps(f *testing.F, factory FuzzFactory)

FuzzConcurrentOps verifies the store is safe under concurrent access.

func FuzzPropertyValuesTypeZoo ¶

func FuzzPropertyValuesTypeZoo(f *testing.F, factory FuzzFactory)

FuzzPropertyValuesTypeZoo verifies that every accepted property value, of any type, reads back equal to what was written. The name predates the removal of PropertyValues (TKT-KQXVF7); it is kept so the backends' fuzz corpora keep their directories.

The round-trip half applies the same directional oracle as createEntityOrSkip: anything storeutil.ValidateProperties rejects, the store MUST reject; anything it accepts MUST come back byte-for-byte. It exists because both halves have failed silently before. BUG-B1RA3J: a value fsstore wrote as a block scalar that read back as "" with no error. BUG-X7ICNM: invalid UTF-8 that pgstore "stored" as U+FFFD and reported success. A target that only checked for an absent error passed over both.

func FuzzRelationKeyCollision ¶

func FuzzRelationKeyCollision(f *testing.F, factory FuzzFactory)

FuzzRelationKeyCollision verifies that relation key construction never causes collisions or round-trip failures.

func FuzzRenameKeyCollapse ¶

func FuzzRenameKeyCollapse(f *testing.F, factory FuzzFactory)

FuzzRenameKeyCollapse verifies rename never loses relations.

func RunAddressTests ¶

func RunAddressTests(t *testing.T, f Factory)

RunAddressTests pins how every backend answers an entity.Ref (TKT-KQXVF7). A row is addressed by (id, face). A ref that names no row is ErrNotFound, whether the row is absent or the ref is malformed: a malformed face can never be declared, so it names nothing, and a backend must not map it onto some other row, a path, or a SQL error.

func RunAll ¶

func RunAll(t *testing.T, f Factory, sf SearchFactory, vsf VisibleSearchFactory, caps Capabilities)

RunAll runs the full conformance suite. The optional SearchFactory is used for search tests; if nil, search tests are skipped. The optional VisibleSearchFactory is used for ACL-scoped search tests; if nil, they are skipped. Capabilities gates optional feature tests (e.g. attachments).

func RunAttachmentTests ¶

func RunAttachmentTests(t *testing.T, f Factory)

RunAttachmentTests runs attachment conformance tests.

func RunBulkMigrateTests ¶

func RunBulkMigrateTests(t *testing.T, f Factory)

RunBulkMigrateTests is the conformance suite for bulk migration rewrites (TKT-HH7PKJ).

Every backend must pass these, whether it implements store.BulkMigrator natively (pgstore and sqlitestore rewrite the table in one statement) or is served by the generic fallback. store.SwapRelationEndpoints picks the path and the OBSERVABLE contract is identical either way — that equivalence is the whole point of the seam, and the reason this suite is not gated on a capability flag.

Keeping both paths under ONE contract is deliberate. A native fast path and a hand-written loop are exactly the pair that drifts: BUG-TMGWIN happened because detection and remediation were maintained as two lists, each looking complete alone.

func RunCASTests ¶

func RunCASTests(t *testing.T, f Factory)

RunCASTests runs the compare-and-swap conformance suite for store.EntityWriter.UpdateEntityIf (TKT-34XS2R).

This is part of RunAll rather than an opt-in section, deliberately. CAS is the primitive callers reach for INSTEAD of a process-local mutex, so a backend that accepts a stale expected-version is not merely missing a feature — it silently returns success for a write that lost a race, which is the exact failure the caller adopted CAS to avoid. There is no "degrade gracefully" story here, so there is no capability flag.

func RunEndpointMatchTests ¶

func RunEndpointMatchTests(t *testing.T, f Factory)

RunEndpointMatchTests is the conformance suite for store.RelationPredicate.EndpointMatch — filtering the candidate set by the TYPE and PROPERTIES of the entity on the far side of a relation, rather than by endpoint id (TKT-RELTRV).

The scenarios that matter to a backend author, beyond the happy path:

• a dangling edge (endpoint row absent) is NOT a match, so a pushed-down JOIN and a Go-side lookup agree
• EndpointMatch composes with Endpoints as a CONJUNCTION, not a widening
• Negate inverts the whole predicate including the endpoint filter
• a chained hop resolves against the endpoint, not the original candidate

Run via RunAll.

func RunEntityTests ¶

func RunEntityTests(t *testing.T, f Factory)

RunEntityTests runs entity CRUD conformance tests.

func RunFaceSelectionTests ¶

func RunFaceSelectionTests(t *testing.T, f Factory)

RunFaceSelectionTests is the face-selection conformance suite (TKT-KQXVF7): the zero selection is refused by every read, AtFaces is a set (empty matches nothing), AllFaces pages resume inside a family, FaceIn composes with every mode, and an endpoint match reads its endpoint at its own selection or the query's (design A6).

The seed is one faced type with every family shape: all three faces (DOC-1), a named face only (DOC-2) and the default face only (DOC-3), plus an unfaced type whose identity edges point at them.

func RunFacedVisibleSearchTests ¶

func RunFacedVisibleSearchTests(t *testing.T, vsf VisibleSearchFactory)

RunFacedVisibleSearchTests pins the per-face half of the scope (TKT-7IZHP0): the verdict and the face allowlist trim each entity's candidate faces BEFORE the world ranks them. A denied prime falls through to a readable face, as on lists and the single-entity read, and a face the scope denies is never matched or served.

The world prefers draft and falls back to published. POL-1 holds both faces, POL-2 only a draft, and the term "sketch" appears only in POL-1's draft.

func RunFamilyReplaceTests ¶

func RunFamilyReplaceTests(t *testing.T, f Factory, caps Capabilities)

RunFamilyReplaceTests pins store.FamilyReplacer: one validation rule set for every backend, a face swap that never trips the family key, and a delete event for every coordinate the conversion empties.

func RunFamilyTests ¶

func RunFamilyTests(t *testing.T, f Factory)

RunFamilyTests pins the family operations: DeleteFamily, DeleteFace and RenameFamily on a family stored only at named faces.

func RunFieldScopeSearchTests ¶

func RunFieldScopeSearchTests(t *testing.T, vsf VisibleSearchFactory)

RunFieldScopeSearchTests pins search.TypeScope.Fields, the closure of the match-on-hidden-field oracle: a hit whose text matched ONLY properties the reader may not see is dropped, while a hit that matched a visible property, an ungated property, the id or the content survives. The limit counts the surviving hits.

The fixture's `code` value ("zeta777") appears in no title, so a search for it can only match through that property.

func RunFreshnessTests ¶

func RunFreshnessTests(t *testing.T, f Factory)

RunFreshnessTests exercises store.Freshness, the mandatory member of store.Store that had no conformance coverage at all until TKT-8TJ2WN.

It is worth pinning because the three shipped implementations are genuinely different — fsstore takes the max of four filesystem mtimes, memstore scans two maps, pgstore runs SQL max() over a UNION ALL — and because a wrong answer degrades silently: appbuild compares this against the search index's stored timestamp to decide whether to rebuild, so a store that under-reports serves stale search results with no error anywhere.

The assertions are deliberately coarse (monotonicity and coverage, not exact values). A store whose timestamps come from the filesystem or the database clock cannot promise more than that, and demanding equality with a test-observed wall clock would fail those backends for no benefit.

func RunGraphDifferential ¶

func RunGraphDifferential(t *testing.T, f Factory)

RunGraphDifferential compares a backend's native graph queries with graphquerynaive, the behavioral reference, on ONE seeded store. The seed mixes every value shape a property can hold (strings, the empty string, JSON null, absent keys, lists, the empty list, integers, booleans, a real), awkward property names, faces, state-tailed edges, inheritance chains with a cycle, and dangling-free endpoints; the queries are generated from fixed seeds so a failure reproduces.

The reference runs graphquerynaive over a memstore seeded identically, not over the store under test: graphquerynaive reads through ListEntities, and a SQL backend's ListEntities shares its world ranking with its graph queries, so a ranking defect would otherwise agree with itself. A backend that delegates to graphquerynaive exercises only its ListEntities here.

Property names a SQL backend cannot render send the whole query to its naive fallback, so the generator uses one rarely: most queries must take the SQL path to test anything.

Two answers are deliberately NOT compared, because they are documented divergences rather than defects: the GraphCount total under a world with Any (BUG-OQQE8D), and sort keys over list or real values, which Go and SQL render differently (the generator never orders by those properties).

func RunGraphHeaderTests ¶

func RunGraphHeaderTests(t *testing.T, f Factory)

RunGraphHeaderTests pins the content-free projection of GraphQuery (TKT-1U8XYN): for a type-plus-property query and a relation-predicate query, store.GraphQueryHeaders yields exactly HeaderOf(row) for every row GraphQuery yields, in the same order — whether the backend implements store.GraphHeaderQueryer natively or through the generic fallback.

func RunGraphPagingTests ¶

func RunGraphPagingTests(t *testing.T, f Factory)

RunGraphPagingTests pins GraphQuery.OrderBy/Limit/Offset (TKT-1U8XYN): byte-wise ordering on the property's string form, a row without the property sorting as the largest value, id as tiebreak; a Limit/Offset window equal to slicing the full ordered result; GraphCount unaffected by paging; headers paging identically.

func RunGraphPositionTests ¶

func RunGraphPositionTests(t *testing.T, f Factory)

RunGraphPositionTests pins store.GraphPosition to the one definition it can have: for every matched id, the position equals what the ordered GraphQuery result says (TKT-U9DYW4). Stating it as a differential rather than as expected literals is the point — a backend answers a position natively (pgstore, one window-function statement) precisely where it also orders natively, and the two must not drift.

func RunGraphQueryTests ¶

func RunGraphQueryTests(t *testing.T, f Factory)

RunGraphQueryTests is the conformance suite for store.GraphQueryer. Pins the contract every backend implementation must honor — regardless of whether it delegates to graphquerynaive or pushes the query into the underlying engine. New implementations get the same expectations for free.

Each subtest seeds a small graph, runs a GraphQuery, and asserts on the (id-sorted) result set. The scenarios cover:

• direct inbound match (no transitive expansion)
• direct outbound match
• InheritThrough endpoint-side expansion (groups-shaped)
• EntityInheritThrough entity-side expansion (containment-shaped)
• both expansions composed
• OfTypes filter
• cycle / self-loop termination
• depth-cap truncation
• GraphCount returning (matched, total)

Run via RunAll alongside the other conformance suites.

func RunHeaderTests ¶

func RunHeaderTests(t *testing.T, f Factory)

RunHeaderTests runs conformance tests for content-free header listing (TKT-1ESTYJ).

Every backend must pass these, whether it implements store.HeaderReader natively or is served by the generic fallback: store.ListEntityHeaders picks the path, and the OBSERVABLE contract is identical either way. That equivalence is the point — a caller must never have to know which it got.

func RunIteratorNestingTests ¶

func RunIteratorNestingTests(t *testing.T, f Factory, vsf VisibleSearchFactory)

RunIteratorNestingTests pins that a caller may make store calls inside the body of any store iteration (BUG-9TGOH1). Visibility redaction does exactly that for every row. A backend that holds a pooled connection across yield needs a second connection per concurrent iteration, and deadlocks once the iterations outnumber the pool. On a Tx view, the same backend would issue the nested statement on a connection whose result is still being read.

vsf may be nil; the visible-search cases are then skipped.

func RunMatchingFacesTests ¶

func RunMatchingFacesTests(t *testing.T, f Factory)

RunMatchingFacesTests pins store.GraphQueryer.MatchingFaces, the per-face row verdict the ACL read gate runs (acl.Request.ReadableFacesMany). The gate asks it under AllFaces with the grant's face allowlist, so a backend that answered per id instead of per face row, or dropped a branch's face set, would widen or narrow every bare-id read at once.

func RunMentionRollbackTests ¶

func RunMentionRollbackTests(t *testing.T, f Factory)

RunMentionRollbackTests pins that a rolled-back write leaves no index entry. Run by backends with the strong Tx contract (see Capabilities.TxRollback).

func RunMentionTests ¶

func RunMentionTests(t *testing.T, f Factory)

RunMentionTests is the conformance suite for store.MentionIndex (TKT-Q6AKUN). Every in-tree backend implements the capability, so a store that does not is a failure, not a skip.

func RunObserverTests ¶

func RunObserverTests(t *testing.T, f ObserverFactory)

RunObserverTests pins the observer contract every backend must honor (store.EntityObserver + store.FaceObserver). It lives HERE, not in each backend's own tests, because the contract once drifted exactly that way: memstore and fsstore pinned per-face announcements while pgstore pinned the pre-worlds skip, and each backend's tests were green.

func RunPaginationTests ¶

func RunPaginationTests(t *testing.T, f Factory)

RunPaginationTests runs conformance tests for ListEntitiesPage and ListRelationsPage. These verify the cursor contract, limit semantics, and the interaction with query filters — properties the dataentry handlers (and any other paginating caller) depend on.

func RunQueryTests ¶

func RunQueryTests(t *testing.T, f Factory)

RunQueryTests runs entity query conformance tests.

func RunRelatedTests ¶

func RunRelatedTests(t *testing.T, f Factory)

RunRelatedTests is the conformance suite for store.GraphQuery.Related, the caller-supplied conjunction of directed relation predicates (TKT-XKCNCL).

The scenarios that matter to a backend author:

• Incoming reads the entity's incoming edges and false its outgoing ones, exactly as HasInbound and HasOutbound do
• entries are ANDed with each other and with HasInbound: an entry never replaces or widens the slot the ACL read gate occupies
• Negate, paging and the scoped count honor every entry
• the EndpointMatch shape bound applies to entries too

Run via RunAll.

func RunRelationTests ¶

func RunRelationTests(t *testing.T, f Factory)

RunRelationTests runs relation CRUD conformance tests.

func RunSearchTests ¶

func RunSearchTests(t *testing.T, sf SearchFactory)

RunSearchTests runs search and filter conformance tests.

func RunSoftDeleteTests ¶

func RunSoftDeleteTests(t *testing.T, f Factory, sf SearchFactory, attachments bool)

RunSoftDeleteTests is the conformance suite for store.SoftDeleter. It is the proof that a marked entity is hidden from every read path, since a read method that forgets the mark shows a deleted entity with no error. sf is optional; with it, the search index is checked too.

func RunStateTests ¶

func RunStateTests(t *testing.T, f Factory)

RunStateTests is the content-states conformance suite (TKT-DOFYR1): addressing by (id, face), the write-path row-family invariants, default-vs-AllFaces query semantics, relation tail faces in both match implementations, and the delete/rename cascades over a state family. These cases define the contract BEFORE the second backend implements — they are what keep storeutil.MatchRelation and pgstore's relationWhere from drifting.

func RunSweepAttributionTests ¶

func RunSweepAttributionTests(t *testing.T, f Factory, sweepNow func(t *testing.T, s store.Store))

RunSweepAttributionTests pins who a swept create/update version is attributed to. RunVersionTests drives capture through the synchronous writer and so cannot see this; the sweep is the only path that records creates and updates, so the attribution it stamps is what history shows for almost every edit.

The contract (TKT-ZIRMGM): a write carrying a store.Attribution is credited to that editor, and a write without one is credited to the version-sweep system principal, never to a guessed or stale identity.

sweepNow must run one tick that treats every row as settled.

func RunSweepBacklogTests ¶

func RunSweepBacklogTests(t *testing.T, f Factory, sweepNow func(t *testing.T, s store.Store))

RunSweepBacklogTests pins that the sweep captures every change when more rows are settled than one tick processes (BUG-1DWMYO).

The sweep dedups in Go, after its candidate query. A row the query selects and the dedup skips is selected again on every tick, so once a batch of them exists the rows behind them are never reached: not slowly, never. The cases below are the ways such rows arose: settled rows that were already captured, numbers whose stored form differs from their hashed form, and rows saved unchanged after a force-live purge.

sweepNow must run one tick that treats every row as settled, with a batch smaller than sweepBacklogRows.

func RunSweepOriginTests ¶

func RunSweepOriginTests(t *testing.T, f Factory, sweepNow func(t *testing.T, s store.Store))

RunSweepOriginTests pins the provenance a swept create/update version carries. The sweep captures from the live row, so a backend must keep the write's store.Origin on the row for the version to name it (BUG-YC5Z07).

sweepNow must run one tick that treats every row as settled.

func RunTxAbnormalExitTests ¶

func RunTxAbnormalExitTests(t *testing.T, f Factory)

TxDurabilityFactory builds a store for the abnormal-exit cases below. It is separate from Factory because these cases need a store that OUTLIVES the transaction under test — a factory that registers t.Cleanup teardown is fine, but the store must still be usable after fn has panicked.

The cases exist because RunTxRollbackTests only ever returns an ERROR from fn. A backend can pass it while leaving the store permanently unusable after a panic or a cancelled commit, which is exactly what happened to sqlitestore: abandoning an open transaction on a pooled connection poisoned every subsequent transaction AND made the uncommitted write durable. The suite could not see it, so the bug shipped to review.

func RunTxObserverIsolationTests ¶

func RunTxObserverIsolationTests(t *testing.T, newStore func(t *testing.T, o store.EntityObserver) store.Store)

RunTxObserverIsolationTests asserts observers do not witness rolled-back writes.

Separate from RunTxRollbackTests because it needs a store with an observer attached, which Factory cannot express. Worth its own entry point: observers are how derived state (search indexes) stays correct, so an observer firing for a write that never committed leaves the index holding a phantom entity — and nothing self-heals until a full reindex.

func RunTxRollbackTests ¶

func RunTxRollbackTests(t *testing.T, f Factory)

RunTxRollbackTests exercises the stronger Tx guarantees of backends with real rollback (pgstore): an error from fn discards the transaction's writes, delivers no events, and post-commit delivery works. fsstore/memstore deliberately do NOT meet these (DEC-8UIL0 reduced single-user guarantees) and must not run this suite.

func RunTxStressTest ¶

func RunTxStressTest(t *testing.T, f Factory)

RunTxStressTest soaks a store under sustained mixed concurrent load — Tx read-modify-write counters, multi-write transactions with injected failures, nested transactions, plain writes, reads, and a draining subscriber — with a progress watchdog that converts a deadlock into a failing test with a full goroutine dump (Go's runtime deadlock panic only fires when ALL goroutines block, which a partial deadlock never triggers).

End-state invariants, valid for every backend regardless of rollback support:

• No lost updates: the counter equals the number of Tx increments that returned success.
• Pair atomicity: each two-entity transaction either left both entities or neither (the failure is injected only after both writes, so this holds under rollback AND under the fs/mem no-rollback contract).

Duration: 2s default; set RELA_STRESS_SECONDS for longer local runs.

func RunTxTests ¶

func RunTxTests(t *testing.T, f Factory)

RunTxTests exercises the store.Transactor contract every backend must meet: serialization, view re-entrancy, read-your-writes, error propagation, and nested-Tx joining. Rollback and post-commit event delivery are backend-dependent — see RunTxRollbackTests.

func RunValidationTests ¶

func RunValidationTests(t *testing.T, f Factory)

RunValidationTests runs input validation conformance tests.

func RunVersionTagTests ¶

func RunVersionTagTests(t *testing.T, f Factory, sweepNow func(t *testing.T, s store.Store))

RunVersionTagTests pins the store.VersionTagger contract (TKT-VO6VG9): capture-now, moving and removing a tag, which lifecycle a tag belongs to across rename, delete and re-creation, per-face scope, the purge refusal, the compare-and-set precondition, the in-transaction refusal and concurrent moves.

sweepNow must run one sweep tick that treats every row as settled. Deletes and renames are captured synchronously above the store, so the suite writes those version rows itself, as entitymanager would.

func RunVersionTests ¶

func RunVersionTests(t *testing.T, f Factory)

RunVersionTests is the conformance suite for content versioning — the optional capability bundle a backend advertises via store.VersionService.

Why this lives here rather than beside an implementation ¶

pgstore had versioning to itself for a long time, and its guarantees were pinned only by tests inside pgstore. That is fine for one implementation and actively misleading for two: the second backend's tests describe whatever it happens to do, the first backend's describe whatever IT happens to do, and nothing anywhere states what a caller may RELY on. The consumers (internal/dataentry's history handlers) type-assert the interface and cannot see which backend answered, so the contract has to be the thing under test.

Extracted when sqlitestore became the second implementation (TKT-4NU9ZD), following the precedent set by Capabilities.TxRollback in TKT-8TJ2WN: the backend DECLARES the tier and the suite runs, so a backend that has the capability and forgets to say so gets no silent pass.

What this deliberately does not test ¶

Sweep cadence and debounce windows are mechanism, not contract — a backend may capture create/update rows on any schedule, or (like fsstore) not at all. The suite therefore drives capture through the SYNCHRONOUS writer, which every versioning backend must implement, and asserts on what history READS back.

func RunVisibleSearchTests ¶

func RunVisibleSearchTests(t *testing.T, vsf VisibleSearchFactory)

RunVisibleSearchTests is the conformance suite for search.VisibleSearcher. Any implementation — the generic scope-filter wrapper or a backend-native one — must pass it (TKT-BA8BSX).

Every case asserts two invariants on top of its specific expectation:

• no-leak: every yielded hit is in the case's allowed set;
• ordered-subsequence: the visible stream equals the ungated stream of the same backend with disallowed hits deleted, order preserved.

Fixture corpora stay far below every backend's candidate bound, so truncation never confounds the subsequence check; the post-visibility limit contract is pinned separately (LimitPostVisibility).

func RunWatcherTests ¶

func RunWatcherTests(t *testing.T, f Factory)

RunWatcherTests runs event subscription conformance tests.

func RunWorldTests ¶

func RunWorldTests(t *testing.T, f Factory)

RunWorldTests is the world-resolution conformance suite (TKT-WAV8XP): the three resolution rules, chain order, the at-most-one-prime invariant, exclude-vs-default fallback, and the zero-value default-world fast path. The other selection modes are RunFaceSelectionTests.

These cases define the contract BEFORE the second backend implements it. fs/mem resolve in shared Go (storeutil); pgstore resolves in SQL in PR-C — this suite is what stops the two from drifting, exactly as RunStateTests does for content states.

Gated by Capabilities.Worlds for one commit window; see that field.