@lovrozagar/oat 0.2.2 → 0.3.0

package/README.md

@@ -736,6 +736,14 @@ Default cohort is **7** records, one of each variant, sliced by `cohortSize`:
 
 Numbers use the ladder `1, 2, 5, 10, 20, 50, 100` so **lexical order ≠ numeric order** (otherwise a TEXT compare looks correct). Enums walk `index % enum.length`. `readOnly` / `x-generated` fields are omitted. Required fields that cannot be generated get a type fallback (`0`, `false`, `[]`, `{}`, `"value"`). Arrays honour `minItems` (never send `[]` when `minItems ≥ 1`). Nested objects stop at depth 4.
 
+Empty schemas (`{}`, `true`, `additionalProperties: {}`) and cyclic `$ref`s after inlining stop the walk — they become a scalar or `{}`, never another object descent. A `RangeError` during generation is a `COVERAGE_GAP` on that entity naming the operationId and JSON pointer (`fixture generation overflow on table.create (/)`), not `blocked by unknown`.
+
+String fields honour `format` and `pattern`: `email` → `oat-{variant}-{index}@example.test`, `uri` / `url` → `https://example.test/...`, `uuid` → a fixed-shape UUID, `pattern` → a string that matches (or the field is omitted / the entity is a gap). `"Quarterly Report N"` is only used when the document does not constrain the string.
+
+An operation with `x-invite` is not `entity.create`. oat does not POST a generated invitee. The invite check sends `granteeField` = the peer's `inviteAs`. Missing `inviteAs` is a coverage gap naming the tag.
+
+A create whose `operationId` appears in any principal `auth.steps`, or that declares `x-fresh-principal`, is not seeded. Those rows were provisioned by the auth flow.
+
 Parent path parameters are created first (depth-first through the owning entity's create). Config / principal `roots` fill parameters oat cannot create.
 
 A create that returns `>= 300` on the first variant fails the entity (downstream checks `BLOCKED`). Later variants that fail just shorten the cohort — a partial cohort is still used.
@@ -892,6 +900,8 @@ x-invite:
 
 Put this on the invite operation. Config must give the invitee `inviteAs`. Defaults if omitted: `granteeField: key`, `tokenPointer: $.token`, `grantPointer: $.grant_id`. All three of `invite` / `accept` / `revoke` (operationIds) are required or the tag is ignored.
 
+An invite operation is **not** the entity's fixture create, even when it is `POST` on the collection. oat will not seed it with a generated email. The invite check (and only that check) creates the grant, using `inviteAs` as `granteeField`. The check still runs when there is no non-invite create, as long as an item or list route exists.
+
 Timeline asserted: cannot read → invite → still cannot → accept → can → revoke → cannot.
 
 **Fallback:** the check does not run.
@@ -1071,7 +1081,11 @@ export default defineConfig({
 })
 ```
 
-An excluded operation never silently narrows what gets reported. Excluding an entity's `create` degrades that entity the same way a real seeding failure does — a `COVERAGE_GAP` naming the reason, then read-only checks run against whatever the list route already returns; `BLOCKED` if nothing exists to fall back on. Excluding `read`/`update`/`delete` individually stands down just the checks that need that one operation. The run summary states what a profile skipped: `skipped 12 operation(s) under --profile cheap (12 high-cost)` — the same principle as `did not apply` for a coverage gap: a report that only shows what ran invites the reader to assume the rest was verified.
+An excluded operation never silently narrows what gets reported. Excluding an entity's `create` degrades that entity the same way a real seeding failure does — a `COVERAGE_GAP` naming the reason, then read-only checks run against whatever the list route already returns; `BLOCKED` if nothing exists to fall back on. Excluding `read`/`update`/`delete` individually stands down just the checks that need that one operation.
+
+Exclusion applies to every invocation, not only create/read/update/delete. `effects.declared-effect-occurs` and `async.reaches-terminal-state` drop ops the profile forbids and record `profile.skip` — they do not POST `extract.once` under `--profile cheap`. A check whose only targets were excluded did not apply / names the profile; it never looks like the backend returned 500.
+
+The run summary states what a profile skipped: `skipped 12 operation(s) under --profile cheap (12 high-cost)` — the same principle as `did not apply` for a coverage gap: a report that only shows what ran invites the reader to assume the rest was verified.
 
 ### `x-rate-limit` — pacing oat's own traffic
 

package/dist/cli.js

@@ -200,7 +200,7 @@ async function main() {
         return 0;
     }
     if (command === "conformance") {
-        const { postgresAvailable, renderParserSuite, renderSuite, runExampleSpecSuite, runTagUnlockSuite, runParserSuite, runCoverageReportSuite, runTenantScopeSuite, runSuite, sqliteAvailable, d1Available, } = await import("./conformance/suite.js");
+        const { postgresAvailable, renderParserSuite, renderSuite, runExampleSpecSuite, runTagUnlockSuite, runParserSuite, runCoverageReportSuite, runSeedContractSuite, runTenantScopeSuite, runSuite, sqliteAvailable, d1Available, } = await import("./conformance/suite.js");
         const { runFeatureGateSuite } = await import("./conformance/feature-gate.js");
         const parser = renderParserSuite(runParserSuite());
         process.stdout.write(parser.text);
@@ -222,6 +222,9 @@ async function main() {
         const featureGate = renderParserSuite(await runFeatureGateSuite());
         process.stdout.write(featureGate.text);
         parser.failures += featureGate.failures;
+        const seedContract = renderParserSuite(await runSeedContractSuite());
+        process.stdout.write(seedContract.text);
+        parser.failures += seedContract.failures;
         if (flags.parser === true)
             return parser.failures > 0 ? 1 : 0;
         if (flags.precision !== undefined) {
@@ -372,6 +375,15 @@ async function main() {
     const raw = await loadSpec(specSource, str(flags, "base-url"));
     const { doc, externalRefs } = dereference(raw);
     const model = buildModel(doc);
+    try {
+        const { probeCreateFixtures } = await import("./runtime/world.js");
+        probeCreateFixtures(model);
+    }
+    catch (error) {
+        const { isOverflowError } = await import("./runtime/fixture.js");
+        if (!isOverflowError(error))
+            throw error;
+    }
     switch (command) {
         case "plan":
             process.stdout.write(report.plan(model, flags.json === true));

package/dist/runtime/checks.d.ts.map

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

package/dist/runtime/checks.js

@@ -2543,25 +2543,20 @@ function pointerValue(body, pointer) {
  * at the same check — the timeline is the property.
  */
 const inviteGrantsThenRevokes = {
-    applicable: (ctx) => ctx.invite !== null &&
-        ctx.readOp !== undefined &&
-        ctx.records.length > 0 &&
-        ctx.actors.some((actor) => actor.inviteAs !== undefined &&
-            ctx.actors[0] !== undefined &&
-            !sameTenantScope(actor.roots, ctx.actors[0].roots)),
+    applicable: (ctx) => ctx.invite !== null && (ctx.readOp !== undefined || ctx.listOp !== undefined),
     dependsOn: ["list.read-after-write", "tenant.item-not-readable-cross-tenant"],
     id: "auth.invite-grants-then-revokes",
-    needs: "x-invite naming invite/accept/revoke, a peer principal with inviteAs, and an item route",
+    needs: "x-invite naming invite/accept/revoke, a peer principal with inviteAs, and an item or list route",
     async run(ctx) {
         const spec = ctx.invite;
         const owner = ctx.actors[0];
-        const target = ctx.records[0];
-        if (spec === null || owner === undefined || target === undefined || ctx.readOp === undefined) {
+        if (spec === null || owner === undefined) {
             return;
         }
-        const delegate = ctx.actors.find((actor) => actor.inviteAs !== undefined && !sameTenantScope(actor.roots, owner.roots));
+        const delegate = ctx.actors.find((actor) => actor !== owner && actor.inviteAs !== undefined && !sameTenantScope(actor.roots, owner.roots)) ?? ctx.actors.find((actor) => actor !== owner && actor.inviteAs !== undefined);
         if (delegate === undefined || delegate.inviteAs === undefined) {
-            return ctx.findings.unresolved(this.id, ctx.entityName, "no peer principal declares inviteAs, so there is no one to invite");
+            return ctx.findings.gap(this.id, ctx.entityName, "x-invite requires a peer principal with inviteAs", "x-invite names the grant flow, but no peer principal declares inviteAs, so oat " +
+                "cannot fill the grantee field without inventing an email");
         }
         const inviteOp = ctx.model.byOperationId.get(spec.invite);
         const acceptOp = ctx.model.byOperationId.get(spec.accept);
@@ -2569,16 +2564,23 @@ const inviteGrantsThenRevokes = {
         if (inviteOp === undefined || acceptOp === undefined || revokeOp === undefined) {
             return ctx.findings.unresolved(this.id, ctx.entityName, "x-invite names an operation that is not in the document");
         }
-        const id = String(target[ctx.identity]);
-        const resource = { ...ctx.scope, ...itemParamFor(ctx, id) };
-        const itemPath = ctx.readOp.path;
+        const target = ctx.records[0];
+        const id = target === undefined ? undefined : String(target[ctx.identity]);
+        const resource = {
+            ...ctx.scope,
+            ...(id === undefined ? {} : itemParamFor(ctx, id)),
+        };
+        const itemPath = ctx.readOp?.path;
         const canRead = async () => {
+            if (itemPath === undefined || id === undefined)
+                return null;
             const exchange = await ctx.client.get(fillPath(itemPath, { ...delegate.roots, ...resource }), {
                 headers: delegate.headers(),
             });
             return exchange.status < 300;
         };
-        if (await canRead()) {
+        const alreadyReadable = await canRead();
+        if (alreadyReadable === true) {
             return ctx.findings.unresolved(this.id, ctx.entityName, "the delegate could already read the record, so invite cannot be distinguished from a leak");
         }
         const invited = await ctx.client.request(inviteOp.method, fillPath(inviteOp.path, resource), {
@@ -2590,7 +2592,7 @@ const inviteGrantsThenRevokes = {
         if (invited.status >= 300) {
             return ctx.findings.unresolved(this.id, ctx.entityName, `invite returned ${invited.status}, so accept/revoke were never exercised`);
         }
-        if (await canRead()) {
+        if ((await canRead()) === true) {
             ctx.findings.backend(this.id, ctx.entityName, "an invite grants access before it is accepted", `inviting ${delegate.id} made ${ctx.entityName} ${id} readable immediately. The accept ` +
                 "step is then theatre — anyone who can be named in an invite body is already in.", [invited]);
             return;
@@ -2608,7 +2610,7 @@ const inviteGrantsThenRevokes = {
         if (accepted.status >= 300) {
             return ctx.findings.unresolved(this.id, ctx.entityName, `accept returned ${accepted.status}`);
         }
-        if (!(await canRead())) {
+        if ((await canRead()) === false) {
             ctx.findings.backend(this.id, ctx.entityName, "accepting an invite does not grant access", `${delegate.id} accepted an invite to ${ctx.entityName} ${id} and still cannot read it. ` +
                 "The invite flow completed; the grant did not.", [invited, accepted]);
             return;
@@ -2622,7 +2624,7 @@ const inviteGrantsThenRevokes = {
         if (revoked.status >= 300) {
             return ctx.findings.unresolved(this.id, ctx.entityName, `revoke returned ${revoked.status}`);
         }
-        if (await canRead()) {
+        if ((await canRead()) === true) {
             ctx.findings.backend(this.id, ctx.entityName, "revoking an invite does not remove access", `${delegate.id} can still read ${ctx.entityName} ${id} after the grant was revoked. ` +
                 "A share that cannot be taken back is a standing leak.", [invited, accepted, revoked]);
         }
@@ -2983,9 +2985,24 @@ const successSchemaHonoured = {
 };
 /** Builds a body that should be accepted, for use as the base of a negative probe. */
 function validBody(ctx, schema) {
-    const [member] = buildCohort(schema, ctx.seed, ["baseline"]);
+    const [member] = buildCohort(schema, ctx.seed, ["baseline"], ctx.createOp?.operationId ?? ctx.entityName);
     return member?.body ?? {};
 }
+/** Invite bodies must carry the peer's `inviteAs`, never a generated email. */
+function bodyForOp(ctx, op) {
+    const body = validBody(ctx, requestSchemaOf(ctx, op) ?? {});
+    const spec = op.invite ?? ctx.invite;
+    if (spec === null || spec === undefined)
+        return body;
+    const owner = ctx.actors[0];
+    const delegate = ctx.actors.find((actor) => actor !== owner &&
+        actor.inviteAs !== undefined &&
+        owner !== undefined &&
+        !sameTenantScope(actor.roots, owner.roots)) ?? ctx.actors.find((actor) => actor !== owner && actor.inviteAs !== undefined);
+    if (delegate?.inviteAs !== undefined)
+        body[spec.granteeField] = delegate.inviteAs;
+    return body;
+}
 function requestSchemaOf(ctx, op) {
     const raw = ctx.model.rawOperations.get(op.operationId);
     const content = raw?.requestBody?.content;
@@ -3245,7 +3262,7 @@ const declaredEffectsOccur = {
                 const before = await observe(ctx, listOp);
                 if (before === null)
                     continue;
-                const body = op.hasRequestBody ? validBody(ctx, requestSchemaOf(ctx, op) ?? {}) : undefined;
+                const body = op.hasRequestBody ? bodyForOp(ctx, op) : undefined;
                 const invoked = await ctx.client.request(op.method, fillPath(op.path, ctx.scope), {
                     headers: ctx.auth(),
                     ...(body === undefined ? {} : { body }),
@@ -3317,7 +3334,7 @@ const asyncReachesTerminalState = {
             const spec = op.async;
             if (spec === null)
                 continue;
-            const body = op.hasRequestBody ? validBody(ctx, requestSchemaOf(ctx, op) ?? {}) : undefined;
+            const body = op.hasRequestBody ? bodyForOp(ctx, op) : undefined;
             const start = await ctx.client.request(op.method, fillPath(op.path, ctx.scope), {
                 headers: ctx.auth(),
                 ...(body === undefined ? {} : { body }),