@manudota/artist-mcp 2.1.1-staging.97 → 2.2.0

package/agent-pack/.artist/policies/PATCH.md

@@ -76,6 +76,26 @@ may have edited since.
 - Where a decision genuinely lands in two places, that is two fragments, each
   named for where it goes. Not one merged block covering both.
 
+### A table is the exception, and only because OneNote makes it one
+
+OneNote supports no change to a single row or cell. The tool can replace a whole
+table and nothing smaller, so where the decision lands in a table the smallest
+fragment it can *apply* is the entire table.
+
+That does not loosen anything above; it moves the care somewhere else. **Every
+cell that is not changing has to be carried across exactly as it reads now** —
+copy them from the rows the preview lists rather than retyping them from memory,
+because a cell left out of the markup is not a cell left alone, it is a value
+destroyed. `UNKNOWN` stays `UNKNOWN` in those words, and a column the musician
+never fills stays empty.
+
+Say what the change is, not what the mechanism is. "Changing Honorar to 1450" is
+the decision; that the whole table is rewritten to do it is worth one sentence,
+because they are approving the loss of everything in it if the markup is wrong.
+
+A patch to be pasted is unaffected: they place a row themselves, so it stays one
+row.
+
 A whole page is a fragment only when the whole page is what they settled — the
 consolidated page in `policy:divergence`, once every conflicting field has been
 decided, which goes somewhere new rather than over either original. Wanting a
@@ -175,6 +195,49 @@ Owner is the only cell they settled. Due is `UNKNOWN` because no date was given
 is `UNKNOWN` because "not started" is a reasonable guess and still a guess. The
 page says nothing about any of this until they paste it.
 
+## Table markup
+
+A table cannot be edited a cell at a time — OneNote supports no update to a row
+or a cell, so changing one value rewrites the whole table. Every cell that is
+not changing has to be carried across exactly as it reads.
+
+Formatting the original carried and the replacement leaves out is now carried
+across for you, and the preview says which parts it is keeping. Do not rely on
+that silently: it covers the table's own borders and its cells' borders, and it
+stops the moment the markup specifies any styling of its own — style one cell
+and you have taken responsibility for all of them.
+
+So write the house shape explicitly whenever the table is a new one, and let
+inheritance cover the ones you are editing in place. The house shape, which is
+what the artist's own pages already look like:
+
+- The table itself: `<table border="1" style="border-collapse:collapse">`. The
+  `border` attribute is the part OneNote acts on — a CSS `border:1px solid` in
+  the style alone comes back as `border:0px`.
+- Every cell: `<td style="border:1px solid #A3A3A3;padding:4px">`, with the
+  content in a `<p>`.
+- The header row, where the table has one, additionally carries
+  `background-color:#EFEFEF` on each cell and wraps its text in `<b>`. A roster
+  of musicians, a milestones table, a Field/Value block — the first row names the
+  columns and is shaded so it reads as a header rather than as data.
+- A free-text section is a single-cell table and has **no** header row. Shading
+  its only cell would make the whole section look like a heading.
+- Column widths are not set. OneNote sizes them, and a width guessed from a
+  preview is worse than none.
+
+Send this through the `html` parameter, never `text` — a table put through
+`text` arrives entity-escaped and lands on the page as literal angle brackets.
+
+Where a page needs several changes, give them as `changes` in one call. They are
+previewed together, confirmed together and written together, and if any one of
+them cannot be applied then none of them is. Changing one thing at a time makes
+the tool re-read the page between every change.
+
+Reading the page back afterwards is still worth doing on anything structural. It
+is no longer a way of telling a display artifact from a real mangling — the
+preview shows paragraph breaks and table rows as they are — but it is the only
+thing that confirms what the page now holds.
+
 ## Boundaries
 
 - Never claim a page was changed unless the tool reported changing it. A patch

package/agent-pack/registry.json

@@ -47,7 +47,7 @@
       "name": "Patch",
       "description": "Once the musician has decided something, hand them the smallest fragment that records it, and say which part of the page it goes under.",
       "file": ".artist/policies/PATCH.md",
