@vgai/engine 0.5.14 → 0.5.16

package/src/adapter/authoring-seam-contract.ts

@@ -0,0 +1,211 @@
+/** Compiler-derived proof requirements for the AuthoringAdapter protocol.
+ *
+ * This is intentionally adjacent to the interface. Coverage used to enumerate
+ * only top-level provider names, which allowed `{}` to count as a complete
+ * provider. These descriptors cover every nested member and encode the
+ * weakest evidence that can truthfully verify it.
+ */
+
+import type {
+  AssetDropProvider,
+  AssetSubjectProvider,
+  AuthoringAdapter,
+  BoxEditProvider,
+  ColorSampleProvider,
+  ComponentInstancesProvider,
+  HierarchyProvider,
+  InspectorProvider,
+  PersistenceProvider,
+  PickProvider,
+  RectProvider,
+  RelatedSubjectsProvider,
+  SelectionProvider,
+  SpatialHandlesProvider,
+  StoriesProvider,
+  StructureProvider,
+  TextProvider,
+  TransformProvider,
+  TruthProvider,
+} from './authoring';
+import { defineSeamShape, type SeamShape } from './seam-evidence';
+
+export const AUTHORING_ADAPTER_SHAPE = defineSeamShape<AuthoringAdapter>()({
+  capabilities: { optional: false, kind: 'value', required: 'shape' },
+  provenance: { optional: true, kind: 'value', required: 'shape' },
+  hierarchy: { optional: false, kind: 'value', required: 'operation' },
+  selection: { optional: true, kind: 'value', required: 'effect' },
+  transforms: { optional: true, kind: 'value', required: 'effect' },
+  inspector: { optional: true, kind: 'value', required: 'effect' },
+  assetSubject: { optional: true, kind: 'value', required: 'operation' },
+  related: { optional: true, kind: 'value', required: 'operation' },
+  instances: { optional: true, kind: 'value', required: 'effect' },
+  structure: { optional: true, kind: 'value', required: 'round-trip' },
+  persistence: { optional: true, kind: 'value', required: 'round-trip' },
+  pickable: { optional: true, kind: 'value', required: 'operation' },
+  rects: { optional: true, kind: 'value', required: 'operation' },
+  boxEdit: { optional: true, kind: 'value', required: 'effect' },
+  text: { optional: true, kind: 'value', required: 'effect' },
+  colorSample: { optional: true, kind: 'value', required: 'operation' },
+  stories: { optional: true, kind: 'value', required: 'effect' },
+  truth: { optional: true, kind: 'value', required: 'operation' },
+  spatialHandles: { optional: true, kind: 'value', required: 'effect' },
+  assetDrop: { optional: true, kind: 'value', required: 'round-trip' },
+  subscribe: { optional: true, kind: 'function', required: 'effect' },
+  observeTransforms: { optional: true, kind: 'function', required: 'effect' },
+});
+
+export const HIERARCHY_PROVIDER_SHAPE = defineSeamShape<HierarchyProvider>()({
+  roots: { optional: false, kind: 'function', required: 'operation' },
+  node: { optional: false, kind: 'function', required: 'operation' },
+  object3D: { optional: true, kind: 'function', required: 'operation' },
+  idForObject3D: { optional: true, kind: 'function', required: 'effect' },
+});
+
+export const SELECTION_PROVIDER_SHAPE = defineSeamShape<SelectionProvider>()({
+  get: { optional: false, kind: 'function', required: 'operation' },
+  set: { optional: false, kind: 'function', required: 'effect' },
+  resolve: { optional: true, kind: 'function', required: 'operation' },
+});
+
+export const TRANSFORM_PROVIDER_SHAPE = defineSeamShape<TransformProvider>()({
+  dimensions: { optional: true, kind: 'function', required: 'operation' },
+  get: { optional: false, kind: 'function', required: 'operation' },
+  editability: { optional: true, kind: 'function', required: 'operation' },
+  beginEdit: { optional: false, kind: 'function', required: 'effect' },
+  apply: { optional: false, kind: 'function', required: 'effect' },
+  endEdit: { optional: false, kind: 'function', required: 'effect' },
+  remove: { optional: true, kind: 'function', required: 'round-trip' },
+  sourceCommit: { optional: true, kind: 'value', required: 'round-trip' },
+});
+
+export const INSPECTOR_PROVIDER_SHAPE = defineSeamShape<InspectorProvider>()({
+  properties: { optional: false, kind: 'function', required: 'operation' },
+  get: { optional: false, kind: 'function', required: 'operation' },
+  set: { optional: false, kind: 'function', required: 'effect' },
+  editability: { optional: true, kind: 'function', required: 'operation' },
+  remove: { optional: true, kind: 'function', required: 'round-trip' },
+});
+
+export const ASSET_SUBJECT_PROVIDER_SHAPE = defineSeamShape<AssetSubjectProvider>()({
+  get: { optional: false, kind: 'function', required: 'operation' },
+  entries: { optional: true, kind: 'function', required: 'operation' },
+});
+
+export const RELATED_SUBJECTS_PROVIDER_SHAPE = defineSeamShape<RelatedSubjectsProvider>()({
+  links: { optional: false, kind: 'function', required: 'operation' },
+});
+
+export const COMPONENT_INSTANCES_PROVIDER_SHAPE = defineSeamShape<ComponentInstancesProvider>()({
+  describe: { optional: false, kind: 'function', required: 'operation' },
+  openComponent: { optional: true, kind: 'function', required: 'effect' },
+  revert: { optional: false, kind: 'function', required: 'round-trip' },
+  applyToComponent: { optional: false, kind: 'function', required: 'round-trip' },
+});
+
+export const STRUCTURE_PROVIDER_SHAPE = defineSeamShape<StructureProvider>()({
+  create: { optional: false, kind: 'function', required: 'round-trip' },
+  remove: { optional: false, kind: 'function', required: 'round-trip' },
+  duplicate: { optional: false, kind: 'function', required: 'round-trip' },
+  reparent: { optional: false, kind: 'function', required: 'round-trip' },
+  reorder: { optional: true, kind: 'function', required: 'round-trip' },
+  creatableKinds: { optional: true, kind: 'function', required: 'operation' },
+  wrap: { optional: true, kind: 'function', required: 'round-trip' },
+  unwrap: { optional: true, kind: 'function', required: 'round-trip' },
+  group: { optional: true, kind: 'function', required: 'round-trip' },
+  ungroup: { optional: true, kind: 'function', required: 'round-trip' },
+  canUngroup: { optional: true, kind: 'function', required: 'operation' },
+  removeMany: { optional: true, kind: 'function', required: 'round-trip' },
+  copy: { optional: true, kind: 'function', required: 'effect' },
+  canCopy: { optional: true, kind: 'function', required: 'operation' },
+  cut: { optional: true, kind: 'function', required: 'round-trip' },
+  paste: { optional: true, kind: 'function', required: 'round-trip' },
+  canPaste: { optional: true, kind: 'function', required: 'operation' },
+});
+
+export const PERSISTENCE_PROVIDER_SHAPE = defineSeamShape<PersistenceProvider>()({
+  isDirty: { optional: false, kind: 'function', required: 'operation' },
+  lastError: { optional: true, kind: 'function', required: 'operation' },
+  save: { optional: false, kind: 'function', required: 'round-trip' },
+  destination: { optional: false, kind: 'value', required: 'shape' },
+  applyExternal: { optional: true, kind: 'function', required: 'effect' },
+});
+
+export const PICK_PROVIDER_SHAPE = defineSeamShape<PickProvider>()({
+  pick: { optional: false, kind: 'function', required: 'operation' },
+  candidates: { optional: true, kind: 'function', required: 'operation' },
+});
+
+export const STORIES_PROVIDER_SHAPE = defineSeamShape<StoriesProvider>()({
+  storiesFor: { optional: false, kind: 'function', required: 'operation' },
+  active: { optional: false, kind: 'function', required: 'operation' },
+  apply: { optional: false, kind: 'function', required: 'effect' },
+  isolate: { optional: true, kind: 'function', required: 'effect' },
+  title: { optional: true, kind: 'value', required: 'shape' },
+});
+
+export const ASSET_DROP_PROVIDER_SHAPE = defineSeamShape<AssetDropProvider>()({
+  accepts: { optional: false, kind: 'function', required: 'operation' },
+  drop: { optional: false, kind: 'function', required: 'round-trip' },
+});
+
+export const RECT_PROVIDER_SHAPE = defineSeamShape<RectProvider>()({
+  rect: { optional: false, kind: 'function', required: 'operation' },
+  contextRects: { optional: true, kind: 'function', required: 'operation' },
+  emptyContainers: { optional: true, kind: 'function', required: 'operation' },
+});
+
+export const BOX_EDIT_PROVIDER_SHAPE = defineSeamShape<BoxEditProvider>()({
+  begin: { optional: false, kind: 'function', required: 'effect' },
+  apply: { optional: false, kind: 'function', required: 'effect' },
+  end: { optional: false, kind: 'function', required: 'effect' },
+  gizmoOrigin: { optional: true, kind: 'function', required: 'operation' },
+  referencePoint: { optional: true, kind: 'function', required: 'operation' },
+});
+
+export const TEXT_PROVIDER_SHAPE = defineSeamShape<TextProvider>()({
+  get: { optional: false, kind: 'function', required: 'operation' },
+  set: { optional: false, kind: 'function', required: 'effect' },
+});
+
+export const COLOR_SAMPLE_PROVIDER_SHAPE = defineSeamShape<ColorSampleProvider>()({
+  backgroundChainAt: { optional: false, kind: 'function', required: 'operation' },
+});
+
+export const TRUTH_PROVIDER_SHAPE = defineSeamShape<TruthProvider>()({
+  resolve: { optional: false, kind: 'function', required: 'operation' },
+});
+
+export const SPATIAL_HANDLES_PROVIDER_SHAPE = defineSeamShape<SpatialHandlesProvider>()({
+  layers: { optional: false, kind: 'function', required: 'operation' },
+  preview: { optional: false, kind: 'function', required: 'effect' },
+  commit: { optional: false, kind: 'function', required: 'round-trip' },
+});
+
+type ObjectProviderKey = Exclude<
+  keyof AuthoringAdapter,
+  'capabilities' | 'provenance' | 'hierarchy' | 'subscribe' | 'observeTransforms'
+>;
+
+/** The one nested-provider table. Its key type comes from AuthoringAdapter and
+ * each value is typed against that provider's own interface. */
+export const AUTHORING_PROVIDER_SHAPES: {
+  readonly [K in ObjectProviderKey]: SeamShape<NonNullable<AuthoringAdapter[K]>>;
+} = {
+  selection: SELECTION_PROVIDER_SHAPE,
+  transforms: TRANSFORM_PROVIDER_SHAPE,
+  inspector: INSPECTOR_PROVIDER_SHAPE,
+  assetSubject: ASSET_SUBJECT_PROVIDER_SHAPE,
+  related: RELATED_SUBJECTS_PROVIDER_SHAPE,
+  instances: COMPONENT_INSTANCES_PROVIDER_SHAPE,
+  structure: STRUCTURE_PROVIDER_SHAPE,
+  persistence: PERSISTENCE_PROVIDER_SHAPE,
+  pickable: PICK_PROVIDER_SHAPE,
+  rects: RECT_PROVIDER_SHAPE,
+  boxEdit: BOX_EDIT_PROVIDER_SHAPE,
+  text: TEXT_PROVIDER_SHAPE,
+  colorSample: COLOR_SAMPLE_PROVIDER_SHAPE,
+  stories: STORIES_PROVIDER_SHAPE,
+  truth: TRUTH_PROVIDER_SHAPE,
+  spatialHandles: SPATIAL_HANDLES_PROVIDER_SHAPE,
+  assetDrop: ASSET_DROP_PROVIDER_SHAPE,
+};

