@forgeax/engine-render 0.1.33 → 0.1.34

package/src/scene/probe-blend.ts

@@ -31,6 +31,27 @@ export interface ProbeSceneObjectInput {
   readonly position: readonly [number, number, number];
 }
 
+export interface ProbeBlendBufferProjection {
+  /** Stable producer identity; dirty evidence is never portable across producers. */
+  readonly sourceIdentity: object;
+  readonly revision: number;
+  /** Exact accepted revision from which dirty/removed evidence was derived. */
+  readonly baseRevision: number;
+  /** Producer-computed lane capacity, including the slot-zero sentinel. */
+  readonly capacity: number;
+  readonly records: readonly {
+    readonly cacheKey: number;
+    readonly record: ProbeBlendRecord;
+  }[];
+  /** Records whose generation or payload changed at this revision. */
+  readonly dirtyRecords: readonly {
+    readonly cacheKey: number;
+    readonly record: ProbeBlendRecord;
+  }[];
+  /** Cache keys retired at this revision. */
+  readonly removedCacheKeys: readonly number[];
+}
+
 export interface ProbeSceneProbeInput {
   readonly identity: string;
   readonly position: readonly [number, number, number];
@@ -68,6 +89,8 @@ export interface ProbeAdmissionResult {
 export interface ProbeSceneProjectionInput {
   readonly objects: readonly ProbeSceneObjectInput[];
   readonly probes: readonly ProbeSceneProbeInput[];
+  /** Keep explicit zero-local rows for consumers whose published ABI always reads this page. */
+  readonly retainSkyResidualRecords?: boolean;
   /** Optional analytic oracle input; records never store or replace Sky. */
   readonly skyIrradiance?: readonly [number, number, number];
   readonly sky?: {
@@ -549,6 +572,17 @@ export class ProbeBlendSceneProjection {
   };
   private lastDirtyVisitCount = 0;
   private lastDirtyReasons: readonly ProbeSceneDirtyReason[] = [];
+  private readonly bufferProjectionSource = Object.freeze({});
+  private bufferProjection: ProbeBlendBufferProjection = Object.freeze({
+    sourceIdentity: this.bufferProjectionSource,
+    revision: 0,
+    baseRevision: 0,
+    capacity: 1,
+    records: Object.freeze([]),
+    dirtyRecords: Object.freeze([]),
+    removedCacheKeys: Object.freeze([]),
+  });
+  private resultRecords: readonly ProbeBlendRecord[] = Object.freeze([]);
   private recordFacts = new Map<
     number,
     {
@@ -567,6 +601,11 @@ export class ProbeBlendSceneProjection {
     return this.records.size > 0;
   }
 
+  /** Stable upload projection; rebuilt only when probe/object facts change. */
+  recordBufferProjection(): ProbeBlendBufferProjection {
+    return this.bufferProjection;
+  }
+
   inspect(): ProbeBlendInspection {
     return {
       activeContributorCount: this.lastActiveContributorCount,
@@ -628,6 +667,30 @@ export class ProbeBlendSceneProjection {
     const dirtyReasons: ProbeSceneDirtyReason[] = [];
     const affectedObjectKeys = new Set<number>();
     const previous = this.previous;
+    if (
+      previous !== undefined &&
+      previous.objects === input.objects &&
+      input.worldRevision === previous.worldRevision &&
+      input.retainSkyResidualRecords === previous.retainSkyResidualRecords &&
+      sameProbeFacts(input.probes, previous.probes) &&
+      sameSkyFacts(input, previous)
+    ) {
+      return {
+        records: this.resultRecords,
+        contributors: [],
+        activeContributorCount: this.lastActiveContributorCount,
+        admittedProbeCount: this.lastAdmittedProbeCount,
+        coverage: this.lastCoverage,
+        skyResidualFraction: 1 - this.lastCoverage,
+        dirtyReasons: [],
+        affectedObjectKeys: [],
+        visits: 0,
+        allocations: 0,
+        uploads: 0,
+        receipt: this.lastReceipt,
+        ...(this.lastError === undefined ? {} : { error: this.lastError }),
+      };
+    }
     const objectKeys = input.objects.map((object) => String(object.objectKey)).sort();
     const previousObjectKeys =
       previous?.objects.map((object) => String(object.objectKey)).sort() ?? [];
@@ -637,7 +700,11 @@ export class ProbeBlendSceneProjection {
     }
     if (previous !== undefined && input.worldRevision !== previous.worldRevision)
       dirtyReasons.push('world');
-    if (previous !== undefined && !sameProbeFacts(input.probes, previous.probes))
+    if (
+      previous !== undefined &&
+      (!sameProbeFacts(input.probes, previous.probes) ||
+        input.retainSkyResidualRecords !== previous.retainSkyResidualRecords)
+    )
       dirtyReasons.push('probe-fact');
     if (previous !== undefined && !sameSkyFacts(input, previous)) dirtyReasons.push('sky');
     const previousObjects = new Map(previous?.objects.map((object) => [object.objectKey, object]));
@@ -718,7 +785,7 @@ export class ProbeBlendSceneProjection {
       let record: ProbeBlendRecord;
       if (admission.error !== undefined) firstError ??= admission.error;
       if (admission.admitted.length === 0) {
-        if (input.probes.length === 0) {
+        if (input.probes.length === 0 && input.retainSkyResidualRecords !== true) {
           nextRecords.delete(object.objectKey);
           this.recordFacts.delete(object.objectKey);
           continue;
@@ -776,8 +843,9 @@ export class ProbeBlendSceneProjection {
       firstError ??= admission.error;
     }
     const allocations = previous === undefined ? nextRecords.size : 0;
+    const resultRecords = Object.freeze([...nextRecords.values()]);
     const result = {
-      records: [...nextRecords.values()],
+      records: resultRecords,
       contributors: firstTerms,
       activeContributorCount: firstActiveCount,
       admittedProbeCount: firstAdmittedCount,
@@ -791,14 +859,38 @@ export class ProbeBlendSceneProjection {
       receipt: firstReceipt,
       ...(firstError === undefined ? {} : { error: firstError }),
     };
+    const projectedRecords = Object.freeze(
+      [...nextRecords].map(([objectKey, record]) => Object.freeze({ cacheKey: objectKey, record })),
+    );
+    const dirtyRecords = Object.freeze(
+      projectedRecords.filter(({ record }) => affectedObjectKeys.has(record.objectKey)),
+    );
+    const removedCacheKeys = Object.freeze(
+      [...this.records.keys()].filter((objectKey) => !nextRecords.has(objectKey)),
+    );
+    const capacity = projectedRecords.reduce(
+      (value, { record }) => Math.max(value, record.objectKey + 2),
+      1,
+    );
     this.previous = input;
     this.records = nextRecords;
+    this.resultRecords = resultRecords;
+    const baseRevision = this.bufferProjection.revision;
+    this.bufferProjection = Object.freeze({
+      sourceIdentity: this.bufferProjectionSource,
+      revision: baseRevision + 1,
+      baseRevision,
+      capacity,
+      records: projectedRecords,
+      dirtyRecords,
+      removedCacheKeys,
+    });
     this.lastError = firstError;
     this.lastReceipt = firstReceipt;
     this.lastActiveContributorCount = firstActiveCount;
     this.lastAdmittedProbeCount = firstAdmittedCount;
     this.lastCoverage = firstCoverage;
-    this.lastFinite = [...nextRecords.values()].every(
+    this.lastFinite = this.resultRecords.every(
       (record) => record.bytes.length === PROBE_BLEND_RECORD_BYTE_SIZE,
     );
     this.lastSky =