@@ -0,0 +1,12 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): the draft read declares `draftChanges`, a pending draft's per-key provenance: which authoring surface last changed each key path of the draft, under which actor, and when
+
+Clause-②: yes (widening)
+
+- **The key.** `GetMetaItemResponseSchema` gains an optional `draftChanges` beside `item`: one entry per changed key path of the pending draft body, each `{ path, by, actor, at }`. `path` is an array of the keys from the body root to the deepest key the write changed (`["fields", "renewal_count"]`, `["fields", "renewal_count", "label"]`); an array value is one leaf, so a change to a view's columns is `["columns"]` and never carries an index (which elements differ is read by comparing the array with the published body's; the entry says who last changed the array); `[]` is the whole body of an item created as a draft. `by` is a closed set: `copilot` (an AI assistant's tool writing on a person's behalf), `studio` (a person editing in Studio) or `api` (any other caller of the save door). `actor` is the write's recorded identity or `null`, and `at` its ISO-8601 instant.
+- **Where it is served.** Only on the strict draft read (`GET /meta/:type/:name?state=draft`), the read Studio's editor loads an item from, so the marks always describe the body that read returned. It is absent on the active read, the cached branch and the `?preview=draft` read. `ListDraftsResponseSchema` (`GET /meta/_drafts`) is unchanged.
+- **Absent means "not recorded".** No server writes the key yet; until one does, and for a draft row saved before it did, the key is absent rather than `[]`, so a reader never takes "not recorded" for "nothing changed".
+- **Nothing breaks.** Every response that parsed before still parses, and no runtime behaviour changes in this release of the spec.
@@ -1457,6 +1457,7 @@ This schema accepts one of the following structures:
 | **resettable** | `boolean` | optional | Whether the item can be reset to its packaged default — true iff it is artifact-backed, i.e. there is a baseline to reset TO. |
 | **version** | `string \| null` | optional | ADR-0008 version token of the STORED row a save to this item compares against, at this read's scope (the environment's partition and `?package=`) and lifecycle (`?state=draft` reads the draft row, the plain read the active row). The same keyed token a save receipt's `version` serves for that row: send it back as the `If-Match` request header on `PUT /meta/:type/:name` (with `?mode=draft` for the draft) and a concurrent edit is refused 409 `METADATA_CONFLICT` instead of overwritten. `null` when no stored row is there — an item served from code or a package artifact, or from a row in another scope (a package-less row a package read falls back to) — so the next save creates one: pin it with `If-None-Match: *`. A `null` beside `editable: false` is no such invitation: that item takes no save at this address, so no pin is prescribed for it. ABSENT on the cached published-value branch and on a `?preview=draft` read, which publish no version: absence means "not published here", never "no row". Opaque — echo it verbatim, never parse it. |
 | **registration** | `{ state: 'registered' } \| { state: 'refused'; reason: object } \| { state: 'unregistered' }` | optional | The automation engine's verdict on this flow (see `FlowRegistrationSchema`): `registered`, or `refused` with the engine's `reason` verbatim, or `unregistered`. Present only on a `flow` read answered by a process that runs an automation service; absent otherwise, and absence means no engine judged it, never `registered`. Unlike the protection keys it is published by the cached branch too, read live and never part of the ETag, so a cached read that carries it is never answered 304; it is absent on a draft read, whose pending body no engine holds. The verdict is the answering process's engine. Beside `item`, never inside it: the item's `status` stays what its author declared. |
+| **draftChanges** | `{ path: string[]; by: Enum<'copilot' \| 'studio' \| 'api'>; actor: string \| null; at: string }[]` | optional | Per-key provenance of the pending draft: which authoring surface last changed each key path of `item`, under which actor, and when. No server writes the key yet: until the engine's draft save records it, every draft read is one whose saves recorded none, and the key is absent. The contract a writer must meet: it compares each draft save with the body that save replaced (the previous draft, or the published body for the draft's first save); it keeps the entries from the first recorded save until the draft is published or discarded, which remove the draft row and the entries with it; and it keeps no two entries on one path, replacing every entry at or under a path a save changes, so the last write to change a key is the entry whose `path` is the longest prefix of that key's path, and entries under a key's path are changes inside it. The entries name which writes changed what; they are not a list of every difference from the published body (compare the two bodies for that). Served only on a `?state=draft` read that answers a stored draft row. ABSENT on the active read, the cached branch and a `?preview=draft` read, and for a draft row whose saves recorded none: absence means "not recorded", never "no changes". |
 
 ### Nested Shape: `GetMetaItemResponse.sortability`
 
@@ -1483,6 +1484,17 @@ This schema accepts one of the following structures:
 | :--- | :--- | :--- | :--- |
 | **state** | `'unregistered'` | ✅ | The engine holds nothing under the flow's name and recorded no refusal for it. |
 
