@aethervtt/shard-core 0.0.1 → 0.2.0

package/dist/scheduler/profiler.js

@@ -1,22 +1,281 @@
+import { ShardError } from "../error.js";
 import { defineResource } from "../schema/resource.js";
+function defineSpan(name) {
+  return { name, id: -1 };
+}
+const TRACK = { main: 0, gpu: 1, async: 2, gc: 3, worker: 4 };
+function trackName(track) {
+  if (track === TRACK.main) return "main";
+  if (track === TRACK.gpu) return "gpu";
+  if (track === TRACK.async) return "async";
+  if (track === TRACK.gc) return "gc";
+  return "worker";
+}
+function spanCovers(key, name) {
+  if (name === key) return true;
+  const n = key.length;
+  if (n === 0 || name.length <= n || !name.startsWith(key)) return false;
+  return key.charCodeAt(n - 1) === SLASH || name.charCodeAt(n) === SLASH;
+}
+const SLASH = 47;
+const MAX_SPANS = 65536;
+const MAX_DEPTH = 64;
+const ASYNC_SLOTS = 256;
+const spanNames = [];
+const spanTracks = [];
+const spanIds = /* @__PURE__ */ new Map();
+function internSpan(name, track = defaultTrack(name)) {
+  const known = spanIds.get(name);
+  if (known !== void 0) return known;
+  const id = spanNames.length;
+  if (id >= MAX_SPANS) {
+    throw new ShardError("perf/too-many-spans", `More than ${MAX_SPANS} span names`, {
+      hint: 'Span names are fixed strings (e.g. "terrain/encode"), not per-entity or per-frame text.'
+    });
+  }
+  spanNames.push(name);
+  spanTracks.push(track);
+  spanIds.set(name, id);
+  return id;
+}
+function spanCount() {
+  return spanNames.length;
+}
+function spanId(name) {
+  return spanIds.get(name) ?? -1;
+}
+function spanName(id) {
+  return spanNames[id] ?? `span#${id}`;
+}
+function spanTrack(id) {
+  return spanTracks[id] ?? TRACK.main;
+}
+function defaultTrack(name) {
+  if (name.startsWith("gpu:")) return TRACK.gpu;
+  if (name.startsWith("worker/")) return TRACK.worker;
+  if (name === "gc" || name.startsWith("gc/")) return TRACK.gc;
+  return TRACK.main;
+}
+function idOf(span, track) {
+  if (typeof span === "string") return spanIds.get(span) ?? internSpan(span, track);
+  let id = span.id;
+  if (id < 0) {
+    id = internSpan(span.name, track);
+    span.id = id;
+  }
+  return id;
+}
+const ProfilerSettings = defineResource("core/ProfilerSettings", {
+  description: "Turns the profiler (0074) on or off, and how many runs its aggregates cover. Off, spans cost a branch.",
+  hostWritable: true,
+  init: () => ({ enabled: true, window: 120 })
+});
+const host = globalThis;
+function defaultNow() {
+  return host.performance ? host.performance.now() : Date.now();
+}
+let measuredClock;
+function clockInfo() {
+  if (measuredClock) return measuredClock;
+  let resolution = Number.POSITIVE_INFINITY;
+  let prev = defaultNow();
+  let steps = 0;
+  for (let i = 0; i < 2e6 && steps < 20; i++) {
+    const t = defaultNow();
+    if (t !== prev) {
+      if (t - prev < resolution) resolution = t - prev;
+      prev = t;
+      steps++;
+    }
+  }
+  const isolated = host.document === void 0 ? true : host.crossOriginIsolated === true;
+  measuredClock = {
+    resolutionMs: Number.isFinite(resolution) ? Math.round(resolution * 1e6) / 1e6 : 0,
+    isolated
+  };
+  return measuredClock;
+}
 class Profiler {
-  window;
-  series = /* @__PURE__ */ new Map();
-  constructor(window = 120) {
-    this.window = window;
+  settings;
+  /** The clock, in ms. */
+  now;
+  /** Receives every span while a capture runs. */
+  sink;
+  /** Gets `perf/span-mismatch` and similar warnings; the app logs them. */
+  onWarning;
+  /** `Time.frame` of the frame running now (or that ran last). */
+  frame = 0;
+  /** The last span `end` measured, in ms. */
+  lastMs = 0;
+  /** What the renderer said about GPU timing: `unavailable` without timestamp queries. */
+  gpu = {
+    status: "unknown",
+    quantized: false
+  };
+  windowSize;
+  series = [];
+  stackIds = new Int32Array(MAX_DEPTH);
+  stackStarts = new Float64Array(MAX_DEPTH);
+  depth = 0;
+  frameStartAt = 0;
+  warned = new Uint8Array(256);
+  asyncIds = new Int32Array(ASYNC_SLOTS).fill(-1);
+  asyncKeys = new Array(ASYNC_SLOTS);
+  asyncStarts = new Float64Array(ASYNC_SLOTS);
+  asyncCount = 0;
+  frameSpan = defineSpan("frame");
+  constructor(options = {}) {
+    const o = typeof options === "number" ? { settings: { enabled: true, window: options } } : options;
+    this.settings = o.settings ?? { enabled: true, window: 120 };
+    this.now = o.now ?? defaultNow;
+    this.windowSize = Math.max(1, this.settings.window | 0);
+  }
+  get window() {
+    return this.windowSize;
+  }
+  get enabled() {
+    return this.settings.enabled;
   }
-  record(name, ms) {
-    let series = this.series.get(name);
-    if (!series) {
-      series = { samples: new Float64Array(this.window), cursor: 0, count: 0 };
-      this.series.set(name, series);
+  // --- spans -------------------------------------------------------------------
+  /** Starts a span on the main track. Returns a token for `end`; -1 when the profiler is off. */
+  begin(span) {
+    if (!this.settings.enabled) return -1;
+    const id = span.id >= 0 ? span.id : idOf(span, TRACK.main);
+    const d = this.depth;
+    if (d >= MAX_DEPTH) {
+      this.warn(id, WARN_DEPTH);
+      return -1;
     }
-    series.samples[series.cursor] = ms;
-    series.cursor = (series.cursor + 1) % this.window;
-    if (series.count < this.window) series.count++;
+    this.stackIds[d] = id;
+    this.depth = d + 1;
+    this.stackStarts[d] = this.now();
+    return d * MAX_SPANS + id;
+  }
+  /** Ends the span `begin` returned `token` for, recording it. */
+  end(token) {
+    if (token < 0) return;
+    const at = this.now();
+    const d = token / MAX_SPANS | 0;
+    const id = token - d * MAX_SPANS;
+    if (d !== this.depth - 1 || this.stackIds[d] !== id) {
+      this.warn(id, WARN_ORDER);
+      if (d >= this.depth || this.stackIds[d] !== id) return;
+    }
+    this.depth = d;
+    const start = this.stackStarts[d];
+    const ms = at - start;
+    this.lastMs = ms;
+    this.push(id, ms);
+    const sink = this.sink;
+    if (sink !== void 0) sink.event(id, TRACK.main, d, start, ms, -1);
   }
+  /** Drops the span `token` and everything begun inside it, recording nothing (an exception unwound it). */
+  cancel(token) {
+    if (token < 0) return;
+    const d = token / MAX_SPANS | 0;
+    if (d < this.depth) this.depth = d;
+  }
+  /**
+   * Time measured elsewhere (a GPU pass, a worker job): its aggregate, and a timeline event on
+   * `track` that ended now, or started at `start`. `frame`: the frame it belongs to, when it lands
+   * later (GPU timings).
+   */
+  record(span, ms, track, start, frame = -1) {
+    if (!this.settings.enabled) return;
+    const id = idOf(span, track);
+    this.push(id, ms);
+    const sink = this.sink;
+    if (sink !== void 0) {
+      const t = track ?? spanTracks[id];
+      sink.event(id, t, t === TRACK.main ? this.depth : 0, start ?? this.now() - ms, ms, frame);
+    }
+  }
+  /** Only the aggregate (`render/<node>` sums its views into one sample a frame). */
+  sample(span, ms) {
+    if (!this.settings.enabled) return;
+    this.push(idOf(span), ms);
+  }
+  /** Only the timeline event, when a capture runs. */
+  event(span, track, start, ms, frame = -1) {
+    const sink = this.sink;
+    if (sink === void 0 || !this.settings.enabled) return;
+    sink.event(idOf(span, track), track, track === TRACK.main ? this.depth : 0, start, ms, frame);
+  }
+  /** Whether a capture is listening (callers skip work that only feeds the timeline). */
+  get capturing() {
+    return this.sink !== void 0;
+  }
+  /**
+   * Work that starts in one frame and ends in another (an asset load, a page fetch): an async span,
+   * matched to its `endAsync` by span and key.
+   */
+  beginAsync(span, key) {
+    if (!this.settings.enabled) return;
+    const id = span.id >= 0 ? span.id : idOf(span, TRACK.async);
+    if (this.asyncCount >= ASYNC_SLOTS) {
+      this.warn(id, WARN_ASYNC);
+      return;
+    }
+    for (let i = 0; i < ASYNC_SLOTS; i++) {
+      if (this.asyncIds[i] !== -1) continue;
+      this.asyncIds[i] = id;
+      this.asyncKeys[i] = key;
+      this.asyncStarts[i] = this.now();
+      this.asyncCount++;
+      return;
+    }
+  }
+  endAsync(span, key) {
+    if (!this.settings.enabled || span.id < 0 || this.asyncCount === 0) return;
+    const id = span.id;
+    for (let i = 0; i < ASYNC_SLOTS; i++) {
+      if (this.asyncIds[i] !== id || this.asyncKeys[i] !== key) continue;
+      const start = this.asyncStarts[i];
+      const ms = this.now() - start;
+      this.asyncIds[i] = -1;
+      this.asyncKeys[i] = void 0;
+      this.asyncCount--;
+      this.push(id, ms);
+      const sink = this.sink;
+      if (sink !== void 0) sink.event(id, TRACK.async, 0, start, ms, -1);
+      return;
+    }
+  }
+  // --- frames ------------------------------------------------------------------
+  /**
+   * A frame starts: spans left open from before are dropped (and reported once), and the `frame`
+   * span begins. Returns its token for `endFrame`.
+   */
+  beginFrame(frame) {
+    if (!this.settings.enabled) return -1;
+    if (this.depth > 0) {
+      const id = this.stackIds[this.depth - 1];
+      this.warn(id, WARN_OPEN_AT_START);
+      this.depth = 0;
+    }
+    if (this.settings.window !== this.windowSize) this.resize();
+    this.frame = frame;
+    const token = this.begin(this.frameSpan);
+    this.frameStartAt = this.stackStarts[0];
+    const sink = this.sink;
+    if (sink !== void 0) sink.frameStart(frame, this.frameStartAt);
+    return token;
+  }
+  endFrame(token) {
+    if (token < 0) return;
+    if (this.depth > 1) {
+      const id = this.stackIds[this.depth - 1];
+      this.warn(id, WARN_OPEN_AT_END);
+      this.depth = 1;
+    }
+    this.end(token);
+    const sink = this.sink;
+    if (sink !== void 0) sink.frameEnd(this.frame, this.lastMs);
+  }
+  // --- reading -----------------------------------------------------------------
   timing(name) {
-    const series = this.series.get(name);
+    const id = spanIds.get(name);
+    const series = id === void 0 ? void 0 : this.series[id];
     if (!series || series.count === 0) return void 0;
     let sum = 0;
     let max = 0;
@@ -25,20 +284,174 @@ class Profiler {
       sum += v;
       if (v > max) max = v;
     }
-    const last = series.samples[(series.cursor - 1 + this.window) % this.window];
+    const last = series.samples[(series.cursor - 1 + this.windowSize) % this.windowSize];
     return { last, avg: sum / series.count, max, samples: series.count };
   }
+  /** A span's samples over the window, in ring order (not by age); undefined if it never ran. */
+  samples(name) {
+    const id = spanIds.get(name);
+    const series = id === void 0 ? void 0 : this.series[id];
+    return series?.count ? series.samples.subarray(0, series.count) : void 0;
+  }
+  /** Every span that ran, by name. */
   all() {
     const out = {};
-    for (const name of this.series.keys()) out[name] = this.timing(name);
+    for (let id = 0; id < this.series.length; id++) {
+      if (!this.series[id]?.count) continue;
+      const name = spanNames[id];
+      out[name] = this.timing(name);
+    }
+    return out;
+  }
+  /**
+   * How many samples a span has had since the profiler started (or its aggregates were reset), by
+   * id: 0 if none. Allocates nothing, for per-frame readers such as feature budgets (0075).
+   */
+  runsOf(id) {
+    return this.series[id]?.total ?? 0;
+  }
+  /**
+   * The span that was open around a span's latest sample (its parent on the main track), by id, or
+   * -1: what lets aggregates count time two covering keys share once (0075's slices).
+   */
+  parentOf(id) {
+    return this.series[id]?.parent ?? -1;
+  }
+  /** A span's latest sample in ms, by id, or 0 if it has none. Allocates nothing. */
+  lastOf(id) {
+    const series = this.series[id];
+    if (series === void 0 || series.count === 0) return 0;
+    return series.samples[(series.cursor - 1 + this.windowSize) % this.windowSize];
+  }
+  /** Names of every span with samples. */
+  names() {
+    const out = [];
+    for (let id = 0; id < this.series.length; id++)
+      if (this.series[id]?.count) out.push(spanNames[id]);
     return out;
   }
+  /** Forgets every aggregate (`perf.reset`). */
+  reset() {
+    for (const series of this.series) {
+      if (!series) continue;
+      series.count = 0;
+      series.cursor = 0;
+      series.total = 0;
+    }
+  }
+  // --- internals ---------------------------------------------------------------
+  push(id, ms) {
+    let series = this.series[id];
+    if (series === void 0) series = this.createSeries(id);
+    series.samples[series.cursor] = ms;
+    series.cursor = series.cursor + 1 === this.windowSize ? 0 : series.cursor + 1;
+    if (series.count < this.windowSize) series.count++;
+    series.total++;
+    series.parent = this.depth > 0 ? this.stackIds[this.depth - 1] : -1;
+  }
+  createSeries(id) {
+    while (this.series.length <= id) this.series.push(void 0);
+    const series = {
+      samples: new Float64Array(this.windowSize),
+      cursor: 0,
+      count: 0,
+      total: 0,
+      parent: -1
+    };
+    this.series[id] = series;
+    return series;
+  }
+  resize() {
+    this.windowSize = Math.max(1, this.settings.window | 0);
+    for (let id = 0; id < this.series.length; id++) {
+      if (this.series[id])
+        this.series[id] = {
+          samples: new Float64Array(this.windowSize),
+          cursor: 0,
+          count: 0,
+          total: this.series[id].total,
+          parent: this.series[id].parent
+        };
+    }
+  }
+  /** Reports a problem once per span name. */
+  warn(id, kind) {
+    if (id >= this.warned.length) {
+      const grown = new Uint8Array(Math.max(id + 1, this.warned.length * 2));
+      grown.set(this.warned);
+      this.warned = grown;
+    }
+    if (this.warned[id]) return;
+    this.warned[id] = 1;
+    this.onWarning?.(warningOf(kind, spanName(id)));
+  }
+}
+const WARN_ORDER = 0;
+const WARN_OPEN_AT_START = 1;
+const WARN_OPEN_AT_END = 2;
+const WARN_DEPTH = 3;
+const WARN_ASYNC = 4;
+const MISMATCH = [
+  "ended out of order: spans end in the reverse order they began",
+  "was still open when a frame began",
+  "was still open when its frame ended"
+];
+function warningOf(kind, name) {
+  if (kind === WARN_DEPTH) {
+    return new ShardError(
+      "perf/span-overflow",
+      `Spans nest deeper than ${MAX_DEPTH} at "${name}"`,
+      {
+        hint: "A span that begins in a loop needs its end inside the loop too.",
+        path: name
+      }
+    );
+  }
+  if (kind === WARN_ASYNC) {
+    return new ShardError("perf/async-overflow", `More than ${ASYNC_SLOTS} async spans are open`, {
+      hint: "Every beginAsync(span, key) needs an endAsync(span, key), even when the work fails.",
+      path: name
+    });
+  }
+  return new ShardError("perf/span-mismatch", `Span "${name}" ${MISMATCH[kind]}`, {
+    hint: "Every profiler.begin(span) needs one profiler.end(token), in the same frame.",
+    path: name
+  });
+}
+function spanStats(profiler, name) {
+  const timing = profiler.timing(name);
+  const samples = profiler.samples(name);
+  if (!timing || !samples) return void 0;
+  const sorted = Float64Array.from(samples).sort();
+  const at = (p) => sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];
+  const out = {
+    span: name,
+    track: trackName(spanTrack(spanIds.get(name))),
+    ...timing,
+    p50: at(0.5),
+    p95: at(0.95)
+  };
+  const resolution = clockInfo().resolutionMs;
+  if (out.track !== "gpu" && resolution > 0 && timing.avg < 4 * resolution) out.coarse = true;
+  return out;
 }
 const ProfilerResource = defineResource("core/Profiler", {
-  description: "Per-system CPU timings over recent frames.",
+  description: "Span timings (0074): systems, schedules, frames, render passes, GPU and workers.",
   init: () => new Profiler()
 });
 export {
   Profiler,
-  ProfilerResource
+  ProfilerResource,
+  ProfilerSettings,
+  TRACK,
+  clockInfo,
+  defineSpan,
+  internSpan,
+  spanCount,
+  spanCovers,
+  spanId,
+  spanName,
+  spanStats,
+  spanTrack,
+  trackName
 };

package/dist/scheduler/schedule.d.ts

@@ -1,5 +1,5 @@
 import type { World } from '../ecs/world.js';
-import type { Profiler } from './profiler.js';
+import { type Profiler } from './profiler.js';
 import { SystemConfig, type SystemDef, type SystemSetConfig } from './system.js';
 export interface ScheduleLabel {
     readonly kind: 'schedule';
@@ -33,6 +33,10 @@ export interface SystemDescription {
  */
 export declare class Schedule {
     readonly label: ScheduleLabel;
+    /** `schedule/<Label>`: one run of the schedule (0074). */
+    private readonly span;
+    /** `commands/<Label>`: command application over one run. */
+    private readonly commandsSpan;
     private readonly entries;
     private readonly setConfigs;
     private order;

package/dist/scheduler/schedule.js

@@ -1,5 +1,6 @@
 import { Commands } from "../ecs/commands.js";
 import { ShardError } from "../error.js";
+import { defineSpan, TRACK } from "./profiler.js";
 import {
   conditionLabel,
   SystemConfig
@@ -35,16 +36,23 @@ class Context {
 }
 class Schedule {
   label;
+  /** `schedule/<Label>`: one run of the schedule (0074). */
+  span;
+  /** `commands/<Label>`: command application over one run. */
+  commandsSpan;
   entries = [];
   setConfigs = [];
   order;
   constructor(label) {
     this.label = label;
+    this.span = defineSpan(`schedule/${label.name}`);
+    this.commandsSpan = defineSpan(`commands/${label.name}`);
   }
   add(system) {
     const config = system instanceof SystemConfig ? system : new SystemConfig(system);
     this.entries.push({
       config,
+      span: defineSpan(config.system.name),
       index: this.entries.length,
       state: void 0,
       ctx: void 0,
@@ -77,6 +85,9 @@ class Schedule {
   }
   run(world, options) {
     const order = this.resolve();
+    const profiler = options.profiler;
+    const scheduleToken = profiler !== void 0 ? profiler.begin(this.span) : -1;
+    let commandsMs = 0;
     for (let i = 0; i < order.length; i++) {
       const entry = order[i];
       const conditions = entry.conditions;
@@ -95,10 +106,11 @@ class Schedule {
       }
       const ctx = entry.ctx;
       ctx.thisRunTick = world.incrementTick();
-      const start = options.now();
+      const token = profiler !== void 0 ? profiler.begin(entry.span) : -1;
       try {
         system.run(entry.state, world, ctx);
       } catch (err) {
+        profiler?.cancel(scheduleToken);
         const message = err instanceof Error ? err.message : String(err);
         const code = err instanceof ShardError ? ` [${err.code}]` : "";
         throw new ShardError(
@@ -110,10 +122,28 @@ class Schedule {
           }
         );
       }
-      options.profiler?.record(system.name, options.now() - start);
+      if (profiler !== void 0) profiler.end(token);
       ctx.lastRunTick = ctx.thisRunTick;
       world.incrementTick();
-      if (ctx.commands.length > 0) ctx.commands.apply();
+      if (ctx.commands.length > 0) {
+        if (profiler === void 0) ctx.commands.apply();
+        else {
+          const start = profiler.now();
+          try {
+            ctx.commands.apply();
+          } catch (err) {
+            profiler.cancel(scheduleToken);
+            throw err;
+          }
+          const ms = profiler.now() - start;
+          commandsMs += ms;
+          profiler.event(this.commandsSpan, TRACK.main, start, ms);
+        }
+      }
+    }
+    if (profiler !== void 0) {
+      profiler.sample(this.commandsSpan, commandsMs);
+      profiler.end(scheduleToken);
     }
   }
   describe() {

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) {