@lovrozagar/oat 0.1.0

package/dist/config/load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/config/load.ts"],"names":[],"mappings":"AAAA;;;;GAIG;;;;;;;;;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAGxC,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC5C,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,CAAA;IAEvE,IAAI,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAc,CAAA;IACjE,CAAC;IAED,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,kCAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAC,CAE7C,CAAA;QACb,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,IAAI,MAAM,CAAA;QACvC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACnD,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAA;QACvD,CAAC;QACD,OAAO,MAAM,CAAA;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACtE,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,oCAAoC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACpF,MAAM,IAAI,KAAK,CACd,oBAAoB,IAAI,0DAA0D;gBACjF,uEAAuE,CACxE,CAAA;QACF,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,KAAK,OAAO,EAAE,CAAC,CAAA;IAClE,CAAC;AACF,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,WAAW,CAAI,KAAQ,EAAE,MAAyB,OAAO,CAAC,GAAG;IAC5E,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,sBAAsB,EAAE,CAAC,KAAK,EAAE,IAAY,EAAE,EAAE;YACpE,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,CAAC,CAAA;YAC1B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,wCAAwC,CAAC,CAAA;YAC3F,CAAC;YACD,OAAO,QAAQ,CAAA;QAChB,CAAC,CAAM,CAAA;IACR,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,CAAM,CAAA;IACjF,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACjD,MAAM,GAAG,GAA4B,EAAE,CAAA;QACvC,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;YAC5E,GAAG,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;QAClC,CAAC;QACD,OAAO,GAAQ,CAAA;IAChB,CAAC;IACD,OAAO,KAAK,CAAA;AACb,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { defineConfig } from "./config/define-config.ts";
+export type { AuthFlow, AuthStep, Hooks, OatConfig, OperationStep, OutOfBandRequest, OutOfBandStep, Principal, RequestStep, } from "./config/define-config.ts";
+export { loadConfig } from "./config/load.ts";
+export { deriveCollectionShape, deriveIdentity } from "./spec/collection.ts";
+export type { CollectionShape } from "./spec/collection.ts";
+export { buildModel } from "./spec/graph.ts";
+export type { EntityModel, OperationModel, SpecModel } from "./spec/graph.ts";
+export { dereference, loadSpec, normalisePath, parseRouteRef } from "./spec/load.ts";
+export type { OpenApiDocument } from "./spec/types.ts";
+export { run } from "./runtime/run.ts";
+export type { RunOptions, RunResult } from "./runtime/run.ts";
+export type { Actor } from "./runtime/checks.ts";
+export type { Finding, Verdict } from "./runtime/finding.ts";
+export { buildMatrixGraph, matrixViewFromReport, renderMatrixGraph, renderMatrixHtml, } from "./report/matrix.ts";
+export type { EntityMatrix, InvalidateLink, MatrixGraph, MatrixGraphEdge, MatrixGraphNode, } from "./report/matrix.ts";
+export { coverageByCheck, renderConsole, renderJson, renderMarkdown, renderRepros } from "./report/render.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,9 @@
+export { defineConfig } from "./config/define-config.js";
+export { loadConfig } from "./config/load.js";
+export { deriveCollectionShape, deriveIdentity } from "./spec/collection.js";
+export { buildModel } from "./spec/graph.js";
+export { dereference, loadSpec, normalisePath, parseRouteRef } from "./spec/load.js";
+export { run } from "./runtime/run.js";
+export { buildMatrixGraph, matrixViewFromReport, renderMatrixGraph, renderMatrixHtml, } from "./report/matrix.js";
+export { coverageByCheck, renderConsole, renderJson, renderMarkdown, renderRepros } from "./report/render.js";
+//# sourceMappingURL=index.js.map

package/dist/reference/defects.d.ts