package/src/adapter/authoring.ts

@@ -58,7 +58,7 @@ export interface AuthoringProvenance {
    * - `foreign` — a live tree the editor does not own (an unmodified external
    *   game, or any world edited only through an overlay); edits go to the
    *   overlay, never the source;
-   * - `live` — a running game adopted at play time; edits are not persisted;
+   * - `live` — a running game adopted at play time; ordinary edits are not persisted;
    * - `boundary` — a declared world with no live editing surface here.
    */
   source: 'document' | 'source-code' | 'foreign' | 'live' | 'boundary';
@@ -118,6 +118,12 @@ export interface PropertyDescriptor {
   label: string;
   type: 'string' | 'number' | 'boolean' | 'vec3' | 'color' | 'enum' | 'asset' | 'json';
   readonly?: boolean;
+  /**
+   * Why this field cannot be written, in the adapter's own vocabulary. The
+   * Inspector, its control surface, and the write refusal all project this
+   * same sentence; omitting it uses the generic read-only explanation.
+   */
+  readonlyReason?: string;
   options?: unknown[];
   /**
    * Optional domain-shaped grouping (T3.4 slice 2): properties sharing the
@@ -210,6 +216,42 @@ export interface TransformEditability {
   writable: boolean;
   /** Human-facing explanation for a disabled gizmo/field. */
   reason?: string;
+  /**
+   * Is there an AUTHORED override of this channel that {@link
+   * TransformProvider.remove} could drop? The per-channel analogue of a
+   * property descriptor's `resettable`, and it is answered the same way: the
+   * document actually carries this channel, and this session has a door that
+   * can take it back.
+   *
+   * It lives HERE rather than being inferred from `remove`'s presence because
+   * `remove` is a lane-wide fact while this is a per-subject one — a composite
+   * routes both, but only this one can say that THIS node's `position` is
+   * authored and THAT node's is not. Omitted ⇒ nothing to drop, and the
+   * protocol's removal door refuses by name instead of acking a revert it did
+   * not perform.
+   *
+   * EACH HALF IS ANSWERED BY WHOEVER CAN SEE IT, and a lane that cannot read
+   * its own document may not invent the first. A source lane holding the
+   * file's text answers both (the first-party R3F lane reads the callsite's
+   * attributes before saying yes). A lane whose client holds only an
+   * oid → file:line index and writes through a server that resolves the
+   * address — the vendored-ingest lane — can honestly answer only the SECOND,
+   * so that is what it answers, and `remove`'s own {@link WriteAck} reports
+   * whether an attribute was actually dropped (`persisted: false` when the
+   * callsite carried none). The inverse is what is forbidden on every lane:
+   * acking a drop that took no byte.
+   */
+  removable?: boolean;
+}
+
+/** The one lawful Play→source write: a person explicitly attributes the
+ * selected live node's current transform to its OID-anchored source literal.
+ * This is an atomic optional group so availability and the write door cannot
+ * drift apart. Ordinary transform gestures remain governed by begin/apply/end
+ * and therefore stay ephemeral while Play is running. */
+export interface TransformSourceCommitProvider {
+  availability(id: string): { available: boolean; reason?: string };
+  commit(id: string): Promise<WriteAck>;
 }
 
 export interface TransformProvider {
@@ -231,6 +273,35 @@ export interface TransformProvider {
    * live-only floor rather than borrowing an answer from somewhere else.
    */
   endEdit(id: string): void | WriteAck | Promise<void | WriteAck>;
+  /**
+   * Optional — DROP one channel's authored transform entirely, rather than
+   * writing a value into it.
+   *
+   * THE SAME DOOR {@link InspectorProvider.remove} IS, for the channel the
+   * Transform section owns instead of a property row. `apply`/`endEdit` write a
+   * VALUE, so reverting a channel an authoring gesture APPENDED by writing the
+   * old numbers back leaves `position={[0, 0, 0]}` standing where the source
+   * carried nothing — the file ends one attribute heavier than it started, and
+   * no byte-level edit/revert round trip can close. Only removal expresses that
+   * absence, which is why a lane without this door grades UNVERIFIABLE rather
+   * than passing.
+   *
+   * SAME ACK CONTRACT AS {@link endEdit} — the pipe's per-edit {@link WriteAck}
+   * for THIS removal, awaited. Removal is a write; it moves bytes, and the
+   * caller has the same right to be told where they went. Returning nothing
+   * means this provider performed no persisted write and the shell reports the
+   * live-only floor.
+   *
+   * What "absent" MEANS is the dialect writer's to decide (deleting the JSX
+   * attribute, for the source lanes). Nothing above this seam infers it: a lane
+   * whose transform truth IS the running object — there is no document for the
+   * channel to be absent from — simply omits the method, and the protocol door
+   * refuses by name rather than falling back to a value write.
+   */
+  remove?(id: string, channel: TransformChannel): void | WriteAck | Promise<void | WriteAck>;
+  /** Explicit Play→source attribution. Absent outside an eligible live OID
+   * surface; never used implicitly by a transform gesture. */
+  readonly sourceCommit?: TransformSourceCommitProvider;
 }
 
 /**
@@ -262,14 +333,28 @@ export interface InspectorProvider {
   editability?(id: string, path: string): { writable: boolean; reason?: string };
   /**
    * Optional — REMOVE a property's authored override entirely (not "set to a
-   * value"), letting whatever governs it in its absence take over. The one
-   * concrete need today: a longhand CSS override (`style.borderTopLeftRadius`)
-   * that a uniform edit of its shorthand (`style.borderRadius`) must clear so
-   * the shorthand actually wins, instead of leaving a stale longhand that
-   * silently overrides it on reload (spec 27 §5 C2, U2). Adapters with no
-   * removable-override concept simply omit it — callers optional-chain.
+   * value"), letting whatever governs it in its absence take over.
+   *
+   * THIS IS THE ONLY WAY TO EXPRESS BYTE-ABSENCE. {@link set} writes a VALUE:
+   * reverting a prop an authoring gesture ADDED by setting it back to what the
+   * default would have been leaves `position={[0, 0, 0]}` in the source where
+   * the file previously carried nothing at all. Only removal restores the
+   * bytes, which is why a lane with no `remove` cannot close its own
+   * edit/revert round trip and grades UNVERIFIABLE rather than passing.
+   *
+   * SAME ACK CONTRACT AS {@link set} — the pipe's per-edit {@link WriteAck}
+   * (`editor/src/authoring/write-pipe.ts`), awaited. Removal is a write; it
+   * moves bytes, and the caller has the same right to be told where they went
+   * and whether they moved. Returning nothing means this provider performed no
+   * persisted write, and the shell reports the live-only floor.
+   *
+   * What "absent" MEANS is the dialect writer's to decide — deleting a JSX
+   * attribute, dropping a CSS longhand so its shorthand cascades. Nothing above
+   * this seam infers it. Adapters with no removable-override concept simply
+   * omit the method; callers optional-chain, and the protocol door refuses by
+   * name rather than falling back to a value write.
    */
-  remove?(id: string, path: string): void;
+  remove?(id: string, path: string): void | WriteAck | Promise<void | WriteAck>;
 }
 
 /**
@@ -340,6 +425,9 @@ export interface ComponentInstanceDescription {
 export interface ComponentInstanceApplyResult {
   readonly changed: boolean;
   readonly message: string;
+  /** This operation's own writer acknowledgement. Absent when the request was
+   * refused before any write; live-only is an explicit WriteAck. */
+  readonly write?: WriteAck;
 }
 
 /**
@@ -352,14 +440,84 @@ export interface ComponentInstancesProvider {
   describe(id: string): ComponentInstanceDescription | null;
   /** Open the native component/prefab board for this instance's surface. */
   openComponent?(id: string): void;