+### Nested Shape: `GetMetaItemResponse.draftChanges[number]`
+
+One changed key path of the pending draft, and the last write that changed it.
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **path** | `string[]` | ✅ | The changed key path inside `item`: one object key per segment, from the body root down to the deepest key whose value the write changed, added or removed. `["fields", "renewal_count"]` is a field the write added; `["fields", "renewal_count", "label"]` is one property of it. A segment is the key exactly as stored, dots included (a permission set's `fields` map is keyed `object.field`), so a path is never one dotted string. An array is one value: its path ends at its key (`["columns"]`) and never carries an index, which an insert or a reorder would shift. Which elements of an array the draft added or dropped is read by comparing it with the published body's array; the entry answers only who last changed the array as a whole. `[]` is the whole body: the write that created the draft of an item with no published body. |
+| **by** | `Enum<'copilot' \| 'studio' \| 'api'>` | ✅ | The authoring surface of the write that last changed this path. Closed: `copilot` is an AI assistant's tool writing on a person's behalf (Studio's AI copilot); `studio` is a person editing in Studio; `api` is any other caller of the save door. It names the surface, not the person: a copilot write and a Studio write of the same user carry the same `actor`. |
+| **actor** | `string \| null` | ✅ | The identity that write was recorded under: the save's `actor`, the value its history event carries. `null` when the write recorded none, never a sentinel string. |
+| **at** | `string` | ✅ | When that write happened: an ISO-8601 instant in UTC, written with `Z` (the form `toISOString()` produces). An offset or a local time is refused. |
+
 
 ---
 
 
@@ -19,4 +19,4 @@ hand-patch a number here** — fix the code or the verdict and regenerate.
 
 | Dir | Sites |
 |---|---|
-| `api/` | 444 |
+| `api/` | 445 |
@@ -789,6 +789,7 @@
     "api/GetMetaItemRequest:state",
     "api/GetMetaItemRequest:type",
     "api/GetMetaItemResponse:deletable",
+    "api/GetMetaItemResponse:draftChanges",
     "api/GetMetaItemResponse:editable",
     "api/GetMetaItemResponse:item",
     "api/GetMetaItemResponse:lock",
 
@@ -32,6 +32,7 @@ import type {
   GetMetaItemResponse,
   GetMetaItemsResponse,
   GetMetaItemLayeredResponse,
+  ListDraftsResponse,
   MetadataConflictError,
 } from './protocol.zod';
 import type { MetadataLock } from '../kernel/metadata-protection.zod';
@@ -305,3 +306,64 @@ describe('the engine\'s verdict on a stored flow: `registration` beside the item
     expect('registrations' in GetMetaItemsResponseSchema.parse({ type: 'flow', items: [FLOW] })).toBe(false);
   });
 });