@@ -0,0 +1,254 @@
+/**
+ * Defects the reference backend can be told to exhibit.
+ *
+ * Each one is a real bug seen in production APIs, reduced to its smallest form. The conformance
+ * suite switches them on individually and asserts oat reports exactly that defect and nothing
+ * else — which is what turns "oat is smart" into precision and recall numbers.
+ *
+ * Keep the implementations naive and obvious. If the reference backend grows clever it starts
+ * encoding the same assumptions oat does, and the two drift together into agreeing on nonsense.
+ */
+export declare const DEFECTS: {
+    /** Sort has no total order, so keyset paging silently drops and repeats rows. */
+    readonly UNSTABLE_SORT: "sort lacks a tiebreak; page walks drop or duplicate rows";
+    /** Writes land in the item store but the list projection serves a stale snapshot. */
+    readonly STALE_LIST: "list projection does not reflect writes visible on the item route";
+    /** Unrecognised filter fields are dropped instead of rejected. */
+    readonly FILTER_IGNORED: "unknown filter field is silently ignored rather than rejected";
+    /** Cursor pagination and offset pagination disagree about the underlying set. */
+    readonly CURSOR_DRIFT: "cursor pagination yields a different set than offset pagination";
+    /** PATCH behaves as PUT, clearing fields the caller never mentioned. */
+    readonly PATCH_REPLACES: "PATCH clears fields absent from the request body";
+    /** Total count ignores the active filter. */
+    readonly COUNT_IGNORES_FILTER: "count reflects the unfiltered set";
+    /** The tenant predicate is applied to the list query but not to filter matches. */
+    readonly TENANT_LEAK_VIA_FILTER: "filter bypasses the tenant predicate";
+    /**
+     * Denies cross-tenant reads with 403 rather than 404.
+     *
+     * The access decision is correct — the record is not served — but the status distinguishes
+     * "exists, not yours" from "does not exist", which turns the item route into an oracle for
+     * enumerating other tenants' identifiers.
+     */
+    readonly EXISTENCE_LEAK_VIA_STATUS: "cross-tenant denial uses 403, revealing that the record exists";
+    /**
+     * Accepts an Idempotency-Key and creates a second record anyway.
+     *
+     * The failure mode is a retry — a timeout, a proxy replay, a double-click — silently
+     * duplicating a charge or an order. The key is the client's only defence against that, and
+     * whether it is honoured cannot be established without replaying a request.
+     */
+    readonly IDEMPOTENCY_IGNORED: "Idempotency-Key is accepted but replay creates a duplicate record";
+    /**
+     * A write invalidates a route the document says it invalidates — except it does not.
+     *
+     * The parent keeps serving a derived value computed before the child write: a denormalised
+     * counter nobody refreshes, or a cached projection whose key was never busted. The write
+     * succeeds, the child's own listing is correct, and only the *other* route the document named
+     * is wrong — which is why nothing short of following `x-invalidate` finds it.
+     */
+    readonly PARENT_PROJECTION_STALE: "a route named by x-invalidate keeps serving pre-write data";
+    /**
+     * The collection serves a different value for a field than the item route does.
+     *
+     * A denormalised listing, a search index rebuilt on a lag, a cached projection: each read path
+     * is internally consistent and individually plausible, so every per-projection check passes.
+     * Only comparing the paths against each other reveals that a client's view of a record depends
+     * on which route it happened to use.
+     */
+    readonly LIST_DETAIL_DISAGREE: "the collection and the item route serve different values for a field";
+    /**
+     * The filter is applied when it is the only query parameter, and dropped once a sort joins it.
+     *
+     * Models the real failure: adding an ORDER BY changes which index the planner picks, and the
+     * predicate rides on the index that is no longer chosen. Each axis is provably correct on its
+     * own, so a suite that only ever tests one at a time reports the API as clean.
+     */
+    readonly FILTER_DROPPED_WHEN_SORTED: "a filter stops being applied once a sort is also requested";
+    /**
+     * The filter is applied when it is the only query parameter, and dropped once a sparse
+     * fieldset joins it.
+     *
+     * The realistic shape: a query builder that projects first and then cannot (or does not)
+     * apply a predicate to a column it just omitted — or that takes a different code path the
+     * moment `fields=` is present and forgets the WHERE. Each axis is correct alone.
+     */
+    readonly FILTER_DROPPED_WHEN_SELECTED: "a filter stops being applied once a select is also requested";
+    /**
+     * The filter is applied when it is the only query parameter, and dropped once a free-text
+     * search joins it.
+     *
+     * Adding `q` often switches the backend onto a search-index path that does not honour the
+     * structured predicate. Search alone is correct, the filter alone is correct, and together
+     * the filter silently vanishes.
+     */
+    readonly FILTER_DROPPED_WHEN_SEARCHED: "a filter stops being applied once a search is also requested";
+    /**
+     * The filter survives each pair — filter+sort and filter+select — and vanishes only when
+     * both extra axes are present at once.
+     *
+     * A query planner that has a two-axis path and a three-axis path, and only the latter
+     * forgets the WHERE. Every pairwise check passes; the bug is the triple.
+     */
+    readonly FILTER_DROPPED_WHEN_SORTED_AND_SELECTED: "a filter stops being applied once a sort and a select are requested together";
+    /**
+     * The filter survives filter+search and filter+sort, and vanishes only when a search and a
+     * sort are requested together — typically the search-index path that also tries to honour
+     * an ORDER BY and drops the structured predicate to do it.
+     */
+    readonly FILTER_DROPPED_WHEN_SORTED_AND_SEARCHED: "a filter stops being applied once a sort and a search are requested together";
+    /**
+     * The filter survives filter+search and filter+select, and vanishes only when a search and
+     * a sparse fieldset are requested together.
+     */
+    readonly FILTER_DROPPED_WHEN_SEARCHED_AND_SELECTED: "a filter stops being applied once a search and a select are requested together";
+    /**
+     * The page window is computed over the *unfiltered* set, and the filter is applied to whatever
+     * that window happened to contain.
+     *
+     * Page one usually looks right, which is what makes it survive review. The damage shows up
+     * further in: pages come back short, records that match the predicate are never returned at
+     * all, and the total is computed over a different set than the rows. Any code that resolves a
+     * cursor or an offset before applying the predicate has this bug.
+     */
+    readonly FILTER_AFTER_PAGINATION: "paging is applied before filtering, so pages miss matching records";
+    /**
+     * The document declares a field filterable that the backend rejects.
+     *
+     * Not a backend bug — the backend is entitled to refuse a field it never indexed. The document
+     * is what is wrong, and it is wrong in the most expensive way: every client generated from it
+     * offers a filter that 400s at runtime. oat is the only thing positioned to notice, because it
+     * is the only thing that reads the claim and then tries it.
+     */
+    readonly SPEC_OVERCLAIMS_FILTERABLE: "x-query declares a field filterable that the backend rejects";
+    /**
+     * The document declares a field sortable that the backend rejects.
+     *
+     * Same failure as SPEC_OVERCLAIMS_FILTERABLE, one role over: the backend is entitled to refuse
+     * a field it never indexed for ordering, but the document is wrong to promise it can. Every
+     * client generated from this document offers an `order` value that 400s at runtime.
+     */
+    readonly SPEC_OVERCLAIMS_SORTABLE: "x-query declares a field sortable that the backend rejects";
+    /**
+     * `and(a,b)` and `or(a,b)` are compiled with their joiner swapped: a conjunction evaluates as
+     * a disjunction and vice versa.
+     *
+     * A realistic shape for the bug: a query builder that always joins terms with the same
+     * operator regardless of which combinator the expression named, because the grouping was
+     * parsed but never actually consulted when assembling the join. Every single-predicate filter
+     * check still passes — the defect is invisible until two terms are combined.
+     */
+    readonly FILTER_GROUP_COMBINATOR_SWAPPED: "and() and or() combinators inside a filter expression are swapped";
+    /**
+     * The document declares a field selectable that the backend rejects.
+     *
+     * The select analogue of SPEC_OVERCLAIMS_FILTERABLE and SPEC_OVERCLAIMS_SORTABLE: the backend
+     * is entitled to stop projecting a column, but the document is wrong to keep promising it can.
+     */
+    readonly SPEC_OVERCLAIMS_SELECTABLE: "x-query declares a field selectable that the backend rejects";
+    /** Tombstoned records remain in the default listing. */
+    readonly SOFT_DELETE_LEAK: "soft-deleted records still appear in the default list";
+    /** Server-owned fields accept client writes. */
+    readonly IMMUTABLE_WRITABLE: "immutable field accepts a write";
+    /** Sparse fieldsets are accepted and ignored. */
+    readonly SELECT_IGNORED: "select returns every field regardless of what was requested";
+    /** LIKE metacharacters in user input are not escaped. */
+    readonly LIKE_UNESCAPED: "unescaped LIKE metacharacters make a filter match everything";
+    /** Offset arithmetic is wrong by one row per page. */
+    readonly OFF_BY_ONE_PAGE: "page offset is computed one row late";
+    /** Create returns a status the document does not declare. */
+    readonly CREATED_201_AS_200: "create returns 200 where the document declares 201";
+    /** Malformed input crashes instead of being rejected. */
+    readonly ERROR_500_ON_BAD_FILTER: "malformed filter produces 500 instead of 400";
+    /** Deleting an absent record reports success. */
+    readonly DELETE_MISSING_OK: "deleting a nonexistent record returns success instead of 404";
+    /** Reads of another tenant's record succeed. */
+    readonly CROSS_TENANT_READ: "item route serves records belonging to another tenant";
+    /** The page-size parameter is accepted and ignored. */
+    readonly LIMIT_IGNORED: "limit is accepted but does not bound the page size";
+    /** More rows are returned than the documented maximum allows. */
+    readonly LIMIT_EXCEEDS_MAX: "page size exceeds the documented maxLimit";
+    /** The more-pages flag is always false, so callers stop after page one. */
+    readonly HASMORE_ALWAYS_FALSE: "hasMore is false even when further pages exist";
+    /** The sort parameter is accepted and ignored. */
+    readonly ORDER_IGNORED: "order is accepted but does not change the result order";
+    /** The search parameter is accepted and ignored. */
+    readonly SEARCH_IGNORED: "q is accepted but does not filter the result";
+    /** A field is accepted at create and silently discarded. */
+    readonly CREATE_DROPS_FIELD: "create accepts a field and does not persist it";
+    /** An enum field accepts values outside the declared set. */
+    readonly ENUM_NOT_VALIDATED: "enum field accepts a value outside the declared set";
+    /** A string longer than maxLength is stored. */
+    readonly MAXLENGTH_NOT_VALIDATED: "string exceeding maxLength is accepted";
+    /** A create missing a required field succeeds. */
+    readonly REQUIRED_NOT_VALIDATED: "create succeeds with a required field missing";
+    /** A non-JSON content type is accepted on a JSON endpoint. */
+    readonly CONTENT_TYPE_NOT_ENFORCED: "request body is parsed regardless of content type";
+    /** Error bodies do not match the documented error schema. */
+    readonly ERROR_SCHEMA_DRIFT: "error response does not match its documented schema";
+    /** Success bodies carry fields the schema does not declare. */
+    readonly RESPONSE_SCHEMA_DRIFT: "success response carries undeclared fields";
+    /** An equality predicate is parsed and then never applied. */
+    readonly FILTER_EQ_NOT_APPLIED: "eq predicate is accepted but matches every record";
+    /** An empty filtered set is replaced by the unfiltered one. */
+    readonly EMPTY_RESULT_RETURNS_ALL: "a filter matching nothing falls back to returning everything";
+    /** SQL three-valued logic leaking through: NULL rows vanish from a negated predicate. */
+    readonly NEQ_DROPS_NULLS: "neq silently excludes records whose value is null";
+    /** The total is computed by a query that disagrees with the one producing the rows. */
+    readonly COUNT_ALWAYS_ZERO: "count reports zero while the same body returns records";
+    /** Descending order drops the rows an ascending order includes. */
+    readonly SORT_DESC_DROPS_NULLS: "descending sort omits records with a null sort key";
+    /** An operation declares an effect in the document and does not perform it. */
+    readonly EFFECT_NOT_APPLIED: "declared x-effects side effect never happens";
+    /** An async job never leaves its running state. */
+    readonly ASYNC_NEVER_COMPLETES: "async job stays pending forever and never reaches a terminal state";
+    /** The receipt for an async job omits the identifier needed to poll it. */
+    readonly ASYNC_RECEIPT_MISSING_ID: "async receipt omits the job id the document declares";
+    /**
+     * DDL names a physical column differently from every read.
+     *
+     * SQL-store only, and modelled on a real production bug: SQLite resolves an unknown
+     * double-quoted identifier as a *string literal* instead of erroring, so the mismatch
+     * surfaces as every row reporting the column's own name as its value — silent corruption
+     * rather than a loud failure.
+     */
+    readonly COLUMN_NAME_MISMATCH: "physical column name differs from the name every read uses";
+    /**
+     * Numeric columns compared as text, so `amount > 9` misses 10 and ordering reads
+     * 1, 10, 100, 2. Extremely common wherever query values arrive untyped from a URL.
+     */
+    readonly NUMERIC_COMPARED_AS_TEXT: "numeric column is compared and ordered as text";
+    /**
+     * The listing and the cursor lookup disagree about collation, so keyset pagination resolves
+     * a boundary the listing never had — rows are skipped or repeated between pages.
+     */
+    readonly COLLATION_INCONSISTENT: "cursor resolution uses a different collation than the listing";
+    /**
+     * Read-modify-write without locking: the handler reads the row, then writes every column
+     * back. Two concurrent patches to different fields, and the later write reinstates the
+     * earlier field's old value — the classic ORM `save(entity)` lost update.
+     */
+    readonly CONCURRENT_WRITE_LOST: "concurrent writes to different fields lose one of them";
+    /**
+     * A lower-ranked role can read a record that a higher-ranked role in the same tenant cannot.
+     *
+     * The lattice is inverted on the item route only: a viewer is served, a member is denied,
+     * the owner still reads. Isolation and the write path stay intact; the failure is purely
+     * that privilege is not monotonic.
+     */
+    readonly ROLE_MONOTONICITY_BROKEN: "a lower-ranked role can read a record a higher-ranked same-tenant role cannot";
+    /** Accept completes but the invitee still cannot read the shared record. */
+    readonly INVITE_NEVER_GRANTS: "accepting an invite does not grant access to the record";
+    /** Revoke returns success and the invitee can still read. */
+    readonly REVOKE_IGNORED: "revoking an invite does not remove access";
+};
+export type DefectName = keyof typeof DEFECTS;
+export declare class DefectSet {
+    private readonly enabled;
+    constructor(names?: readonly string[]);
+    static fromEnv(value: string | undefined): DefectSet;
+    has(name: DefectName): boolean;
+    list(): DefectName[];
+}
+export declare function isDefectName(value: string): value is DefectName;
+//# sourceMappingURL=defects.d.ts.map

