@aethervtt/shard-core 0.0.1 → 0.1.0

package/dist/ecs/host-write.d.ts

@@ -0,0 +1,5 @@
+import type { ComponentDef } from '../schema/component.js';
+/** Runs `fn` with `hostOnly` component writes allowed. */
+export declare function withHostWrite<T>(fn: () => T): T;
+/** Throws unless a host grant is open. The world calls it before writing a `hostOnly` component. */
+export declare function assertHostWrite(def: ComponentDef): void;

package/dist/ecs/host-write.js

@@ -0,0 +1,24 @@
+import { ShardError } from "../error.js";
+let depth = 0;
+function withHostWrite(fn) {
+  depth++;
+  try {
+    return fn();
+  } finally {
+    depth--;
+  }
+}
+function assertHostWrite(def) {
+  if (depth > 0) return;
+  throw new ShardError(
+    "core/owner-not-authorable",
+    `"${def.name}" can only be written by the host`,
+    {
+      hint: "Ownership is a grant from host code: spawn with world.owners.spawn(owner, ...) or world.owners.adopt(owner, entity)."
+    }
+  );
+}
+export {
+  assertHostWrite,
+  withHostWrite
+};

package/dist/ecs/index.d.ts

@@ -3,6 +3,7 @@ export { type Entity, entityGeneration, entityIndex, formatEntity, MAX_ENTITIES,
 export { EventQueue, EventReader } from './events.js';
 export { ChildOf, Children, Derived } from './hierarchy.js';
 export { type LifecycleEvent, type LifecycleKind, type LifecycleObserver, type LifecycleTrigger, onAdd, onRemove, onSet, type TriggerEvent, type TriggerObserver, } from './observers.js';
+export { OwnedBy, Owner, type OwnerDescription, type OwnerLimits, type OwnerQuota, OwnerReleased, Owners, type OwnerUsage, } from './owners.js';
 export { Query, type QueryDescriptor } from './query.js';
 export { type ColumnOf, ComponentStorage, Table, type TickSource } from './table.js';
 export { type ComponentInit, World, type WorldStats } from './world.js';

package/dist/ecs/index.js

@@ -13,6 +13,12 @@ import {
   onRemove,
   onSet
 } from "./observers.js";
+import {
+  OwnedBy,
+  Owner,
+  OwnerReleased,
+  Owners
+} from "./owners.js";
 import { Query } from "./query.js";
 import { ComponentStorage, Table } from "./table.js";
 import { World } from "./world.js";
@@ -25,6 +31,10 @@ export {
   EventQueue,
   EventReader,
   MAX_ENTITIES,
+  OwnedBy,
+  Owner,
+  OwnerReleased,
+  Owners,
   Query,
   Table,
   World,

package/dist/ecs/owners.d.ts

@@ -0,0 +1,113 @@
+import type { Entity } from './entity.js';
+import type { ComponentInit, World } from './world.js';
+/** What an owner may hold at most, itself and its child owners together. */
+export interface OwnerLimits {
+    entities?: number;
+    triangles?: number;
+    textures?: number;
+    bytes?: number;
+}
+export type OwnerQuota = keyof OwnerLimits;
+/** What an owner holds now: its own and its child owners' together. */
+export interface OwnerUsage {
+    entities: number;
+    triangles: number;
+    textures: number;
+    bytes: number;
+}
+export interface OwnerDescription {
+    name: string;
+    parent: string | undefined;
+    children: string[];
+    released: boolean;
+    /** Usage including child owners, which is what limits apply to. */
+    usage: OwnerUsage;
+    limits: OwnerLimits;
+    /** Sections other packages add: asset leases, GPU objects. */
+    [section: string]: unknown;
+}
+export declare const OwnedBy: import("..").ComponentDef<{
+    readonly owner: import("..").FieldType<number, "u32">;
+    readonly inherited: import("..").FieldType<boolean, "u8">;
+}>;
+export declare const OwnerReleased: import("..").EventDef<{
+    name: string;
+    entities: number;
+}>;
+/** Created by `world.owners.create`; held by host code, never serialized. */
+export declare class Owner {
+    readonly name: string;
+    readonly parent: Owner | undefined;
+    readonly limits: Readonly<OwnerLimits>;
+    /** @internal The value `OwnedBy.owner` stores. */
+    readonly id: number;
+    /** @internal Use `world.owners.create`. */
+    constructor(token: symbol, id: number, name: string, parent: Owner | undefined, limits: OwnerLimits);
+}
+type ReleaseHook = (owner: Owner) => void;
+type Describer = (owner: Owner) => unknown;
+/** The world's owners (`world.owners`). */
+export declare class Owners {
+    private readonly world;
+    private readonly states;
+    private readonly issued;
+    private readonly releaseHooks;
+    private readonly describers;
+    private nextId;
+    private live;
+    constructor(world: World);
+    /** A new owner. With `parent`, its usage counts toward the parent's limits too. */
+    create(name: string, options?: {
+        parent?: Owner;
+        limits?: OwnerLimits;
+    }): Owner;
+    /** Spawns an entity owned by `owner`: the only way to create an owned entity. */
+    spawn(owner: Owner, ...inits: readonly ComponentInit[]): Entity;
+    /** Gives an existing entity, and the descendants that had no owner of their own, to `owner`. */
+    adopt(owner: Owner, entity: Entity): void;
+    /**
+     * Despawns everything `owner` and its child owners hold (with descendants), drops their leases
+     * (unloading assets no one else leases, and their GPU objects), and sends `OwnerReleased`. The
+     * owner and its children are unusable afterwards (`core/owner-released`).
+     */
+    release(owner: Owner): void;
+    /** Counts, limits and the sections other packages add (asset leases, GPU objects). */
+    describe(owner: Owner): OwnerDescription;
+    /** Every live owner, for agents (`owners.describe` with no name). */
+    list(): {
+        name: string;
+        parent: string | undefined;
+        usage: OwnerUsage;
+    }[];
+    /** The live owner named `name`, for host code that keeps names rather than objects. */
+    find(name: string): Owner | undefined;
+    /** The name of the entity's owner, or undefined. Reading ownership needs no grant. */
+    nameOf(entity: Entity): string | undefined;
+    isReleased(owner: Owner): boolean;
+    /**
+     * Reserves `amount` of a quota for work about to happen (an asset lease, a GPU upload): throws
+     * `core/owner-quota` and changes nothing if it would exceed a limit of the owner or an ancestor.
+     */
+    charge(owner: Owner, quota: Exclude<OwnerQuota, 'entities'>, amount: number): void;
+    /**
+     * Throws `core/owner-quota` unless `amount` more of `quota` fits `owner` and its ancestors. For work
+     * that makes many things at once (a scene load) and must create nothing if it doesn't fit.
+     */
+    ensureCapacity(owner: Owner, quota: OwnerQuota, amount: number): void;
+    /** Gives back what `charge` reserved. */
+    refund(owner: Owner, quota: Exclude<OwnerQuota, 'entities'>, amount: number): void;
+    /** Runs when an owner is released, after its entities are gone (assets drop its leases here). */
+    onRelease(hook: ReleaseHook): () => void;
+    /** Adds a section to `describe` (e.g. `leases`, `gpu`). */
+    addDescriber(section: string, describe: Describer): () => void;
+    /** Throws `core/owner-released` or `core/owner-invalid` unless `owner` is live and issued here. */
+    private state;
+    private check;
+    private adjust;
+    private ownerIdOf;
+    /** The entity and its descendants that are unowned or owned by `from` through inheritance. */
+    private collect;
+    /** A new child of an owned parent takes the parent's owner, unless it has its own. */
+    private inherit;
+}
+export {};

package/dist/ecs/owners.js

@@ -0,0 +1,297 @@
+import { ShardError } from "../error.js";
+import { defineComponent } from "../schema/component.js";
+import { t } from "../schema/field.js";
+import { defineEvent } from "../schema/resource.js";
+import { ChildOf, Children } from "./hierarchy.js";
+import { withHostWrite } from "./host-write.js";
+import { onAdd, onRemove, onSet } from "./observers.js";
+const OwnedBy = defineComponent(
+  "core/OwnedBy",
+  {
+    owner: t.u32({ description: "The owner id; world.owners.nameOf(entity) gives its name." }),
+    inherited: t.bool({ description: "Set when the entity took its parent's owner." })
+  },
+  {
+    description: "Who owns this entity (0061). Only host code holding the Owner writes it (world.owners.spawn / adopt); children take their parent's owner. Never in scene files.",
+    hostOnly: true
+  }
+);
+const OwnerReleased = defineEvent("core/OwnerReleased", {
+  description: "An owner was released: its entities despawned, its leases dropped."
+});
+const QUOTAS = ["entities", "triangles", "textures", "bytes"];
+const ISSUE = /* @__PURE__ */ Symbol("owner");
+class Owner {
+  name;
+  parent;
+  limits;
+  /** @internal The value `OwnedBy.owner` stores. */
+  id;
+  /** @internal Use `world.owners.create`. */
+  constructor(token, id, name, parent, limits) {
+    if (token !== ISSUE) {
+      throw new ShardError("core/owner-invalid", "Owners are created with world.owners.create", {
+        hint: "An Owner is a grant from host code; it cannot be constructed or copied."
+      });
+    }
+    this.id = id;
+    this.name = name;
+    this.parent = parent;
+    this.limits = Object.freeze({ ...limits });
+  }
+}
+class Owners {
+  world;
+  states = /* @__PURE__ */ new Map();
+  issued = /* @__PURE__ */ new WeakMap();
+  releaseHooks = /* @__PURE__ */ new Set();
+  describers = /* @__PURE__ */ new Map();
+  nextId = 1;
+  live = 0;
+  constructor(world) {
+    this.world = world;
+    world.observe(onAdd(OwnedBy), ({ entity }) => {
+      const state = this.states.get(world.get(entity, OwnedBy).owner);
+      if (state) this.adjust(state, "entities", 1);
+    });
+    world.observe(onRemove(OwnedBy), ({ entity }) => {
+      const state = this.states.get(world.get(entity, OwnedBy).owner);
+      if (state) this.adjust(state, "entities", -1);
+    });
+    world.observe(onSet(OwnedBy), ({ entity, previous }) => {
+      const before = previous && this.states.get(previous.owner);
+      const after = this.states.get(world.get(entity, OwnedBy).owner);
+      if (before === after) return;
+      if (before) this.adjust(before, "entities", -1);
+      if (after) this.adjust(after, "entities", 1);
+    });
+    world.observe(onAdd(ChildOf), ({ entity }) => this.inherit(entity));
+    world.observe(onSet(ChildOf), ({ entity }) => this.inherit(entity));
+  }
+  /** A new owner. With `parent`, its usage counts toward the parent's limits too. */
+  create(name, options = {}) {
+    const parent = options.parent ? this.state(options.parent) : void 0;
+    for (const [key, value] of Object.entries(options.limits ?? {})) {
+      if (!QUOTAS.includes(key) || !(typeof value === "number" && value >= 0)) {
+        throw new ShardError("core/owner-invalid", `Invalid owner limit ${key}: ${value}`, {
+          hint: `Limits are non-negative numbers for ${QUOTAS.join(", ")}.`
+        });
+      }
+    }
+    const owner = new Owner(ISSUE, this.nextId++, name, parent?.owner, options.limits ?? {});
+    const state = {
+      owner,
+      children: /* @__PURE__ */ new Set(),
+      parent,
+      usage: { entities: 0, triangles: 0, textures: 0, bytes: 0 },
+      released: false
+    };
+    parent?.children.add(state);
+    this.states.set(owner.id, state);
+    this.issued.set(owner, state);
+    this.live++;
+    return owner;
+  }
+  /** Spawns an entity owned by `owner`: the only way to create an owned entity. */
+  spawn(owner, ...inits) {
+    const state = this.state(owner);
+    this.check(state, "entities", 1);
+    const spawn = this.world.spawn.bind(this.world);
+    return withHostWrite(() => spawn(...inits, [OwnedBy, { owner: owner.id, inherited: false }]));
+  }
+  /** Gives an existing entity, and the descendants that had no owner of their own, to `owner`. */
+  adopt(owner, entity) {
+    const state = this.state(owner);
+    const previous = this.world.tryGet(entity, OwnedBy)?.owner;
+    const moving = [];
+    this.collect(entity, previous, moving);
+    this.check(state, "entities", moving.filter((e) => this.ownerIdOf(e) !== owner.id).length);
+    withHostWrite(() => {
+      for (let i = 0; i < moving.length; i++) {
+        const e = moving[i];
+        const value = { owner: owner.id, inherited: e !== entity };
+        if (this.world.has(e, OwnedBy)) this.world.set(e, OwnedBy, value);
+        else this.world.add(e, OwnedBy, value);
+      }
+    });
+  }
+  /**
+   * Despawns everything `owner` and its child owners hold (with descendants), drops their leases
+   * (unloading assets no one else leases, and their GPU objects), and sends `OwnerReleased`. The
+   * owner and its children are unusable afterwards (`core/owner-released`).
+   */
+  release(owner) {
+    const state = this.state(owner);
+    const all = [];
+    const gather = (s) => {
+      for (const child of s.children) gather(child);
+      all.push(s);
+    };
+    gather(state);
+    const ids = new Set(all.map((s) => s.owner.id));
+    const world = this.world;
+    const doomed = [];
+    const q = world.query({ with: [OwnedBy] });
+    for (const table of q.tables) {
+      const column = table.column(OwnedBy, "owner");
+      for (let i = 0; i < table.count; i++) {
+        if (ids.has(column[i])) doomed.push(table.entities[i]);
+      }
+    }
+    const counts = /* @__PURE__ */ new Map();
+    for (const s of all) counts.set(s.owner.id, s.usage.entities);
+    for (const e of doomed) if (world.isAlive(e)) world.despawn(e);
+    for (const s of all) {
+      for (const hook of this.releaseHooks) hook(s.owner);
+      s.released = true;
+      this.states.delete(s.owner.id);
+      this.live--;
+      world.send(OwnerReleased, { name: s.owner.name, entities: counts.get(s.owner.id) ?? 0 });
+    }
+    state.parent?.children.delete(state);
+  }
+  /** Counts, limits and the sections other packages add (asset leases, GPU objects). */
+  describe(owner) {
+    const state = this.issued.get(owner);
+    if (!state) throw invalid();
+    const out = {
+      name: owner.name,
+      parent: owner.parent?.name,
+      children: [...state.children].map((c) => c.owner.name),
+      released: state.released,
+      usage: { ...state.usage },
+      limits: { ...owner.limits }
+    };
+    if (!state.released) for (const [key, fn] of this.describers) out[key] = fn(owner);
+    return out;
+  }
+  /** Every live owner, for agents (`owners.describe` with no name). */
+  list() {
+    return [...this.states.values()].map((s) => ({
+      name: s.owner.name,
+      parent: s.owner.parent?.name,
+      usage: { ...s.usage }
+    }));
+  }
+  /** The live owner named `name`, for host code that keeps names rather than objects. */
+  find(name) {
+    for (const s of this.states.values()) if (s.owner.name === name) return s.owner;
+    return void 0;
+  }
+  /** The name of the entity's owner, or undefined. Reading ownership needs no grant. */
+  nameOf(entity) {
+    const id = this.ownerIdOf(entity);
+    return id === void 0 ? void 0 : this.states.get(id)?.owner.name;
+  }
+  isReleased(owner) {
+    return this.issued.get(owner)?.released ?? true;
+  }
+  /**
+   * Reserves `amount` of a quota for work about to happen (an asset lease, a GPU upload): throws
+   * `core/owner-quota` and changes nothing if it would exceed a limit of the owner or an ancestor.
+   */
+  charge(owner, quota, amount) {
+    const state = this.state(owner);
+    this.check(state, quota, amount);
+    this.adjust(state, quota, amount);
+  }
+  /**
+   * Throws `core/owner-quota` unless `amount` more of `quota` fits `owner` and its ancestors. For work
+   * that makes many things at once (a scene load) and must create nothing if it doesn't fit.
+   */
+  ensureCapacity(owner, quota, amount) {
+    this.check(this.state(owner), quota, amount);
+  }
+  /** Gives back what `charge` reserved. */
+  refund(owner, quota, amount) {
+    const state = this.issued.get(owner);
+    if (state && !state.released) this.adjust(state, quota, -amount);
+  }
+  /** Runs when an owner is released, after its entities are gone (assets drop its leases here). */
+  onRelease(hook) {
+    this.releaseHooks.add(hook);
+    return () => this.releaseHooks.delete(hook);
+  }
+  /** Adds a section to `describe` (e.g. `leases`, `gpu`). */
+  addDescriber(section, describe) {
+    this.describers.set(section, describe);
+    return () => this.describers.delete(section);
+  }
+  /** Throws `core/owner-released` or `core/owner-invalid` unless `owner` is live and issued here. */
+  state(owner) {
+    const state = this.issued.get(owner);
+    if (!state) throw invalid();
+    if (state.released) {
+      throw new ShardError("core/owner-released", `Owner "${owner.name}" was released`, {
+        hint: "Create a new owner; a released one holds nothing and accepts nothing."
+      });
+    }
+    return state;
+  }
+  check(state, quota, amount) {
+    if (amount <= 0) return;
+    for (let s = state; s; s = s.parent) {
+      const limit = s.owner.limits[quota];
+      if (limit !== void 0 && s.usage[quota] + amount > limit) {
+        throw new ShardError(
+          "core/owner-quota",
+          `Owner "${s.owner.name}" is at its ${quota} limit (${s.usage[quota]} of ${limit}; ${amount} more requested)`,
+          {
+            path: quota,
+            hint: s === state ? "Release what it no longer needs, or create it with a higher limit." : `The limit belongs to "${s.owner.name}", which counts its child owners' usage.`
+          }
+        );
+      }
+    }
+  }
+  adjust(state, quota, amount) {
+    for (let s = state; s; s = s.parent) s.usage[quota] += amount;
+  }
+  ownerIdOf(entity) {
+    return this.world.tryGet(entity, OwnedBy)?.owner;
+  }
+  /** The entity and its descendants that are unowned or owned by `from` through inheritance. */
+  collect(entity, from, out) {
+    out.push(entity);
+    const children = this.world.tryGet(entity, Children);
+    if (!children) return;
+    for (const child of children.entities) {
+      if (child === null || !this.world.isAlive(child)) continue;
+      const own = this.world.tryGet(child, OwnedBy);
+      if (own && !(own.inherited && own.owner === from)) continue;
+      this.collect(child, from, out);
+    }
+  }
+  /** A new child of an owned parent takes the parent's owner, unless it has its own. */
+  inherit(entity) {
+    if (this.live === 0) return;
+    const world = this.world;
+    const own = world.tryGet(entity, OwnedBy);
+    if (own && !own.inherited) return;
+    const parent = world.get(entity, ChildOf).parent;
+    const from = parent !== null && world.isAlive(parent) ? world.tryGet(parent, OwnedBy) : void 0;
+    if (!from || !this.states.has(from.owner)) return;
+    if (own?.owner === from.owner) return;
+    const moving = [];
+    this.collect(entity, own?.owner, moving);
+    withHostWrite(() => {
+      for (let i = 0; i < moving.length; i++) {
+        const e = moving[i];
+        const value = { owner: from.owner, inherited: true };
+        if (world.has(e, OwnedBy)) world.set(e, OwnedBy, value);
+        else world.add(e, OwnedBy, value);
+      }
+    });
+  }
+}
+function invalid() {
+  return new ShardError("core/owner-invalid", "Not an owner of this world", {
+    hint: "Pass the Owner object world.owners.create returned, in the same world."
+  });
+}
+export {
+  OwnedBy,
+  Owner,
+  OwnerReleased,
+  Owners
+};

package/dist/ecs/world.d.ts

@@ -5,6 +5,7 @@ import type { EventDef, ResourceDef } from '../schema/resource.js';
 import { type Entity } from './entity.js';
 import { EventReader } from './events.js';
 import { type LifecycleObserver, type LifecycleTrigger, type TriggerObserver } from './observers.js';
+import { Owners } from './owners.js';
 import { Query, type QueryDescriptor } from './query.js';
 import { Table, type TickSource } from './table.js';
 /** A component to spawn/add with: the bare definition (defaults), or `[definition, values]`. */
@@ -29,6 +30,14 @@ export declare class World implements TickSource {
     /** Change-detection clock. The scheduler advances it once per system run. */
     tick: number;
     readonly registry: Registry;
+    /**
+     * While true, the next write (`set`, `add`, `remove`, `spawn`, `despawn`, `insertResource`,
+     * `removeResource`, `send`, `patchResource`, `touchResource`) clears it and calls `onWake`. The
+     * on-demand runner sets it when a frame ends and nothing asks for another (0052).
+     */
+    asleep: boolean;
+    /** Called by the first write while `asleep`. Set by the on-demand runner. */
+    onWake: (() => void) | undefined;
     private generations;
     private tableOf;
     private rowOf;
@@ -40,11 +49,21 @@ export declare class World implements TickSource {
     private readonly emptyTable;
     private readonly queries;
     private readonly resources;
+    /** Change tick per resource id: set by insertResource, patchResource, and touchResource. */
+    private readonly resourceTicks;
     private readonly eventQueues;
     private readonly observers;
     private readonly registered;
+    private owners_;
     constructor();
+    /**
+     * Who made what (0061): owners hold entities and asset leases, and release them together.
+     * Only code holding an `Owner` can spawn into it, lease for it, or release it.
+     */
+    get owners(): Owners;
     incrementTick(): number;
+    /** Wakes the world as a write would: if it's asleep, clears `asleep` and calls `onWake`. */
+    wake(): void;
     spawn<const T extends readonly Fields[]>(...inits: {
         [K in keyof T]: ComponentInit<T[K]>;
     }): Entity;
@@ -81,6 +100,18 @@ export declare class World implements TickSource {
     /** Returns a cached query; the same descriptor always gives the same `Query`. */
     query(desc: QueryDescriptor): Query;
     insertResource<T>(def: ResourceDef<T>, value: T): void;
+    /**
+     * Assigns `partial`'s fields onto the resource, marks it changed, and wakes the world. How code
+     * outside a frame writes a resource; a bare field assignment is invisible to both (0052).
+     */
+    patchResource<T extends object>(def: ResourceDef<T>, partial: Partial<T>): T;
+    /** Marks the resource changed and wakes the world, after editing it in place. */
+    touchResource(def: ResourceDef<unknown>): void;
+    /**
+     * Whether the resource was inserted, patched, or touched after tick `since` (a system passes
+     * `ctx.lastRunTick`), like component change detection.
+     */
+    resourceChanged(def: ResourceDef<unknown>, since: number): boolean;
     /** Inserts the resource from its `init` if it isn't present yet, and returns it. */
     initResource<T>(def: ResourceDef<T>): T;
     resource<T>(def: ResourceDef<T>): T;

package/dist/ecs/world.js

@@ -3,12 +3,14 @@ import { Registry } from "../schema/registry.js";
 import { formatEntity, MAX_ENTITIES, makeEntity } from "./entity.js";
 import { EventQueue, EventReader } from "./events.js";
 import { ChildOf, Children } from "./hierarchy.js";
+import { assertHostWrite } from "./host-write.js";
 import {
   ObserverTable,
   onAdd,
   onRemove,
   onSet
 } from "./observers.js";
+import { Owners } from "./owners.js";
 import { Query, queryKey } from "./query.js";
 import { Table } from "./table.js";
 const FREE = 4294967295;
@@ -19,6 +21,14 @@ class World {
   /** Change-detection clock. The scheduler advances it once per system run. */
   tick = 1;
   registry = new Registry();
+  /**
+   * While true, the next write (`set`, `add`, `remove`, `spawn`, `despawn`, `insertResource`,
+   * `removeResource`, `send`, `patchResource`, `touchResource`) clears it and calls `onWake`. The
+   * on-demand runner sets it when a frame ends and nothing asks for another (0052).
+   */
+  asleep = false;
+  /** Called by the first write while `asleep`. Set by the on-demand runner. */
+  onWake = void 0;
   generations = new Uint32Array(1024);
   tableOf = new Uint32Array(1024).fill(FREE);
   rowOf = new Uint32Array(1024);
@@ -30,18 +40,36 @@ class World {
   emptyTable;
   queries = /* @__PURE__ */ new Map();
   resources = /* @__PURE__ */ new Map();
+  /** Change tick per resource id: set by insertResource, patchResource, and touchResource. */
+  resourceTicks = [];
   eventQueues = /* @__PURE__ */ new Map();
   observers = new ObserverTable();
   registered = [];
+  owners_;
   constructor() {
     this.emptyTable = this.getOrCreateTable([]);
     this.installHierarchy();
   }
+  /**
+   * Who made what (0061): owners hold entities and asset leases, and release them together.
+   * Only code holding an `Owner` can spawn into it, lease for it, or release it.
+   */
+  get owners() {
+    this.owners_ ??= new Owners(this);
+    return this.owners_;
+  }
   incrementTick() {
     return ++this.tick;
   }
+  /** Wakes the world as a write would: if it's asleep, clears `asleep` and calls `onWake`. */
+  wake() {
+    if (!this.asleep) return;
+    this.asleep = false;
+    this.onWake?.();
+  }
   // --- entities --------------------------------------------------------------
   spawn(...inits) {
+    if (this.asleep) this.wake();
     const entity = this.allocate();
     this.insert(entity, inits);
     return entity;
@@ -55,6 +83,7 @@ class World {
     if (index >= this.nextIndex || this.tableOf[index] !== PENDING || this.generations[index] !== Math.floor(entity / MAX_ENTITIES)) {
       throw new ShardError("ecs/dead-entity", `Entity ${formatEntity(entity)} is not reserved`);
     }
+    if (this.asleep) this.wake();
     this.insert(entity, inits);
   }
   isAlive(entity) {
@@ -69,6 +98,7 @@ class World {
   /** Despawns the entity and, if it has children, all of its descendants. */
   despawn(entity) {
     this.locate(entity);
+    if (this.asleep) this.wake();
     const children = this.tryGet(entity, Children);
     if (children) {
       for (const child of children.entities) {
@@ -80,6 +110,7 @@ class World {
   /** Despawns only this entity. Its children lose their `ChildOf` and become roots. */
   despawnSingle(entity) {
     this.locate(entity);
+    if (this.asleep) this.wake();
     const children = this.tryGet(entity, Children);
     if (children) {
       for (const child of children.entities) {
@@ -105,7 +136,9 @@ class World {
   /** Adds a component (defaults for missing fields). If present, replaces it and fires `onSet`. */
   add(entity, component, value) {
     const def = component;
+    if (def.hostOnly) assertHostWrite(def);
     const index = this.locate(entity);
+    if (this.asleep) this.wake();
     this.ensureRegistered(def);
     const table = this.tables[this.tableOf[index]];
     const row = this.rowOf[index];
@@ -134,8 +167,10 @@ class World {
   }
   /** Removes a component. Returns false if the entity didn't have it. */
   remove(entity, component) {
+    if (component.hostOnly) assertHostWrite(component);
     let index = this.locate(entity);
     if (!this.tables[this.tableOf[index]].has(component)) return false;
+    if (this.asleep) this.wake();
     this.fire("remove", entity, component, void 0);
     index = this.locate(entity);
     const table = this.tables[this.tableOf[index]];
@@ -162,9 +197,11 @@ class World {
   /** Writes the given fields and marks the component changed. */
   set(entity, component, values) {
     const def = component;
+    if (def.hostOnly) assertHostWrite(def);
     const index = this.locate(entity);
     const table = this.tables[this.tableOf[index]];
     if (!table.has(def)) throw missingComponent(entity, def.name);
+    if (this.asleep) this.wake();
     const row = this.rowOf[index];
     const previous = this.hasObservers("set", def) ? table.readComponent(def, row) : void 0;
     table.writeComponent(def, row, values);
@@ -207,7 +244,32 @@ class World {
   // --- resources -------------------------------------------------------------
   insertResource(def, value) {
     this.registry.register(def);
+    if (this.asleep) this.wake();
     this.resources.set(def.id, value);
+    this.resourceTicks[def.id] = this.tick;
+  }
+  /**
+   * Assigns `partial`'s fields onto the resource, marks it changed, and wakes the world. How code
+   * outside a frame writes a resource; a bare field assignment is invisible to both (0052).
+   */
+  patchResource(def, partial) {
+    const value = this.resource(def);
+    Object.assign(value, partial);
+    this.touchResource(def);
+    return value;
+  }
+  /** Marks the resource changed and wakes the world, after editing it in place. */
+  touchResource(def) {
+    if (!this.resources.has(def.id)) this.resource(def);
+    this.resourceTicks[def.id] = this.tick;
+    if (this.asleep) this.wake();
+  }
+  /**
+   * Whether the resource was inserted, patched, or touched after tick `since` (a system passes
+   * `ctx.lastRunTick`), like component change detection.
+   */
+  resourceChanged(def, since) {
+    return (this.resourceTicks[def.id] ?? 0) > since;
   }
   /** Inserts the resource from its `init` if it isn't present yet, and returns it. */
   initResource(def) {
@@ -240,10 +302,14 @@ class World {
     return this.resources.has(def.id);
   }
   removeResource(def) {
+    if (!this.resources.has(def.id)) return false;
+    if (this.asleep) this.wake();
+    this.resourceTicks[def.id] = this.tick;
     return this.resources.delete(def.id);
   }
   // --- events ----------------------------------------------------------------
   send(def, ...data) {
+    if (this.asleep) this.wake();
     this.eventQueue(def).send(data[0]);
   }
   reader(def) {
@@ -350,6 +416,7 @@ class World {
     for (let i = 0; i < inits.length; i++) {
       const init = inits[i];
       const def = Array.isArray(init) ? init[0] : init;
+      if (def.hostOnly) assertHostWrite(def);
       this.ensureRegistered(def);
       table = this.tableWith(table, def);
     }

package/dist/math/index.d.ts

@@ -5,6 +5,7 @@ export * as frustum from './frustum.js';
 export { hash32, hashSeed, LATTICE_PRIMES, mix32 } from './hash.js';
 export * as mat3 from './mat3.js';
 export * as mat4 from './mat4.js';
+export * as polygon from './polygon.js';
 export * as quat from './quat.js';
 export * as ray from './ray.js';
 export { Rng } from './rng.js';

package/dist/math/index.js

@@ -5,6 +5,7 @@ import * as frustum from "./frustum.js";
 import { hash32, hashSeed, LATTICE_PRIMES, mix32 } from "./hash.js";
 import * as mat3 from "./mat3.js";
 import * as mat4 from "./mat4.js";
+import * as polygon from "./polygon.js";
 import * as quat from "./quat.js";
 import * as ray from "./ray.js";
 import { Rng } from "./rng.js";
@@ -25,6 +26,7 @@ export {
   mat3,
   mat4,
   mix32,
+  polygon,
   quat,
   ray,
   vec2,

package/dist/math/polygon.d.ts

@@ -0,0 +1,17 @@
+/** The signed area of a ring. Positive when counter-clockwise (y up). */
+export declare function signedArea(points: ArrayLike<number>, start?: number, end?: number): number;
+/** The total area of triangles given by `indices` into flat xy `points`. */
+export declare function trianglesArea(points: ArrayLike<number>, indices: ArrayLike<number>): number;
+/**
+ * Triangulates a simple polygon, with optional holes, by ear clipping. `points` holds the outer
+ * ring first, then each hole; `holes` lists the vertex index where each hole starts. Either
+ * winding works for any ring. Returns vertex indices, three per triangle, counter-clockwise.
+ * Holes are bridged to the outer ring first, so the result covers the polygon minus its holes.
+ */
+export declare function triangulate(points: ArrayLike<number>, holes?: ArrayLike<number>): number[];
+/**
+ * Clips a convex polygon (flat xy, `n` points, in `src`) to the rectangle
+ * `[minX, maxX] × [minY, maxY]` (Sutherland–Hodgman). Writes the result to `out` and returns its
+ * point count (0 when nothing is inside). `out` and `scratch` need room for `n + 4` points.
+ */
+export declare function clipToRect(src: ArrayLike<number>, n: number, minX: number, minY: number, maxX: number, maxY: number, out: Float64Array, scratch: Float64Array): number;

package/dist/math/polygon.js

@@ -0,0 +1,307 @@
+function signedArea(points, start = 0, end = points.length >> 1) {
+  let area = 0;
+  for (let i = start, j = end - 1; i < end; j = i++) {
+    area += points[j * 2] * points[i * 2 + 1] - points[i * 2] * points[j * 2 + 1];
+  }
+  return area / 2;
+}
+function trianglesArea(points, indices) {
+  let area = 0;
+  for (let i = 0; i + 2 < indices.length; i += 3) {
+    const a = indices[i] * 2;
+    const b = indices[i + 1] * 2;
+    const c = indices[i + 2] * 2;
+    area += Math.abs(
+      (points[b] - points[a]) * (points[c + 1] - points[a + 1]) - (points[c] - points[a]) * (points[b + 1] - points[a + 1])
+    );
+  }
+  return area / 2;
+}
+function triangulate(points, holes = []) {
+  const out = [];
+  const count = points.length >> 1;
+  const outerEnd = holes.length > 0 ? holes[0] : count;
+  let outer = ring(points, 0, outerEnd, true);
+  if (!outer || outer.next === outer.prev) return out;
+  if (holes.length > 0) outer = eliminateHoles(points, holes, outer, count);
+  earcut(outer, out, 0);
+  return out;
+}
+function ring(points, start, end, ccw) {
+  if (end - start < 3) return void 0;
+  const forward = signedArea(points, start, end) > 0 === ccw;
+  let last;
+  if (forward) for (let i = start; i < end; i++) last = insert(i, points, last);
+  else for (let i = end - 1; i >= start; i--) last = insert(i, points, last);
+  if (last && last.x === last.next.x && last.y === last.next.y) {
+    const next = last.next;
+    remove(last);
+    last = next;
+  }
+  return last;
+}
+function insert(i, points, last) {
+  const node = { i, x: points[i * 2], y: points[i * 2 + 1], gone: false };
+  if (!last) {
+    node.prev = node;
+    node.next = node;
+  } else {
+    node.next = last.next;
+    node.prev = last;
+    last.next.prev = node;
+    last.next = node;
+  }
+  return node;
+}
+function remove(node) {
+  node.next.prev = node.prev;
+  node.prev.next = node.next;
+  node.gone = true;
+}
+function area2(a, b, c) {
+  return (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
+}
+function pointInTriangle(ax, ay, bx, by, cx, cy, px, py) {
+  return (cx - px) * (ay - py) >= (ax - px) * (cy - py) && (ax - px) * (by - py) >= (bx - px) * (ay - py) && (bx - px) * (cy - py) >= (cx - px) * (by - py);
+}
+function isEar(ear) {
+  const a = ear.prev;
+  const b = ear;
+  const c = ear.next;
+  if (area2(a, b, c) <= 0) return false;
+  for (let p = c.next; p !== a; p = p.next) {
+    if (p.x === a.x && p.y === a.y || p.x === b.x && p.y === b.y || p.x === c.x && p.y === c.y)
+      continue;
+    if (pointInTriangle(a.x, a.y, b.x, b.y, c.x, c.y, p.x, p.y) && area2(p.prev, p, p.next) <= 0)
+      return false;
+  }
+  return true;
+}
+function earcut(start, out, pass) {
+  let ear = start;
+  let stop = ear;
+  while (ear.prev !== ear.next) {
+    const prev = ear.prev;
+    const next = ear.next;
+    if (isEar(ear)) {
+      out.push(prev.i, ear.i, next.i);
+      remove(ear);
+      ear = next.next;
+      stop = next.next;
+      continue;
+    }
+    ear = next;
+    if (ear === stop) {
+      if (pass === 0) earcut(filterPoints(ear), out, 1);
+      else if (pass === 1) earcut(cureLocalIntersections(filterPoints(ear), out), out, 2);
+      else if (pass === 2) splitEarcut(ear, out);
+      return;
+    }
+  }
+}
+function filterPoints(start) {
+  let p = start;
+  let end = start;
+  let again;
+  do {
+    again = false;
+    if (p.x === p.next.x && p.y === p.next.y || area2(p.prev, p, p.next) === 0) {
+      remove(p);
+      p = end = p.prev;
+      if (p === p.next) break;
+      again = true;
+    } else p = p.next;
+  } while (again || p !== end);
+  return end;
+}
+function intersects(p1, q1, p2, q2) {
+  const o1 = Math.sign(area2(p1, q1, p2));
+  const o2 = Math.sign(area2(p1, q1, q2));
+  const o3 = Math.sign(area2(p2, q2, p1));
+  const o4 = Math.sign(area2(p2, q2, q1));
+  return o1 !== o2 && o3 !== o4;
+}
+function locallyInside(a, b) {
+  return area2(a.prev, a, a.next) < 0 ? area2(a, b, a.next) >= 0 && area2(a, a.prev, b) >= 0 : area2(a, b, a.prev) < 0 || area2(a, a.next, b) < 0;
+}
+function cureLocalIntersections(start, out) {
+  let p = start;
+  do {
+    const a = p.prev;
+    const b = p.next.next;
+    if (!(a.x === b.x && a.y === b.y) && intersects(a, p, p.next, b) && locallyInside(a, b) && locallyInside(b, a)) {
+      out.push(a.i, p.i, b.i);
+      remove(p);
+      remove(p.next);
+      p = start = b;
+    }
+    p = p.next;
+  } while (p !== start);
+  return filterPoints(p);
+}
+function middleInside(a, b) {
+  let p = a;
+  let inside = false;
+  const px = (a.x + b.x) / 2;
+  const py = (a.y + b.y) / 2;
+  do {
+    if (p.y > py !== p.next.y > py && p.next.y !== p.y && px < (p.next.x - p.x) * (py - p.y) / (p.next.y - p.y) + p.x)
+      inside = !inside;
+    p = p.next;
+  } while (p !== a);
+  return inside;
+}
+function intersectsPolygon(a, b) {
+  let p = a;
+  do {
+    if (p.i !== a.i && p.next.i !== a.i && p.i !== b.i && p.next.i !== b.i && intersects(p, p.next, a, b))
+      return true;
+    p = p.next;
+  } while (p !== a);
+  return false;
+}
+function isValidDiagonal(a, b) {
+  return a.next.i !== b.i && a.prev.i !== b.i && !intersectsPolygon(a, b) && locallyInside(a, b) && locallyInside(b, a) && middleInside(a, b);
+}
+function splitPolygon(a, b) {
+  const a2 = { i: a.i, x: a.x, y: a.y, gone: false };
+  const b2 = { i: b.i, x: b.x, y: b.y, gone: false };
+  const an = a.next;
+  const bp = b.prev;
+  a.next = b;
+  b.prev = a;
+  a2.next = an;
+  an.prev = a2;
+  b2.next = a2;
+  a2.prev = b2;
+  bp.next = b2;
+  b2.prev = bp;
+  return b2;
+}
+function splitEarcut(start, out) {
+  let a = start;
+  do {
+    let b = a.next.next;
+    while (b !== a.prev) {
+      if (a.i !== b.i && isValidDiagonal(a, b)) {
+        let c = splitPolygon(a, b);
+        a = filterPoints(a);
+        c = filterPoints(c);
+        earcut(a, out, 0);
+        earcut(c, out, 0);
+        return;
+      }
+      b = b.next;
+    }
+    a = a.next;
+  } while (a !== start);
+}
+function eliminateHoles(points, holes, outer, count) {
+  const queue = [];
+  for (let h = 0; h < holes.length; h++) {
+    const start = holes[h];
+    const end = h + 1 < holes.length ? holes[h + 1] : count;
+    const list = ring(points, start, end, false);
+    if (!list) continue;
+    let left = list;
+    let p = list;
+    do {
+      if (p.x < left.x || p.x === left.x && p.y < left.y) left = p;
+      p = p.next;
+    } while (p !== list);
+    queue.push(left);
+  }
+  queue.sort((a, b) => a.x - b.x || a.y - b.y);
+  for (const hole of queue) outer = filterPoints(eliminateHole(hole, outer));
+  return outer;
+}
+function eliminateHole(hole, outer) {
+  const bridge = findHoleBridge(hole, outer);
+  if (!bridge) return outer;
+  const reverse = splitPolygon(bridge, hole);
+  filterPoints(reverse);
+  return filterPoints(bridge);
+}
+function findHoleBridge(hole, outer) {
+  let p = outer;
+  const hx = hole.x;
+  const hy = hole.y;
+  let qx = -Infinity;
+  let m;
+  do {
+    if (hy <= p.y && hy >= p.next.y && p.next.y !== p.y) {
+      const x = p.x + (hy - p.y) * (p.next.x - p.x) / (p.next.y - p.y);
+      if (x <= hx && x > qx) {
+        qx = x;
+        m = p.x < p.next.x ? p : p.next;
+        if (x === hx) return m;
+      }
+    }
+    p = p.next;
+  } while (p !== outer);
+  if (!m) return void 0;
+  const stop = m;
+  const mx = m.x;
+  const my = m.y;
+  let tanMin = Infinity;
+  p = m;
+  do {
+    if (hx >= p.x && p.x >= mx && hx !== p.x && pointInTriangle(hy < my ? hx : qx, hy, mx, my, hy < my ? qx : hx, hy, p.x, p.y)) {
+      const tan = Math.abs(hy - p.y) / (hx - p.x);
+      if (locallyInside(p, hole) && (tan < tanMin || tan === tanMin && (p.x > m.x || p.x === m.x && sectorContainsSector(m, p)))) {
+        m = p;
+        tanMin = tan;
+      }
+    }
+    p = p.next;
+  } while (p !== stop);
+  return m;
+}
+function sectorContainsSector(m, p) {
+  return area2(m.prev, m, p.prev) < 0 && area2(p.next, m, m.next) < 0;
+}
+function clipToRect(src, n, minX, minY, maxX, maxY, out, scratch) {
+  let count = clipEdge(src, n, scratch, 0, minX, 1);
+  count = clipEdge(scratch, count, out, 0, maxX, -1);
+  count = clipEdge(out, count, scratch, 1, minY, 1);
+  count = clipEdge(scratch, count, out, 1, maxY, -1);
+  return count;
+}
+function clipEdge(src, n, dst, axis, at, sign) {
+  let count = 0;
+  if (n === 0) return 0;
+  let px = src[(n - 1) * 2];
+  let py = src[(n - 1) * 2 + 1];
+  let pd = sign * ((axis === 0 ? px : py) - at);
+  for (let i = 0; i < n; i++) {
+    const x = src[i * 2];
+    const y = src[i * 2 + 1];
+    const d = sign * ((axis === 0 ? x : y) - at);
+    if (d >= 0) {
+      if (pd < 0) {
+        const t = pd / (pd - d);
+        dst[count * 2] = px + (x - px) * t;
+        dst[count * 2 + 1] = py + (y - py) * t;
+        count++;
+      }
+      dst[count * 2] = x;
+      dst[count * 2 + 1] = y;
+      count++;
+    } else if (pd >= 0) {
+      const t = pd / (pd - d);
+      dst[count * 2] = px + (x - px) * t;
+      dst[count * 2 + 1] = py + (y - py) * t;
+      count++;
+    }
+    px = x;
+    py = y;
+    pd = d;
+  }
+  return count;
+}
+export {
+  clipToRect,
+  signedArea,
+  trianglesArea,
+  triangulate
+};

package/dist/schema/component.d.ts

@@ -25,6 +25,12 @@ export interface ComponentOptions {
      * rebuilds itself, or that belongs to the session rather than the playthrough.
      */
     save?: boolean;
+    /**
+     * Only host code holding a grant writes it (ownership, 0061). Scene files, prefabs and the
+     * protocol refuse it, and `world.add`, `set` and `remove` throw `core/owner-not-authorable`
+     * outside the grant. Implies `serialize: false`.
+     */
+    hostOnly?: boolean;
 }
 export interface ComponentDef<F extends Fields = Fields> {
     readonly kind: 'component';
@@ -43,6 +49,8 @@ export interface ComponentDef<F extends Fields = Fields> {
     readonly serializable: boolean;
     /** Whether saved games include it: serializable, and not `save: false`. */
     readonly saved: boolean;
+    /** Written only by host code holding a grant (0061). */
+    readonly hostOnly: boolean;
     defaults(): InferFields<F>;
     serialize(value: InferFields<F>): JsonObject;
     /** Validates, then converts. Throws the first validation error. */

package/dist/schema/component.js

@@ -76,8 +76,9 @@ function buildSchema(name, fields, options, reuseId) {
     version,
     layout,
     requires: options.requires ?? [],
-    serializable: options.serialize ?? true,
-    saved: (options.serialize ?? true) && (options.save ?? true),
+    serializable: !options.hostOnly && (options.serialize ?? true),
+    saved: !options.hostOnly && (options.serialize ?? true) && (options.save ?? true),
+    hostOnly: options.hostOnly ?? false,
     defaults: () => defaultsOf(fields),
     serialize: (value) => objectToJson(fields, value),
     deserialize(json, ctx) {

package/dist/schema/field.d.ts

@@ -28,6 +28,18 @@ export interface FieldOptions<V> {
      * resolves to the number on load. The JSON Schema lists the names as alternatives.
      */
     presets?: Readonly<Record<string, number>>;
+    /**
+     * `false`: data only the host reads, kept out of GPU structs (`wgslLayout`), so adding such a
+     * field changes no shader.
+     */
+    gpu?: boolean;
+    /**
+     * Struct fields: the WGSL struct GPU structs (`wgslLayout`) pack it as, `module::path::Name`.
+     * That module declares it from the same fields. Without it a struct isn't GPU data.
+     */
+    wgsl?: string;
+    /** Sample values (presets), listed as the JSON Schema's `examples`. */
+    examples?: readonly V[];
 }
 /** A reference to an asset. `guid` is the identity; `path` is for readers. */
 export interface AssetRef<T extends string = string> {

package/dist/schema/field.js

@@ -55,6 +55,7 @@ function makeField(spec) {
     ...spec,
     jsonSchema: () => ({
       ...baseSchema(spec.options, spec.toJson(spec.defaultValue())),
+      ...spec.options.examples ? { examples: spec.options.examples.map(spec.toJson) } : {},
       ...spec.schema()
     })
   };

package/dist/schema/resource.d.ts

@@ -19,6 +19,13 @@ export interface ResourceDef<T> {
     readonly schema: ComponentDef | undefined;
     /** Saved games include it (0038). Needs `schema`. */
     readonly persist: boolean;
+    /**
+     * Host code (UI, protocol handlers) writes it between frames, through `world.patchResource` or
+     * `world.touchResource` (0052). The on-demand runner's write check watches it.
+     */
+    readonly hostWritable: boolean;
+    /** Only host code writes it: the protocol's `resource.set` refuses it (ownership, 0061). */
+    readonly hostOnly: boolean;
     readonly __type?: T;
 }
 export interface ResourceOptions<T> {
@@ -27,6 +34,8 @@ export interface ResourceOptions<T> {
     reload?: 'keep' | 'replace';
     schema?: ComponentDef;
     persist?: boolean;
+    hostWritable?: boolean;
+    hostOnly?: boolean;
 }
 export declare function defineResource<T>(name: string, options?: ResourceOptions<T>): ResourceDef<T>;
 /** Every resource defined in this process (latest definitions), sorted by name. */

package/dist/schema/resource.js

@@ -21,7 +21,9 @@ function defineResource(name, options = {}) {
     init: options.init,
     reload: options.reload ?? "keep",
     schema: options.schema,
-    persist: options.persist ?? false
+    persist: options.persist ?? false,
+    hostWritable: options.hostWritable ?? false,
+    hostOnly: options.hostOnly ?? false
   };
   resources.set(name, def);
   if (previous) {

package/dist/test-env.d.ts

@@ -1,16 +1,20 @@
 /**
- * How strict tests are about time, in one place.
+ * How strict tests are about time, in one place. Two tiers:
  *
- * - `pnpm bench` (`SHARD_BENCH`) holds the exact budgets from the specs, one file at a time.
- * - `pnpm test` allows 3×, for a machine busy running test files in parallel.
- * - CI (`SHARD_CI`) checks correctness only. Shared runners render with a software GPU, so their
- *   timings say nothing about the engine; budgets are unlimited there and timeouts are 5× longer.
+ * - `pnpm bench` (`SHARD_BENCH`) checks performance: the exact budgets from the specs and
+ *   "allocates nothing", one file at a time on a machine doing nothing else.
+ * - `pnpm test`, locally and in CI (`SHARD_CI`), checks correctness only. Parallel files share the
+ *   CPU and GPU, and CI renders on a software GPU, so wall-clock timings there say nothing about the
+ *   engine: budgets are unlimited and allocation checks are off. Timeouts are 5× longer in CI.
+ *
+ * Write every timing assertion through `budget()`, `slack` or `allocationChecks`, and it lands in
+ * the right tier.
  */
 export type TimingMode = 'bench' | 'test' | 'ci';
 export declare const timingMode: TimingMode;
-/** The factor budgets are multiplied by (and rate floors divided by) in this mode. */
+/** The factor budgets are multiplied by (and rate floors divided by): 1 under `pnpm bench`, else ∞. */
 export declare const slack: number;
-/** A time budget in ms: exact under `pnpm bench`, 3× in `pnpm test`, unlimited in CI. */
+/** A time budget in ms: exact under `pnpm bench`, unlimited in `pnpm test` and CI. */
 export declare function budget(ms: number): number;
 /** A test or hook timeout in ms: 5× in CI, unchanged everywhere else. */
 export declare function timeout(ms: number): number;
@@ -24,8 +28,7 @@ export declare function gcWindow(): {
     end(): Promise<number>;
 };
 /**
- * Whether "allocates nothing" checks run. They hold under `pnpm bench` and `pnpm test`; CI turns them
- * off with the time budgets, since when V8 optimizes (and so whether a call boxes its result) depends
- * on the runner's CPU and timing.
+ * Whether "allocates nothing" checks run: under `pnpm bench` only. When V8 optimizes (and so whether
+ * a call boxes its result) depends on the CPU and on what else is running.
  */
 export declare const allocationChecks: boolean;

package/dist/test-env.js

@@ -1,6 +1,6 @@
 const env = globalThis.process?.env ?? {};
 const timingMode = env.SHARD_BENCH ? "bench" : env.SHARD_CI ? "ci" : "test";
-const slack = timingMode === "bench" ? 1 : timingMode === "test" ? 3 : Number.POSITIVE_INFINITY;
+const slack = timingMode === "bench" ? 1 : Number.POSITIVE_INFINITY;
 function budget(ms) {
   return ms * slack;
 }
@@ -26,7 +26,7 @@ function gcWindow() {
     }
   };
 }
-const allocationChecks = timingMode !== "ci";
+const allocationChecks = timingMode === "bench";
 export {
   allocationChecks,
   budget,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aethervtt/shard-core",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -33,6 +33,6 @@
     "provenance": true
   },
   "shard": {
-    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+    "buildSha": "8e14c9896f82a3554b156f1ffdd68f2cc3e7d78a"
   }
 }