-      "sha256": "d844496f2720befd02efa0ae940355e569acf2467e18906bad7e0769350653e2"
+      "sha256": "47029fd651ab2458ecc4b60dd73b16decf3f5c5506f20f4f61a71ca69f3f38e0"
     },
     {
       "id": "project-type:concert",

package/dist/api.d.ts

@@ -109,4 +109,5 @@ export declare const onenotePatchPage: (pageId: string, commands: readonly {
     target: string;
     action: string;
     content: string;
+    position?: "before" | "after";
 }[], token: string, etag: string | null) => Promise<void>;

package/dist/onenote-patch.d.ts

@@ -66,8 +66,10 @@ export declare const extractElement: (html: string, attr: "id" | "data-id", valu
 export declare const preImage: (html: string, generatedId: string) => string;
 export type PatchCommand = {
     target: string;
-    action: 'append' | 'replace';
+    action: 'append' | 'replace' | 'insert';
     content: string;
+    /** Only an insert has one. Graph ignores it elsewhere rather than refusing. */
+    position?: 'before' | 'after';
 };
 /**
  * Append to a container.
@@ -86,6 +88,20 @@ export declare const appendCommand: (target: string, contentHtml: string) => Pat
  * confusingly or hits something other than what was meant.
  */
 export declare const replaceCommand: (generatedId: string, contentHtml: string) => PatchCommand;
+/**
+ * Put a new element beside an existing one.
+ *
+ * Graph lists `insert` for a `table` with a `position` of `before` or `after`,
+ * and this is the only way a new block reaches the middle of a page: `append`
+ * can only reach the end of the body, so without a sibling insert a section
+ * added to a template lands after everything, which for these pages is after
+ * the signature block rather than where it belongs.
+ *
+ * The anchor is named by its generated id for the same reason a replace is —
+ * `data-id` targets resolve for `append` and not for this, and the failure is
+ * a `20134` that reads as though the element could not be edited.
+ */
+export declare const insertCommand: (generatedId: string, position: "before" | "after", contentHtml: string) => PatchCommand;
 /**
  * Plain text as a single paragraph, which is what replaces a paragraph.
  *
@@ -95,14 +111,71 @@ export declare const replaceCommand: (generatedId: string, contentHtml: string)
  * decided rather than smuggled in through the content string.
  */
 export declare const paragraph: (text: string) => string;
+/**
+ * Well-formed, allowed, and balanced — or nothing is sent.
+ *
+ * Returns the markup unchanged on success. It is deliberately not a normaliser:
+ * what goes to Graph is byte-for-byte what was hashed into the confirmation
+ * token and shown in the preview, so there is no room for a rewrite between
+ * the musician's yes and the write.
+ */
+export declare const validateFragment: (html: string) => string;
+/**
+ * The tag of the single element a fragment consists of, or undefined if it is
+ * not exactly one element.
+ *
+ * A replace must yield an element of the kind the target supports: a table
+ * replaced by two tables, or by a table and a stray paragraph, is not the
+ * change that was previewed as one table.
+ */
+export declare const rootTag: (html: string) => string | undefined;
+export type EditablePart = {
+    element_id: string;
+    /** A table is replaced whole and with HTML; everything else takes plain text. */
+    kind: 'text' | 'table';
+    /** As the musician reads it: a table as its rows, anything else as its text. */
+    text: string;
+    /** The table this sits in, if it does. Null for a top-level element. */
+    inside_table: string | null;
+};
+/** One change. A draft carries a list of these, even when the list has one entry. */
+export type EditChange = {
+    action: 'append' | 'replace' | 'insert';
+    /** The generated id of the element to replace, or to sit beside. Absent for an append. */
+    element_id: string | null;
+    /** Plain text, escaped on the way out. Null when the change is markup. */
+    text: string | null;
+    /** Validated markup. Null when the change is plain text. */
+    html: string | null;
+    /** Which side of the anchor an insert lands on. Null otherwise. */
+    position: 'before' | 'after' | null;
+};
 export type EditDraft = {
     page_id: string;
-    action: 'append' | 'replace';
-    /** The generated id of the element to replace. Absent for an append. */
-    element_id: string | null;
-    text: string;
+    changes: EditChange[];
     source_page: string | null;
 };
+export declare const inherit: (targetHtml: string, contentHtml: string) => {
+    html: string;
+    notes: string[];
+};
+/**
+ * A page and the changes to make to it, whether that is one or several.
+ *
+ * Several ride in one `PATCH`, which is what Graph's array of change objects is
+ * for and which this used to send one command at a time. The reason to batch is
+ * not only the round trips: generated ids move after *every* write, so eight
+ * changes applied one by one means eight reads, and every one of them is a
+ * chance for the page to have moved under the sequence. One command array
+ * resolves every target against a single read.
+ *
+ * That was verified rather than assumed, and so was the thing that makes it
+ * safe to approve as one step: a batch containing one unresolvable target
+ * applies **nothing** — `400`, and the page untouched. See
+ * scripts/spike-onenote-batch.mjs. A batch that half-applied would be a page in
+ * a state nobody previewed and nobody agreed to, and this capability would not
+ * be worth having.
+ */
 export declare const editFrom: (params: Record<string, unknown>) => EditDraft;
 /**
  * The token a preview returns and an edit must carry back.
@@ -117,7 +190,60 @@ export declare const editFrom: (params: Record<string, unknown>) => EditDraft;
  * Hashing the pre-image makes that case fail closed: the edit is refused unless
  * the element still holds exactly what the musician was shown.
  */
-export declare const editToken: (draft: EditDraft, preImageHtml: string) => Promise<string>;
+export declare const editToken: (draft: EditDraft, preImages: string[]) => Promise<string>;
+/** A table as its cell text, row by row. */
+export declare const tableRows: (tableHtml: string) => string[][];
+/**
+ * A table as something a musician can read and say yes or no to.
+ *
+ * This is the difference between a whole-table replace being previewable and
+ * not. The thing a replace destroys is a block of markup hundreds of characters
+ * wide; shown raw it is not a preview, it is a wall that gets approved unread —
+ * and an approval nobody could read is exactly the failure the confirmation
+ * step exists to prevent. So the table is shown as its rows.
+ *
+ * **Nothing is ever cut.** This originally clipped a cell at forty characters
+ * with an ellipsis, on the reasoning that the shape of the table is what a
+ * reader checks. That was wrong in the case these pages are mostly made of: a
+ * single-cell table holding a paragraph of free text, where the whole change
+ * lives past the fortieth character. Both halves of the preview then rendered
+ * to the same truncated line, and the preview asserted in effect that a
+ * destructive change was a no-op. Found in use, not by any test here — the test
+ * asserted the ellipsis was present, which is how a defect gets a green tick.
+ *
+ * So a long cell wraps within its column instead. A wrapped preview is longer
+ * to read; a truncated one cannot be read at all.
+ *
+ * `marks` optionally prefixes each row, from `markRows`. The mark sits outside
+ * the table so the columns still line up under it.
+ */
+export declare const renderTable: (tableHtml: string, marks?: string[]) => string;
+export declare const renderRows: (rows: string[][], marks?: string[]) => string;
+/**
+ * Which rows a replace actually changes, matched up rather than compared by
+ * position.
+ *
+ * A row inserted near the top shifts every row under it, and comparing by index
+ * would then mark the whole table as changed — which tells a reader as little
+ * as marking none of it. So the two row lists are matched by their longest
+ * common subsequence, and only what is genuinely new, gone or altered is
+ * marked.
+ */
+export declare const markRows: (before: string[][], after: string[][]) => {
+    before: string[];
+    after: string[];
+};
+/**
+ * A fragment of several elements, each rendered as what it is.
+ *
+ * A replacement may now be a paragraph, a heading and a table at once, and
+ * running the whole thing through `asText` turned the table back into a column
+ * of loose lines — the same flattening `copy-onenote-page.mjs` refuses for the
+ * same reason. The reader has to be able to see that a table is arriving.
+ */
+export declare const renderFragment: (html: string) => string;
+/** Whether a generated id names a table, which decides what may be done to it. */
+export declare const isTableId: (id: string) => boolean;
 /**
  * What the page currently says, element by element, so a caller can name the
  * part to change without guessing an id.
@@ -127,13 +253,12 @@ export declare const editToken: (draft: EditDraft, preImageHtml: string) => Prom
  * quoted back in a later session — Microsoft says they "might change after a
  * page update", and that was observed rather than merely read.
  */
-export declare const readEditableParts: (token: string, pageId: string) => Promise<{
+export declare const readEditableParts: (token: string, pageId: string, { full }?: {
+    full?: boolean;
+}) => Promise<{
     html: string;
     etag: string | null;
-    parts: {
-        element_id: string;
-        text: string;
-    }[];
+    parts: EditablePart[];
 }>;
 /**
  * Show the change that would be made, and hand back the token making it needs.
@@ -143,33 +268,35 @@ export declare const readEditableParts: (token: string, pageId: string) => Promi
 export declare function previewEdit(token: string, params: Record<string, unknown>): Promise<{
     preview: null;
     page_id: string;
-    parts: {
-        element_id: string;
-        text: string;
-    }[];
+    parts: EditablePart[];
+    abbreviated: boolean;
     confirmation_token: null;
     note: string;
 } | {
     preview: string;
     page_id: string;
-    parts: {
-        element_id: string;
-        text: string;
-    }[];
+    parts: EditablePart[];
+    abbreviated: boolean;
     confirmation_token: string;
     note: string;
 }>;
 /**
- * Apply the change, having shown it.
+ * Apply the change, or the batch of them, having shown it.
  *
  * The page is read again here rather than trusted from the preview, and that is
- * not caution: generated ids move after any page update, so an id that was
- * right at preview may name something else by now. Re-reading also produces the
- * ETag that goes out as `If-Match`, which is what makes the musician typing in
+ * not caution: generated ids move after any page update, so an id that was right
+ * at preview may name something else by now. Re-reading also produces the ETag
+ * that goes out as `If-Match`, which is what makes the musician typing in
  * OneNote between the two calls a refusal rather than a silent overwrite.
  *
- * The confirmation token is checked against the payload *and* the pre-image, so
- * an element whose content changed since the preview fails closed.
+ * The confirmation token is checked against every change *and* every pre-image,
+ * so a batch fails closed if any element it would overwrite has changed since
+ * the preview — not merely the one that moved.
+ *
+ * All the commands go out in one `PATCH`, which is what Graph's array is for.
+ * A batch containing an unresolvable target applies nothing at all, verified
+ * against a real page, so there is no state in which half a confirmed batch is
+ * on the page.
  */
 export declare function applyEdit(token: string, params: Record<string, unknown>, record: RecordWrite): Promise<{
     changed: boolean;