package/dist/reference/defects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defects.d.ts","sourceRoot":"","sources":["../../src/reference/defects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAO,MAAM,OAAO;IACnB,iFAAiF;;IAEjF,qFAAqF;;IAErF,kEAAkE;;IAElE,iFAAiF;;IAEjF,wEAAwE;;IAExE,6CAA6C;;IAE7C,mFAAmF;;IAEnF;;;;;;OAMG;;IAEH;;;;;;OAMG;;IAEH;;;;;;;OAOG;;IAEH;;;;;;;OAOG;;IAEH;;;;;;OAMG;;IAEH;;;;;;;OAOG;;IAEH;;;;;;;OAOG;;IAEH;;;;;;OAMG;;IAGH;;;;OAIG;;IAGH;;;OAGG;;IAGH;;;;;;;;OAQG;;IAEH;;;;;;;OAOG;;IAEH;;;;;;OAMG;;IAEH;;;;;;;;OAQG;;IAEH;;;;;OAKG;;IAEH,wDAAwD;;IAExD,gDAAgD;;IAEhD,iDAAiD;;IAEjD,yDAAyD;;IAEzD,sDAAsD;;IAEtD,6DAA6D;;IAE7D,yDAAyD;;IAEzD,iDAAiD;;IAEjD,gDAAgD;;IAEhD,uDAAuD;;IAEvD,iEAAiE;;IAEjE,2EAA2E;;IAE3E,kDAAkD;;IAElD,oDAAoD;;IAEpD,4DAA4D;;IAE5D,6DAA6D;;IAE7D,gDAAgD;;IAEhD,kDAAkD;;IAElD,8DAA8D;;IAE9D,6DAA6D;;IAE7D,+DAA+D;;IAE/D,8DAA8D;;IAE9D,+DAA+D;;IAE/D,yFAAyF;;IAEzF,uFAAuF;;IAEvF,mEAAmE;;IAEnE,+EAA+E;;IAE/E,mDAAmD;;IAEnD,2EAA2E;;IAE3E;;;;;;;OAOG;;IAEH;;;OAGG;;IAEH;;;OAGG;;IAEH;;;;OAIG;;IAEH;;;;;;OAMG;;IAGH,4EAA4E;;IAE5E,6DAA6D;;CAEpD,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,OAAO,CAAA;AAE7C,qBAAa,SAAS;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAEjC,KAAK,GAAE,SAAS,MAAM,EAAO;IAIzC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAKpD,GAAG,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO;IAI9B,IAAI,IAAI,UAAU,EAAE;CAGpB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D"}