-  revert(id: string, paths: readonly string[]): Promise<void>;
+  revert(id: string, paths: readonly string[]): Promise<void | WriteAck>;
   applyToComponent(id: string, path: string): Promise<ComponentInstanceApplyResult>;
 }
 
+/**
+ * WHAT A STRUCTURAL VERB ANSWERS WITH — the same widening
+ * {@link TransformProvider.endEdit} and {@link InspectorProvider.set} carry,
+ * for the same reason: the ack is produced by the component that performed
+ * THIS edit, and there is nowhere else for a caller to get one.
+ *
+ * `void` is the honest answer for a lane whose verb performs no write of its
+ * own (an in-memory adapter mutating a graph it already owns); a lane that
+ * writes returns the persistence pipe's own {@link WriteAck}
+ * (`editor/src/authoring/write-pipe.ts`), awaited, so a caller that awaits the
+ * verb has awaited the byte.
+ *
+ * A structural verb resolves on ITS OWN verb: `remove` asks whether the struct
+ * writer is bound, never whether the PROP writer is — resolving on a
+ * value-write door is how a lane comes to ack `source-prop` for a door it does
+ * not have.
+ */
+export type StructuralWriteOutcome = void | WriteAck | Promise<void | WriteAck>;
+
+/**
+ * WHAT AN ID-RETURNING STRUCTURAL VERB ANSWERS WITH — the id and the ack, as
+ * ONE return.
+ *
+ * The writing verbs ({@link StructureProvider.remove} and friends) answer with
+ * a bare {@link StructuralWriteOutcome}, because the write IS their whole
+ * answer. `create`/`duplicate`/`group`/`ungroup` owe their caller a second
+ * thing — the id(s) the op produced — and those two halves settle at DIFFERENT
+ * TIMES:
+ *
+ *  - the id is SYNCHRONOUS where a lane can mint one. The live canvas surface
+ *    adds a real display object to the running tree and re-indexes before it
+ *    returns, so `create` hands back an id its caller can select in the same
+ *    turn ("create then immediately select it" is the ordinary shell
+ *    sequence). Making the verb `async` to carry the ack would take that
+ *    away from every caller to serve a value that is already known.
+ *  - the ack is ASYNCHRONOUS wherever a byte is involved, and it is the only
+ *    thing that says whether the edit reached the file it claims.
+ *
+ * So the return carries both. A source lane whose new id only exists after the
+ * remount stamps it answers `id: ''` (there is no honest synchronous id) with a
+ * real `ack`; a router that could not route answers with an unchanged id and
+ * `ack: undefined` (no write was attempted, which is exactly what `void` means
+ * in {@link StructuralWriteOutcome}).
+ *
+ * Firing the write and dropping the promise on the floor — `void structOp(…)`
+ * behind a `return ''` — is the shape this type exists to make unrepresentable:
+ * it left the caller unable to await the byte, which is how N same-file
+ * duplicates went out together, each reading the file before any wrote back.
+ */
+export interface StructuralIdWrite<Id extends string | null = string> {
+  /** The id the op produced — `''` when the lane cannot know it until its own
+   *  source write completes and the world remounts. */
+  readonly id: Id;
+  readonly ack: StructuralWriteOutcome;
+}
+
+/** The plural half of {@link StructuralIdWrite}, for a verb that promotes a set
+ *  of ids rather than minting one. */
+export interface StructuralIdsWrite {
+  readonly ids: readonly string[];
+  readonly ack: StructuralWriteOutcome;
+}
+
+/** Clipboard-backed structural writes retain the existing `false` refusal
+ * channel while answering a successful cut/paste with the write's real
+ * destination. A bare `true` cannot prove a byte landed anywhere. */
+export type StructuralClipboardOutcome = false | WriteAck | Promise<false | WriteAck>;
+
 export interface StructureProvider {
-  create(kind: string, parentId?: string): string;
+  /** Create a `kind` under `parentId`, answering with the new id AND this
+   *  creation's own write ack (see {@link StructuralIdWrite}). */
+  create(kind: string, parentId?: string): StructuralIdWrite;
   /**
-   * Remove `id`. May optionally return an awaitable (`Promise<void>`) when the
+   * Remove `id`. May optionally return an awaitable when the
    * underlying write is asynchronous (e.g. a react-world source-file edit) —
    * `deleteSelection` (`editor-hotkeys.ts`) awaits it per id so a same-file
    * multi-delete's writes land strictly one at a time (see that function's own
@@ -367,14 +525,22 @@ export interface StructureProvider {
    * a per-id loop sound for an adapter whose OID index isn't reindexed between
    * writes). An adapter with a synchronous/in-memory remove (e.g.
    * `UIAuthoringAdapter`) returns `void` — `await`ing it is a harmless no-op.
+   *
+   * A source-writing lane returns THIS removal's own {@link WriteAck} (see
+   * {@link StructuralWriteOutcome}).
    */
-  remove(id: string): void | Promise<void>;
-  duplicate(id: string): string;
-  reparent(id: string, newParentId: string | null): void;
+  remove(id: string): StructuralWriteOutcome;
+  /** Copy `id`, answering with the copy's id AND this duplication's own write
+   *  ack (see {@link StructuralIdWrite}). A source lane whose copy has no id
+   *  until the remount stamps it answers with the SOURCE id it was given —
+   *  `duplicate` has no refusal channel, so an empty string there would be
+   *  indistinguishable from "refused". */
+  duplicate(id: string): StructuralIdWrite;
+  reparent(id: string, newParentId: string | null): StructuralWriteOutcome;
   /** Reorder `id` to sit immediately before `beforeSiblingId` among its siblings
    *  (`null` = move to the end). Absent ⇒ the shell has no sibling-reorder UI
    *  for this adapter. */
-  reorder?(id: string, beforeSiblingId: string | null): void;
+  reorder?(id: string, beforeSiblingId: string | null): StructuralWriteOutcome;
   /**
    * The kinds `create` accepts for a given parent (`null` parentId = a new
    * root), each with a display label — drives the shell's creation palette.
@@ -387,18 +553,22 @@ export interface StructureProvider {
    *  adapter-chosen, e.g. a `div`), re-parenting `id` as that container's sole
    *  child. Absent ⇒ the shell's context menu shows no Wrap item for this
    *  adapter. */
-  wrap?(id: string, wrapperTag?: string): void;
+  wrap?(id: string, wrapperTag?: string): StructuralWriteOutcome;
   /** D3 (spec 27 §6) — replace `id` with its own children (the inverse of
    *  `wrap`). Absent ⇒ the shell's context menu shows no Unwrap item for this
    *  adapter. */
-  unwrap?(id: string): void;
+  unwrap?(id: string): StructuralWriteOutcome;
   /** Group sibling authoring objects beneath one new spatial parent. The
    * adapter owns transform preservation, persistence, and undo semantics.
-   * Returns the new group id, or null when the selection cannot be grouped. */
-  group?(ids: readonly string[]): string | null;
-  /** Dissolve a plain spatial group and return the ids of its promoted
-   * children. Absent means this adapter has no lossless ungroup operation. */
-  ungroup?(id: string): string[];
+   * Answers with the new group id — `null` when the selection cannot be
+   * grouped at all — AND this grouping's own write ack (see
+   * {@link StructuralIdWrite}). */
+  group?(ids: readonly string[]): StructuralIdWrite<string | null>;
+  /** Dissolve a plain spatial group, answering with the ids of its promoted
+   * children AND this dissolution's own write ack (see
+   * {@link StructuralIdsWrite}). Absent means this adapter has no lossless
+   * ungroup operation. */
+  ungroup?(id: string): StructuralIdsWrite;
   /** Preflight for an Ungroup affordance. Omit when ungroup is never offered. */
   canUngroup?(id: string): boolean;
   /**
@@ -410,15 +580,15 @@ export interface StructureProvider {
    * own single batched multi-delete undo). Absent ⇒ the shell falls back to
    * the per-id `remove` loop (today's N-entry behavior, unchanged) — an
    * honest degrade, not a silent behavior change, for any adapter that
-   * hasn't implemented batching. May optionally return an awaitable
-   * (`Promise<void>`), same widening `remove` documents above and for the
-   * same reason (delete-order-residual fix): `deleteSelection`
+   * hasn't implemented batching. May optionally return an awaitable, same
+   * widening `remove` documents above ({@link StructuralWriteOutcome}) and for
+   * the same reason (delete-order-residual fix): `deleteSelection`
    * (`editor-hotkeys.ts`) awaits it so the caller can rely on the whole
    * batch's write having landed before it returns. A synchronous/in-memory
    * implementation (e.g. `UIAuthoringAdapter`'s) returns `void` — awaiting it
    * is a harmless no-op.
    */