+
+/**
+ * #24298 — a pending draft's per-key provenance, `draftChanges`, beside the
+ * item on the draft read: a closed `by` vocabulary, a path that is an ARRAY of
+ * keys, and absence kept distinct from "nothing changed". Typed at the level
+ * an SDK caller branches on, and deliberately not on the `_drafts` row.
+ */
+type DraftChange = NonNullable<GetMetaItemResponse['draftChanges']>[number];
+export type DraftChangeByIsTheClosedSurfaceSet = Assert< Eq< DraftChange['by'], 'copilot' | 'studio' | 'api' > >;
+export type DraftChangePathIsAnArrayOfKeys = Assert< Eq< DraftChange['path'], string[] > >;
+export type DraftChangeActorIsIdOrNull = Assert< Eq< DraftChange['actor'], string | null > >;
+export type DraftChangesMayBeAbsent = Assert< Eq< undefined extends GetMetaItemResponse['draftChanges'] ? true : false, true > >;
+export type DraftsRowCarriesNoDraftChanges = Assert< Eq< 'draftChanges' extends keyof ListDraftsResponse['drafts'][number] ? true : false, false > >;
+
+describe('`draftChanges` — which surface last changed each key of a pending draft, beside the item', () => {
+  const VIEW = { name: 'loan_board', label: 'Loans', columns: ['title', 'due_on'] };
+  const AT = '2026-10-18T11:02:38.000Z';
+  const ENTRIES = [
+    { path: [], by: 'copilot', actor: 'usr_1', at: AT },
+    { path: ['columns'], by: 'studio', actor: 'usr_1', at: AT },
+    { path: ['fields', 'account.name', 'readable'], by: 'api', actor: null, at: AT },
+  ];
+  const DRAFT_READ = { type: 'view', name: 'loan_board', item: VIEW, version: 'v1', draftChanges: ENTRIES };
+
+  it('keeps every entry through a parse — each surface, a root path, a dotted KEY and a null actor', () => {
+    expect(GetMetaItemResponseSchema.parse(DRAFT_READ).draftChanges).toEqual(ENTRIES);
+  });
+
+  it('an older response without the key still parses, and the key stays ABSENT — never defaulted to []', () => {
+    const parsed = GetMetaItemResponseSchema.parse({ type: 'view', name: 'loan_board', item: VIEW, version: 'v1' });
+    expect('draftChanges' in parsed).toBe(false);
+  });
+
+  /** The issue a refused body raises, located — never a bare "it failed". */
+  const issueOf = (draftChanges: unknown) => {
+    const verdict = GetMetaItemResponseSchema.safeParse({ ...DRAFT_READ, draftChanges });
+    expect(verdict.success).toBe(false);
+    return verdict.success ? undefined : verdict.error.issues[0];
+  };
+
+  it('refuses a surface outside the closed set, at the entry\'s `by`', () => {
+    for (const by of ['ai', 'user', 'mcp', 'Copilot']) {
+      expect(issueOf([{ ...ENTRIES[0], by }])).toMatchObject({ code: 'invalid_value', path: ['draftChanges', 0, 'by'] });
+    }
+  });
+
+  it('refuses a dotted-string path and an empty key segment — a path is an array of stored keys', () => {
+    expect(issueOf([{ ...ENTRIES[1], path: 'fields.renewal_count' }]))
+      .toMatchObject({ code: 'invalid_type', path: ['draftChanges', 0, 'path'] });
+    expect(issueOf([{ ...ENTRIES[1], path: ['fields', ''] }]))
+      .toMatchObject({ code: 'too_small', path: ['draftChanges', 0, 'path', 1] });
+  });
+
+  it('refuses an entry without its write\'s time, or with one that is not an ISO-8601 instant', () => {
+    const withoutAt: Record<string, unknown> = { ...ENTRIES[0] };
+    delete withoutAt.at;
+    expect(issueOf([withoutAt])).toMatchObject({ code: 'invalid_type', path: ['draftChanges', 0, 'at'] });
+    expect(issueOf([{ ...ENTRIES[0], at: 'two minutes ago' }]))
+      .toMatchObject({ code: 'invalid_format', path: ['draftChanges', 0, 'at'] });
+  });
+});
@@ -546,6 +546,49 @@ const MetadataProtectionEnvelopeFields = {
  * live and kept out of the ETag ({@link GetMetaItemCachedResponseSchema}). It
  * is absent wherever no automation engine answered, so absence is never read
  * as `registered`.
+ *
+ * [#24298] `draftChanges` is a pending draft's per-key provenance: for each
+ * changed key path of the draft body, which authoring surface (`copilot`,
+ * `studio`, `api`) last changed it, under which actor, and when. It is what
+ * lets Studio's properties mark a field or a view setting the AI copilot
+ * changed, with the draft chip and the source line objectui#12725 rules
+ * (「由 AI 副驾在 2 分钟前作为草稿加入」). It carries ADR-0033's provenance
+ * item, "attribute each AI draft to the acting user + mark it AI-sourced",
+ * at the grain of a key: `actor` is the acting user and `by: 'copilot'` the
+ * AI-sourced mark, two members because one user makes both kinds of edit.
+ * Four measured choices:
+ *
+ * - **On this read, not on the `_drafts` row.** The reader is Studio's
+ *   properties, and they read the item they edit through the strict draft
+ *   read (`?state=draft`, the client's `getDraft`); the `_drafts` list is the
+ *   change badge's and the changes drawer's read, one row per item. Here the
+ *   provenance comes from the same stored row as the body and `version` it
+ *   sits beside, so a mark can never describe a body the editor has not
+ *   loaded.
+ * - **Beside `item`, never inside it**, like `registration`: a fact about the
+ *   stored row the document cannot carry. Inside the body it would be one more
+ *   read decoration every GET → edit → PUT round trip must strip
+ *   (`METADATA_READ_DECORATIONS`), and `provenance` is already the ADR-0010
+ *   envelope key (where the item came from), hence the distinct name.
+ * - **A path is an array of keys, and an array value is one leaf.** Keys may
+ *   contain dots (a permission set's `fields` map is keyed `object.field`), so
+ *   a dotted string would be ambiguous; and an index (`columns[3]`) moves when
+ *   a column is inserted or reordered, so the path stops at `columns` — the
+ *   granularity the ruling names, "a field or a view setting". The ruled
+ *   properties artboard also marks ELEMENTS of an array setting: a kanban
+ *   card's two copilot-added fields, under the line
+ *   「读者」「应还日期」两项由 AI 副驾在 2 分钟前作为草稿加入. The reader finds
+ *   which elements by comparing the draft's array with the published body's,
+ *   and the array's entry says who last changed it and when. Attribution is
+ *   per array, never per element.
+ * - **Optional, never defaulted to `[]`.** Absent means "not recorded" (a
+ *   server with no writer, or a draft row saved before one); an empty-array
+ *   default would answer "nothing changed" for exactly those rows.
+ *
+ * The history log's per-event `source` (see `HistoryMetaItemResponseSchema`)
+ * is not this vocabulary: it is an open label of the code path that wrote the
+ * event, not the surface a person or the copilot used, and it is per write,
+ * not per key.
  */
 export const GetMetaItemResponseSchema = lazySchema(() => z.object({
   type: z.string().describe('Metadata type name'),
@@ -588,6 +631,49 @@ export const GetMetaItemResponseSchema = lazySchema(() => z.object({
     + 'the answering process\'s engine. Beside `item`, never inside it: the item\'s `status` stays what '
     + 'its author declared.',
   ),
+  draftChanges: z.array(z.object({
+    path: z.array(z.string().min(1)).describe(
+      'The changed key path inside `item`: one object key per segment, from the body root down to the '
+      + 'deepest key whose value the write changed, added or removed. `["fields", "renewal_count"]` is a '
+      + 'field the write added; `["fields", "renewal_count", "label"]` is one property of it. A segment '
+      + 'is the key exactly as stored, dots included (a permission set\'s `fields` map is keyed '
+      + '`object.field`), so a path is never one dotted string. An array is one value: its path ends at '
+      + 'its key (`["columns"]`) and never carries an index, which an insert or a reorder would shift. '
+      + 'Which elements of an array the draft added or dropped is read by comparing it with the '
+      + 'published body\'s array; the entry answers only who last changed the array as a whole. '
+      + '`[]` is the whole body: the write that created the draft of an item with no published body.',
+    ),
+    by: z.enum(['copilot', 'studio', 'api']).describe(
+      'The authoring surface of the write that last changed this path. Closed: `copilot` is an AI '
+      + 'assistant\'s tool writing on a person\'s behalf (Studio\'s AI copilot); `studio` is a person '
+      + 'editing in Studio; `api` is any other caller of the save door. It names the surface, not the '
+      + 'person: a copilot write and a Studio write of the same user carry the same `actor`.',
+    ),
+    actor: z.string().nullable().describe(
+      'The identity that write was recorded under: the save\'s `actor`, the value its history event '
+      + 'carries. `null` when the write recorded none, never a sentinel string.',
+    ),
+    at: z.string().datetime().describe(
+      'When that write happened: an ISO-8601 instant in UTC, written with `Z` (the form '
+      + '`toISOString()` produces). An offset or a local time is refused.',
+    ),
+  }).describe('One changed key path of the pending draft, and the last write that changed it.'))
+    .optional().describe(
+      'Per-key provenance of the pending draft: which authoring surface last changed each key path of '
+      + '`item`, under which actor, and when. No server writes the key yet: until the engine\'s draft '
+      + 'save records it, every draft read is one whose saves recorded none, and the key is absent. '
+      + 'The contract a writer must meet: it compares each draft save with the body that save replaced '
+      + '(the previous draft, or the published body for the draft\'s first save); it keeps the entries '
+      + 'from the first recorded save until the draft is published or discarded, which remove the draft '
+      + 'row and the entries with it; and it keeps no two entries on one path, replacing every entry at '
+      + 'or under a path a save changes, so the last write to change a key is the entry whose `path` is '
+      + 'the longest prefix of that key\'s path, and entries under a key\'s path are changes inside it. '
+      + 'The entries name which writes changed what; they are not a list of every difference from the '
+      + 'published body (compare the two bodies for that). Served only on a `?state=draft` read that '
+      + 'answers a stored draft row. ABSENT on the active read, the cached branch and a '
+      + '`?preview=draft` read, and for a draft row whose saves recorded none: absence means "not '
+      + 'recorded", never "no changes".',
+    ),
 }));
 
 /**
@@ -1962,6 +2048,12 @@ export const GetPublishedMetaItemResponseSchema = lazySchema(() => z.unknown().d
  * one template are two drafts with one `type` and `name`. It is the row's
  * stored member, never read off the body, and it is the value the by-name
  * doors' `member` selector takes back.
+ *
+ * [#24298] Per-key provenance (which surface changed which key of the draft,
+ * and when) is deliberately NOT on this row: it is
+ * {@link GetMetaItemResponseSchema}'s `draftChanges`, on the strict draft read
+ * Studio's properties load the item from. `updatedBy` here stays the row's
+ * last actor, the same person for a copilot write and a hand edit.
  */
 export const ListDraftsResponseSchema = lazySchema(() => z.object({
   drafts: z.array(z.object({