package/dist/reference/defects.js

@@ -0,0 +1,265 @@
+/**
+ * Defects the reference backend can be told to exhibit.
+ *
+ * Each one is a real bug seen in production APIs, reduced to its smallest form. The conformance
+ * suite switches them on individually and asserts oat reports exactly that defect and nothing
+ * else — which is what turns "oat is smart" into precision and recall numbers.
+ *
+ * Keep the implementations naive and obvious. If the reference backend grows clever it starts
+ * encoding the same assumptions oat does, and the two drift together into agreeing on nonsense.
+ */
+export const DEFECTS = {
+    /** Sort has no total order, so keyset paging silently drops and repeats rows. */
+    UNSTABLE_SORT: "sort lacks a tiebreak; page walks drop or duplicate rows",
+    /** Writes land in the item store but the list projection serves a stale snapshot. */
+    STALE_LIST: "list projection does not reflect writes visible on the item route",
+    /** Unrecognised filter fields are dropped instead of rejected. */
+    FILTER_IGNORED: "unknown filter field is silently ignored rather than rejected",
+    /** Cursor pagination and offset pagination disagree about the underlying set. */
+    CURSOR_DRIFT: "cursor pagination yields a different set than offset pagination",
+    /** PATCH behaves as PUT, clearing fields the caller never mentioned. */
+    PATCH_REPLACES: "PATCH clears fields absent from the request body",
+    /** Total count ignores the active filter. */
+    COUNT_IGNORES_FILTER: "count reflects the unfiltered set",
+    /** The tenant predicate is applied to the list query but not to filter matches. */
+    TENANT_LEAK_VIA_FILTER: "filter bypasses the tenant predicate",
+    /**
+     * Denies cross-tenant reads with 403 rather than 404.
+     *
+     * The access decision is correct — the record is not served — but the status distinguishes
+     * "exists, not yours" from "does not exist", which turns the item route into an oracle for
+     * enumerating other tenants' identifiers.
+     */
+    EXISTENCE_LEAK_VIA_STATUS: "cross-tenant denial uses 403, revealing that the record exists",
+    /**
+     * Accepts an Idempotency-Key and creates a second record anyway.
+     *
+     * The failure mode is a retry — a timeout, a proxy replay, a double-click — silently
+     * duplicating a charge or an order. The key is the client's only defence against that, and
+     * whether it is honoured cannot be established without replaying a request.
+     */
+    IDEMPOTENCY_IGNORED: "Idempotency-Key is accepted but replay creates a duplicate record",
+    /**
+     * A write invalidates a route the document says it invalidates — except it does not.
+     *
+     * The parent keeps serving a derived value computed before the child write: a denormalised
+     * counter nobody refreshes, or a cached projection whose key was never busted. The write
+     * succeeds, the child's own listing is correct, and only the *other* route the document named
+     * is wrong — which is why nothing short of following `x-invalidate` finds it.
+     */
+    PARENT_PROJECTION_STALE: "a route named by x-invalidate keeps serving pre-write data",
+    /**
+     * The collection serves a different value for a field than the item route does.
+     *
+     * A denormalised listing, a search index rebuilt on a lag, a cached projection: each read path
+     * is internally consistent and individually plausible, so every per-projection check passes.
+     * Only comparing the paths against each other reveals that a client's view of a record depends
+     * on which route it happened to use.
+     */
+    LIST_DETAIL_DISAGREE: "the collection and the item route serve different values for a field",
+    /**
+     * The filter is applied when it is the only query parameter, and dropped once a sort joins it.
+     *
+     * Models the real failure: adding an ORDER BY changes which index the planner picks, and the
+     * predicate rides on the index that is no longer chosen. Each axis is provably correct on its
+     * own, so a suite that only ever tests one at a time reports the API as clean.
+     */
+    FILTER_DROPPED_WHEN_SORTED: "a filter stops being applied once a sort is also requested",
+    /**
+     * The filter is applied when it is the only query parameter, and dropped once a sparse
+     * fieldset joins it.
+     *
+     * The realistic shape: a query builder that projects first and then cannot (or does not)
+     * apply a predicate to a column it just omitted — or that takes a different code path the
+     * moment `fields=` is present and forgets the WHERE. Each axis is correct alone.
+     */
+    FILTER_DROPPED_WHEN_SELECTED: "a filter stops being applied once a select is also requested",
+    /**
+     * The filter is applied when it is the only query parameter, and dropped once a free-text
+     * search joins it.
+     *
+     * Adding `q` often switches the backend onto a search-index path that does not honour the
+     * structured predicate. Search alone is correct, the filter alone is correct, and together
+     * the filter silently vanishes.
+     */
+    FILTER_DROPPED_WHEN_SEARCHED: "a filter stops being applied once a search is also requested",
+    /**
+     * The filter survives each pair — filter+sort and filter+select — and vanishes only when
+     * both extra axes are present at once.
+     *
+     * A query planner that has a two-axis path and a three-axis path, and only the latter
+     * forgets the WHERE. Every pairwise check passes; the bug is the triple.
+     */
+    FILTER_DROPPED_WHEN_SORTED_AND_SELECTED: "a filter stops being applied once a sort and a select are requested together",
+    /**
+     * The filter survives filter+search and filter+sort, and vanishes only when a search and a
+     * sort are requested together — typically the search-index path that also tries to honour
+     * an ORDER BY and drops the structured predicate to do it.
+     */
+    FILTER_DROPPED_WHEN_SORTED_AND_SEARCHED: "a filter stops being applied once a sort and a search are requested together",
+    /**
+     * The filter survives filter+search and filter+select, and vanishes only when a search and
+     * a sparse fieldset are requested together.
+     */
+    FILTER_DROPPED_WHEN_SEARCHED_AND_SELECTED: "a filter stops being applied once a search and a select are requested together",
+    /**
+     * The page window is computed over the *unfiltered* set, and the filter is applied to whatever
+     * that window happened to contain.
+     *
+     * Page one usually looks right, which is what makes it survive review. The damage shows up
+     * further in: pages come back short, records that match the predicate are never returned at
+     * all, and the total is computed over a different set than the rows. Any code that resolves a
+     * cursor or an offset before applying the predicate has this bug.
+     */
+    FILTER_AFTER_PAGINATION: "paging is applied before filtering, so pages miss matching records",
+    /**
+     * The document declares a field filterable that the backend rejects.
+     *
+     * Not a backend bug — the backend is entitled to refuse a field it never indexed. The document
+     * is what is wrong, and it is wrong in the most expensive way: every client generated from it
+     * offers a filter that 400s at runtime. oat is the only thing positioned to notice, because it
+     * is the only thing that reads the claim and then tries it.
+     */
+    SPEC_OVERCLAIMS_FILTERABLE: "x-query declares a field filterable that the backend rejects",
+    /**
+     * The document declares a field sortable that the backend rejects.
+     *
+     * Same failure as SPEC_OVERCLAIMS_FILTERABLE, one role over: the backend is entitled to refuse
+     * a field it never indexed for ordering, but the document is wrong to promise it can. Every
+     * client generated from this document offers an `order` value that 400s at runtime.
+     */
+    SPEC_OVERCLAIMS_SORTABLE: "x-query declares a field sortable that the backend rejects",
+    /**
+     * `and(a,b)` and `or(a,b)` are compiled with their joiner swapped: a conjunction evaluates as
+     * a disjunction and vice versa.
+     *
+     * A realistic shape for the bug: a query builder that always joins terms with the same
+     * operator regardless of which combinator the expression named, because the grouping was
+     * parsed but never actually consulted when assembling the join. Every single-predicate filter
+     * check still passes — the defect is invisible until two terms are combined.
+     */
+    FILTER_GROUP_COMBINATOR_SWAPPED: "and() and or() combinators inside a filter expression are swapped",
+    /**
+     * The document declares a field selectable that the backend rejects.
+     *
+     * The select analogue of SPEC_OVERCLAIMS_FILTERABLE and SPEC_OVERCLAIMS_SORTABLE: the backend
+     * is entitled to stop projecting a column, but the document is wrong to keep promising it can.
+     */
+    SPEC_OVERCLAIMS_SELECTABLE: "x-query declares a field selectable that the backend rejects",
+    /** Tombstoned records remain in the default listing. */
+    SOFT_DELETE_LEAK: "soft-deleted records still appear in the default list",
+    /** Server-owned fields accept client writes. */
+    IMMUTABLE_WRITABLE: "immutable field accepts a write",
+    /** Sparse fieldsets are accepted and ignored. */
+    SELECT_IGNORED: "select returns every field regardless of what was requested",
+    /** LIKE metacharacters in user input are not escaped. */
+    LIKE_UNESCAPED: "unescaped LIKE metacharacters make a filter match everything",
+    /** Offset arithmetic is wrong by one row per page. */
+    OFF_BY_ONE_PAGE: "page offset is computed one row late",
+    /** Create returns a status the document does not declare. */
+    CREATED_201_AS_200: "create returns 200 where the document declares 201",
+    /** Malformed input crashes instead of being rejected. */
+    ERROR_500_ON_BAD_FILTER: "malformed filter produces 500 instead of 400",
+    /** Deleting an absent record reports success. */
+    DELETE_MISSING_OK: "deleting a nonexistent record returns success instead of 404",
+    /** Reads of another tenant's record succeed. */
+    CROSS_TENANT_READ: "item route serves records belonging to another tenant",
+    /** The page-size parameter is accepted and ignored. */
+    LIMIT_IGNORED: "limit is accepted but does not bound the page size",
+    /** More rows are returned than the documented maximum allows. */
+    LIMIT_EXCEEDS_MAX: "page size exceeds the documented maxLimit",
+    /** The more-pages flag is always false, so callers stop after page one. */
+    HASMORE_ALWAYS_FALSE: "hasMore is false even when further pages exist",
+    /** The sort parameter is accepted and ignored. */
+    ORDER_IGNORED: "order is accepted but does not change the result order",
+    /** The search parameter is accepted and ignored. */
+    SEARCH_IGNORED: "q is accepted but does not filter the result",
+    /** A field is accepted at create and silently discarded. */
+    CREATE_DROPS_FIELD: "create accepts a field and does not persist it",
+    /** An enum field accepts values outside the declared set. */
+    ENUM_NOT_VALIDATED: "enum field accepts a value outside the declared set",
+    /** A string longer than maxLength is stored. */
+    MAXLENGTH_NOT_VALIDATED: "string exceeding maxLength is accepted",
+    /** A create missing a required field succeeds. */
+    REQUIRED_NOT_VALIDATED: "create succeeds with a required field missing",
+    /** A non-JSON content type is accepted on a JSON endpoint. */
+    CONTENT_TYPE_NOT_ENFORCED: "request body is parsed regardless of content type",
+    /** Error bodies do not match the documented error schema. */
+    ERROR_SCHEMA_DRIFT: "error response does not match its documented schema",
+    /** Success bodies carry fields the schema does not declare. */
+    RESPONSE_SCHEMA_DRIFT: "success response carries undeclared fields",
+    /** An equality predicate is parsed and then never applied. */
+    FILTER_EQ_NOT_APPLIED: "eq predicate is accepted but matches every record",
+    /** An empty filtered set is replaced by the unfiltered one. */
+    EMPTY_RESULT_RETURNS_ALL: "a filter matching nothing falls back to returning everything",
+    /** SQL three-valued logic leaking through: NULL rows vanish from a negated predicate. */
+    NEQ_DROPS_NULLS: "neq silently excludes records whose value is null",
+    /** The total is computed by a query that disagrees with the one producing the rows. */
+    COUNT_ALWAYS_ZERO: "count reports zero while the same body returns records",
+    /** Descending order drops the rows an ascending order includes. */
+    SORT_DESC_DROPS_NULLS: "descending sort omits records with a null sort key",
+    /** An operation declares an effect in the document and does not perform it. */
+    EFFECT_NOT_APPLIED: "declared x-effects side effect never happens",
+    /** An async job never leaves its running state. */
+    ASYNC_NEVER_COMPLETES: "async job stays pending forever and never reaches a terminal state",
+    /** The receipt for an async job omits the identifier needed to poll it. */
+    ASYNC_RECEIPT_MISSING_ID: "async receipt omits the job id the document declares",
+    /**
+     * DDL names a physical column differently from every read.
+     *
+     * SQL-store only, and modelled on a real production bug: SQLite resolves an unknown
+     * double-quoted identifier as a *string literal* instead of erroring, so the mismatch
+     * surfaces as every row reporting the column's own name as its value — silent corruption
+     * rather than a loud failure.
+     */
+    COLUMN_NAME_MISMATCH: "physical column name differs from the name every read uses",
+    /**
+     * Numeric columns compared as text, so `amount > 9` misses 10 and ordering reads
+     * 1, 10, 100, 2. Extremely common wherever query values arrive untyped from a URL.
+     */
+    NUMERIC_COMPARED_AS_TEXT: "numeric column is compared and ordered as text",
+    /**
+     * The listing and the cursor lookup disagree about collation, so keyset pagination resolves
+     * a boundary the listing never had — rows are skipped or repeated between pages.
+     */
+    COLLATION_INCONSISTENT: "cursor resolution uses a different collation than the listing",
+    /**
+     * Read-modify-write without locking: the handler reads the row, then writes every column
+     * back. Two concurrent patches to different fields, and the later write reinstates the
+     * earlier field's old value — the classic ORM `save(entity)` lost update.
+     */
+    CONCURRENT_WRITE_LOST: "concurrent writes to different fields lose one of them",
+    /**
+     * A lower-ranked role can read a record that a higher-ranked role in the same tenant cannot.
+     *
+     * The lattice is inverted on the item route only: a viewer is served, a member is denied,
+     * the owner still reads. Isolation and the write path stay intact; the failure is purely
+     * that privilege is not monotonic.
+     */
+    ROLE_MONOTONICITY_BROKEN: "a lower-ranked role can read a record a higher-ranked same-tenant role cannot",
+    /** Accept completes but the invitee still cannot read the shared record. */
+    INVITE_NEVER_GRANTS: "accepting an invite does not grant access to the record",
+    /** Revoke returns success and the invitee can still read. */
+    REVOKE_IGNORED: "revoking an invite does not remove access",
+};
+export class DefectSet {
+    enabled;
+    constructor(names = []) {
+        this.enabled = new Set(names);
+    }
+    static fromEnv(value) {
+        if (value === undefined || value.trim() === "")
+            return new DefectSet();
+        return new DefectSet(value.split(",").map((s) => s.trim()).filter(Boolean));
+    }
+    has(name) {
+        return this.enabled.has(name);
+    }
+    list() {
+        return [...this.enabled];
+    }
+}
+export function isDefectName(value) {
+    return Object.hasOwn(DEFECTS, value);
+}
+//# sourceMappingURL=defects.js.map

package/dist/reference/defects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defects.js","sourceRoot":"","sources":["../../src/reference/defects.ts"],"names":[],"mappings":"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"}