-  removeMany?(ids: readonly string[]): void | Promise<void>;
+  removeMany?(ids: readonly string[]): StructuralWriteOutcome;
   /** Copy authored entities through the host clipboard. The adapter owns the
    * native payload (JSX for a source-backed Three/Canvas world, native records
    * for a data-backed adapter); the shell never serializes an engine-private
@@ -428,11 +598,11 @@ export interface StructureProvider {
   canCopy?(ids: readonly string[]): boolean;
   /** Copy, then remove the same authored entities only after the clipboard
    * write succeeds. One adapter operation owns that ordering. */
-  cut?(ids: readonly string[]): boolean | Promise<boolean>;
+  cut?(ids: readonly string[]): StructuralClipboardOutcome;
   /** Paste as children of `parentId`; `null` means the adapter document root.
    * The shell derives the current selection's parent so ordinary Paste creates
    * siblings, matching scene-hierarchy editors. */
-  paste?(parentId: string | null): boolean | Promise<boolean>;
+  paste?(parentId: string | null): StructuralClipboardOutcome;
   /** Honest affordance preflight. It need only cover adapter/session state;
    * the actual paste still validates the live system clipboard. */
   canPaste?(parentId: string | null): boolean;
@@ -538,7 +708,11 @@ export interface AssetDropContext {
 /** Asset drop (hierarchy + viewport). */
 export interface AssetDropProvider {
   accepts(nodeId: string, assetPath: string, context?: AssetDropContext): boolean;
-  drop(nodeId: string, assetPath: string, context?: AssetDropContext): void | Promise<void>;
+  /** A drop that lands as an ELEMENT in the game's own source is a structural
+   *  write, so it answers with the same {@link StructuralWriteOutcome} the rest
+   *  of {@link StructureProvider}'s writing verbs do — a lane whose drop only
+   *  mutates the running graph returns `void`. */
+  drop(nodeId: string, assetPath: string, context?: AssetDropContext): StructuralWriteOutcome;
 }
 
 /** Plain-object rect shape shared by {@link RectProvider} — the same fields a real
@@ -708,6 +882,19 @@ export type NodeCreationSite =
  *    the anchor; survives a cold remount, because the file is truth and the next
  *    mount re-derives from it.
  *    Proof: `packages/editor/test/oid-source-persistence.test.ts`.
+ *  - `source-structure` — the edit is not a VALUE at all: it adds, removes,
+ *    moves or re-nests an ELEMENT of the game's own source (`delete`,
+ *    `duplicate`, `wrap`/`unwrap`, `create`, `reorder`, `reparent`, `group`).
+ *    It is a kind rather than a flavour of `source-prop` because it resolves on
+ *    a DIFFERENT DOOR — the dialect's structural writer, not its attribute
+ *    writer — and a lane can have one without the other. Claiming `source-prop`
+ *    for a structural edit is exactly the classifier/writer split the
+ *    persistence pipe exists to make impossible: it names a value lane that
+ *    never carried the bytes. Its landing contract adds one gate the prop lane
+ *    does not have: the write is WHOLE-FILE and checksum-guarded, so an op
+ *    resolved against a stale element index must fail rather than land at the
+ *    wrong offset.
+ *    Proof: `packages/editor/test/structural-write-pipe.test.ts`.
  *  - `construction-literal` — the value is a literal in the CONSTRUCTION
  *    EXPRESSION that built the object (`new THREE.Mesh(…)` in the game's own
  *    served module). Same landing/remount contract, plus one gate the prop lane
@@ -740,6 +927,7 @@ export type NodeCreationSite =
  */
 export type WriteAnchorKind =
   | 'source-prop'
+  | 'source-structure'
   | 'construction-literal'
   | 'physics-binding'
   | 'data-record'
@@ -793,6 +981,7 @@ export interface WriteAck {
  */
 const WRITE_ANCHOR_KIND_PRESENCE: Readonly<Record<WriteAnchorKind, true>> = {
   'source-prop': true,
+  'source-structure': true,
   'construction-literal': true,
   'physics-binding': true,
   'data-record': true,
@@ -824,22 +1013,23 @@ export function emptyWriteAnchorKindCounts(): Record<WriteAnchorKind, number> {
  * document-backed world's truth is the document, not a construction site).
  * Present ⇒ every id gets an answer, anchored or reasoned.
  */
-export interface CreationSiteProvider {
-  anchor(id: string): NodeCreationSite;
-  /**
-   * The write-side sibling of {@link anchor}: which LANE would carry an edit to
-   * this node's transform, in the closed vocabulary above. Exposed beside the
-   * anchor because that is where every reader already looks, and because a
-   * caller sweeping a hierarchy needs it to find a representative node per kind
-   * (`vgai doctor`'s edit-write walk is that caller).
-   *
-   * Absent ⇒ this adapter plans no lanes it can distinguish; the reader has only
-   * the anchor's own shape, which cannot tell two source lanes apart.
-   * `undefined` for a particular id ⇒ this adapter plans no write for THAT id
-   * (a synthetic hierarchy row, an id no child of a composite owns) — which is
-   * not the same as `live-only`, a lane that really does land on a live object.
-   */
-  writeAnchorKind?(id: string): WriteAnchorKind | undefined;
+export interface AuthoringTruth {
+  /** Where the runtime object came from in the game's own source or data. */
+  readonly site: NodeCreationSite;
+  /** The lane THIS property edit would actually take. `undefined` means the
+   * subject is synthetic or otherwise has no write plan; `live-only` is a real
+   * plan whose destination is the running object. */
+  readonly writeAnchorKind: WriteAnchorKind | undefined;
+}
+
+/**
+ * The TRUTH-family binding. One resolution answers both where a subject came
+ * from and where an edit to one of its properties lands. A caller may not read
+ * those facts through separate providers: that was the classifier/writer split
+ * the persistence pipe exists to remove.
+ */
+export interface TruthProvider {
+  resolve(id: string, property: string): AuthoringTruth;
 }
 
 /** A plain world-space point. Component handles cross the authoring seam as
@@ -931,7 +1121,10 @@ export interface SpatialHandleLayer {
 export interface SpatialHandlesProvider {
   layers(id: string): readonly SpatialHandleLayer[];
   preview(id: string, handleId: string, worldPosition: SpatialPoint3): void;
-  commit(id: string, handleId: string, worldPosition: SpatialPoint3): void | Promise<void>;
+  /** Commit the preview and pass through the owning writer's acknowledgement.
+   * `void` remains the honest live-only/no-write floor; callers must not grade
+   * it as a persisted round trip. */
+  commit(id: string, handleId: string, worldPosition: SpatialPoint3): StructuralWriteOutcome;
 }
 
 export interface AuthoringAdapter {
@@ -967,9 +1160,8 @@ export interface AuthoringAdapter {
   readonly colorSample?: ColorSampleProvider;
   /** D4 — storybook stories. Absent ⇒ no stories for any node in this adapter. */
   readonly stories?: StoriesProvider;
-  /** WO-IDX1 — the source location that constructed a node's live object.
-   *  Absent ⇒ this adapter indexes no creation sites. */
-  readonly creationSite?: CreationSiteProvider;
+  /** Projection subject → source/data anchor and write lane, resolved together. */
+  readonly truth?: TruthProvider;
   /** Adapter-owned component guides and direct-manipulation points. */
   readonly spatialHandles?: SpatialHandlesProvider;
   /** Asset drop (hierarchy + viewport). Absent ⇒ this adapter accepts no drops. */
@@ -1030,7 +1222,7 @@ const AUTHORING_PROVIDER_PRESENCE: Readonly<Record<AuthoringProviderKey, true>>
   text: true,
   colorSample: true,
   stories: true,
-  creationSite: true,
+  truth: true,
   spatialHandles: true,
   assetDrop: true,
   subscribe: true,