fix: preserve semantic image evidence tables

CHANGELOG.md

@@ -13,6 +13,11 @@ All notable changes to this project are documented here. Format follows
   semantic-unit parser and buyer body renderer. See the [product and
   technical gap baseline](docs/product-technical-gap-baseline.md) and
   [ADR 0103](docs/adr/0103-semantic-document-evidence-contract.md).
+- Preserve multiline VISION table rows, render parent and region OCR tables
+  accessibly, and request source-visible entity, relationship, layout, and
+  document-purpose evidence instead of a generic image caption. VISION calls
+  now share the structure channel's 600-second deep-agent runtime boundary;
+  an empty same-image retry can no longer erase previously observed OCR.
 
 - `make smoke` and `make seed` now run through the locked project `uv`
   environment, so local OIDC and synthetic-data workflows resolve the same

docker/contextual-orchestrator/start.py

@@ -14,9 +14,11 @@
 
 
 def _pop_first_env(*names: str) -> str:
-    """Read the first configured alias without leaving credentials in the environment."""
+    """Read the first alias, removing quotes preserved by Docker env files."""
     for name in names:
         value = os.environ.pop(name, "").strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}:
+            value = value[1:-1]
         if value:
             return value
     return ""

docs/adr/0103-semantic-document-evidence-contract.md

@@ -36,6 +36,16 @@ recognizable header/separator/data shape and otherwise preserves plain text.
 5. Keep the frontend's raw-source fallback aligned with the persisted unit
    labels. Persisted row units render as accessible tables; unresolved
    structure remains visibly unresolved and actionable.
+6. Apply the same narrow Markdown-table renderer to persisted image OCR.
+   VISION output may use multiple `TEXT` lines so row boundaries survive; its
+   caption names only visible entities, relationships, layout, and document
+   purpose rather than offering a generic one-sentence description. The
+   client allows 600 seconds for deep orchestrator work; a 180-second local
+   cutoff already terminated a valid live response before delivery.
+7. Serialize replacement per source post and reject a same-image retry when
+   its content hash matches non-empty persisted OCR but the retry returns no
+   OCR. Provider completion is transport evidence, not permission to erase a
+   stronger prior observation.
 
 ## Rejected alternatives
 
@@ -54,6 +64,8 @@ recognizable header/separator/data shape and otherwise preserves plain text.
   markup or image base64.
 - The database keeps the existing normalized unit tables; this decision adds
   no denormalized JSON field or new service.
+- A weaker same-image VISION retry fails before replacement, leaving the
+  prior committed evidence available for a later orchestrator retry.
 - Markdown dialects outside the narrow recognized shape remain plain text and
   are reported as a future parser extension rather than guessed.
 
@@ -62,4 +74,5 @@ recognizable header/separator/data shape and otherwise preserves plain text.
 The baseline's synthetic tests cover numeric superscript footnotes, marker
 footnotes, nested `ol`/`ul`/`oi` order and depth, HTML/OOXML rows, Markdown
 rows, React table rendering, and unresolved indentation. Full CI remains the
-release gate.
+release gate. A persistence regression test proves that an empty same-hash
+VISION retry cannot delete previously observed OCR.

frontend/src/PostBody.stories.tsx

@@ -10,6 +10,9 @@ export default meta;
 
 type Story = StoryObj<typeof meta>;
 
+const TINY_PNG =
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=";
+
 export const MarkdownTableEvidence: Story = {
   args: {
     body: "| Workstream | State |\n| --- | --- |\n| Alpha | Ready |",
@@ -44,6 +47,22 @@ export const MarkdownTableFallback: Story = {
   },
 };
 
+export const ImageOcrTableEvidence: Story = {
+  args: {
+    body: `<img src="data:image/png;base64,${TINY_PNG}" />`,
+    imageContent: [
+      {
+        unit_index: 0,
+        mime_type: "image/png",
+        status_code: "completed",
+        extracted_text: "| Workstream | State |\n| --- | --- |\n| Alpha | Ready |",
+        caption: "A synthetic workstream status table.",
+        tags: ["table"],
+      },
+    ],
+  },
+};
+
 export const NumericFootnote: Story = {
   args: {
     body: "<p>Evidence remains attached to the source.</p><p><sup>1</sup> Source note.</p>",

frontend/src/PostBody.test.tsx

@@ -247,6 +247,43 @@ describe("PostBody", () => {
     expect(screen.getByText("Next action.")).toBeInTheDocument();
   });
 
+  it("renders table-shaped image OCR as accessible evidence", () => {
+    render(
+      <PostBody
+        body={'<img src="data:image/png;base64,QQ==" />'}
+        imageContent={[
+          {
+            unit_index: 0,
+            mime_type: "image/png",
+            status_code: "completed",
+            extracted_text: "| Project | Status |\n| --- | --- |\n| Alpha | Ready |",
+            caption: "A synthetic project status table.",
+            tags: ["table"],
+            regions: [
+              {
+                region_index: 0,
+                x_ratio: 0,
+                y_ratio: 0,
+                width_ratio: 1,
+                height_ratio: 1,
+                status_code: "completed",
+                extracted_text: "| Owner | Action |\n| --- | --- |\n| Team A | Review |",
+                caption: "The table region assigns an action to a team.",
+                tags: ["assignment"],
+              },
+            ],
+          },
+        ]}
+      />,
+    );
+
+    expect(screen.getAllByRole("table")).toHaveLength(2);
+    expect(screen.getByRole("columnheader", { name: "Project" })).toBeInTheDocument();
+    expect(screen.getByText("Ready")).toBeInTheDocument();
+    expect(screen.getByText("The table region assigns an action to a team.")).toBeInTheDocument();
+    expect(screen.getByRole("columnheader", { name: "Owner" })).toBeInTheDocument();
+  });
+
   it("keeps a persisted Markdown table row searchable", () => {
     render(
       <PostBody

frontend/src/PostBody.tsx

@@ -8,40 +8,6 @@ import { t } from "./i18n";
 import type { PostContentUnit, PostImageContent } from "./api";
 import type { ReactNode } from "react";
 
-function parsePipeDelimitedTable(text: string): string[][] | null {
-  const rows = text
-    .split(/\r?\n/)
-    .map((row) => {
-      const cells = row.split("|").map((cell) => cell.trim());
-      if (cells[0] === "") cells.shift();
-      if (cells[cells.length - 1] === "") cells.pop();
-      return cells;
-    })
-    .filter((row) => !row.every((cell) => /^:?-{3,}:?$/.test(cell)))
-    .filter((row) => row.length > 1 && row.some(Boolean));
-  if (rows.length < 2 || rows.some((row) => row.length !== rows[0].length)) return null;
-  if (rows[0].length < 2) return null;
-  return rows;
-}
-
-function renderImageText(text: string) {
-  const rows = parsePipeDelimitedTable(text);
-  if (!rows) return <p>{text}</p>;
-  return (
-    <table className="post-body-table post-image-text-table">
-      <tbody>
-        {rows.map((row, rowIndex) => (
-          <tr key={`post-image-text-row-${rowIndex}`}>
-            {row.map((cell, cellIndex) => (
-              <td key={`post-image-text-cell-${rowIndex}-${cellIndex}`}>{cell}</td>
-            ))}
-          </tr>
-        ))}
-      </tbody>
-    </table>
-  );
-}
-
 const SAFE_EMBEDDED_IMAGE_SOURCE =
   /^data:image\/(?:png|jpe?g|gif|webp|avif|bmp|x-icon|vnd\.microsoft\.icon);base64,[A-Za-z0-9+/]+={0,2}$/i;
 
@@ -68,7 +34,7 @@ function renderImageEvidence(
       {imageContent?.extracted_text ? (
         <details className="post-image-text">
           <summary>{t("Text detected in image")}</summary>
-          {renderImageText(imageContent.extracted_text)}
+          {renderExtractedText(imageContent.extracted_text)}
         </details>
       ) : null}
       {imageContent?.regions?.length ? (
@@ -77,7 +43,14 @@ function renderImageEvidence(
           <ol>
             {imageContent.regions.map((region) => (
               <li key={region.region_index}>
-                <span>{region.caption || region.extracted_text || t("Unknown")}</span>
+                {region.caption ? <p>{region.caption}</p> : null}
+                {region.extracted_text ? (
+                  <div className="post-image-region-text">
+                    {renderExtractedText(region.extracted_text)}
+                  </div>
+                ) : region.caption ? null : (
+                  t("Unknown")
+                )}
                 {region.tags.length ? (
                   <small>
                     {t("Image tags")}: {region.tags.join(", ")}
@@ -294,6 +267,11 @@ function renderMarkdownBlocks(blocks: MarkdownBodyBlock[]): ReactNode[] {
   });
 }
 
+function renderExtractedText(text: string): ReactNode {
+  const markdownBlocks = splitMarkdownTableBody(text);
+  return markdownBlocks ? renderMarkdownBlocks(markdownBlocks) : <p>{text}</p>;
+}
+
 export function PostBody({
   body,
   imageContent = [],

frontend/src/postBodyDisplay.test.ts

@@ -112,6 +112,15 @@ describe("splitPostBody", () => {
     ]);
   });
 
+  it("unescapes pipe characters inside Markdown cells without accepting a short delimiter", () => {
+    expect(
+      splitMarkdownTableBody(
+        "| Project | Notes |\n| :--- | ---: |\n| Alpha | Ready \\| review |",
+      ),
+    ).toEqual([{ kind: "table", rows: [["Project", "Notes"], ["Alpha", "Ready | review"]] }]);
+    expect(splitMarkdownTableBody("| Project | Status |\n| -- | -- |\n| Alpha | Ready |")).toBeNull();
+  });
+
   it("leaves a plain-text post unchanged so existing popups keep their wording", () => {
     expect(splitPostBody("The full body text.")).toEqual([
       { kind: "text", text: "The full body text." },

lineageweave/image_content.py

@@ -141,7 +141,8 @@ class ImageDescription:
     Attributes:
         extracted_text: OCR result -- every piece of legible text found in
             the image, empty string if none.
-        caption: one-sentence description of what the image shows.
+        caption: factual description of the visible entities, relationships,
+            and layout that make the image useful as semantic evidence.
         tags: short tags for the main objects/subjects, for independent
             keyword search separate from the free-text caption.
     """
@@ -177,15 +178,18 @@ def describe(self, image_bytes: bytes, mime_type: str) -> ImageDescription:  # p
 
 
 _RESPONSE_FORMAT = (
-    "Examine this image. Reply with EXACTLY three lines, no extra commentary:\n"
+    "Examine this image. Reply with exactly the three labeled sections below and no "
+    "extra commentary. TEXT may span multiple lines; CAPTION and TAGS stay on their "
+    "labeled lines.\n"
     "TEXT: <all legible text in the image, verbatim, or NONE if there is none. "
-    "If the image contains a table, preserve its row/column structure: one row "
-    "per line, with ' | ' between that row's cell values, in reading order -- "
-    "never flatten a table into an unstructured word list.>\n"
-    "CAPTION: <2-4 concise, evidence-grounded sentences describing the visible layout, "
-    "objects, relationships, directions, measurements, and labels; do not guess "
-    "anything that is not visible>\n"
-    "TAGS: <comma-separated short tags for the main objects/subjects>"
+    "If the image contains a table, preserve its row/column structure as a Markdown "
+    "pipe table: one row per line, with a separator row immediately after the visible "
+    "header. Never flatten a table into an unstructured word list or invent a header "
+    "that is not visible.>\n"
+    "CAPTION: <a concise factual paragraph naming visible named entities, their visible "
+    "relationships, the spatial or document layout, and the table/chart purpose when "
+    "present. Omit anything the pixels do not support.>\n"
+    "TAGS: <comma-separated short tags for visible named entities, objects, and document types>"
 )
 _REGION_RESPONSE_FORMAT = (
     "Find distinct meaningful visual regions in this image for separate OCR and description. "
@@ -254,10 +258,10 @@ def _parse_description(content: str) -> ImageDescription:
             multiline_field = "TEXT" if label == "TEXT" else None
             continue
 
-        if re.match(r"^\s*[*_`>#\-\s]*[A-Za-z][A-Za-z0-9 _-]*\s*:", line):
-            multiline_field = None
-            continue
         if multiline_field == "TEXT" and line.strip():
+            # A colon is common inside OCR (for example ``Date: 2026-08-21``).
+            # Only the known response labels above end the TEXT section;
+            # treating every colon as a provider label loses real image text.
             fields["TEXT"].append(_strip_outer_markdown_emphasis(line))
 
     if not fields["TEXT"] and not fields["CAPTION"]:
@@ -289,7 +293,7 @@ def __init__(
         api_key: str,
         model: str | None = None,
         *,
-        timeout: float = 180.0,
+        timeout: float = 600.0,
         allow_insecure_http: bool = False,
     ) -> None:
         parsed = urlparse(base_url)

lineageweave/post_content_persistence.py

@@ -84,12 +84,24 @@ async def persist_post_content(
 
     Provider calls happen before the short database transaction. A failed or
     unavailable embedding call writes no vector row; it never writes a zero or
-    guessed vector. The raw body remains in ``source_post`` for future retry.
+    guessed vector. A same-image retry cannot replace non-empty persisted OCR
+    with an empty result. The raw body remains in ``source_post`` for future
+    retry.
     """
     normalized = normalized_result or normalize_post_body(body, vision_client)
     chunks = chunk_by_source_body(body)
     image_results = {result.chunk_index: result for result in normalized.image_results}
     formatting = {hint.chunk_index: hint.style for hint in normalized.formatting_hints}
+    image_ocr_by_sha256: dict[str, bool] = {}
+    for chunk in chunks:
+        if chunk.unit_type != "image" or chunk.image_data is None:
+            continue
+        result = image_results.get(chunk.index)
+        description = result.description if result else None
+        content_sha256 = hashlib.sha256(chunk.image_data).hexdigest()
+        image_ocr_by_sha256[content_sha256] = image_ocr_by_sha256.get(
+            content_sha256, False
+        ) or bool(description and description.extracted_text.strip())
 
     prepared: list[tuple[Chunk, str, str | None]] = []
     for chunk in chunks:
@@ -226,6 +238,29 @@ async def persist_post_content(
                 )
 
     async with conn.transaction():
+        if image_ocr_by_sha256:
+            await conn.fetchval(
+                "select post_id from source_post where post_id = $1 for update",
+                post_id,
+            )
+            previous_images = await conn.fetch(
+                """
+                select image.content_sha256, image.extracted_text
+                  from post_content_unit unit
+                  join post_content_image image using (post_content_unit_id)
+                 where unit.post_id = $1
+                   and nullif(btrim(image.extracted_text), '') is not null
+                """,
+                post_id,
+            )
+            if any(
+                row["content_sha256"] in image_ocr_by_sha256
+                and not image_ocr_by_sha256[row["content_sha256"]]
+                for row in previous_images
+            ):
+                raise RuntimeError(
+                    "refusing to replace non-empty image OCR with an empty retry result"
+                )
         await conn.execute("delete from post_content_unit where post_id = $1", post_id)
         unit_ids: dict[int, str] = {}
         for chunk, unit_text, style in prepared:

scripts/backfill_post_content.py

@@ -55,6 +55,15 @@ def _parser() -> argparse.ArgumentParser:
     return parser
 
 
+async def _ensure_open_connection(
+    conn: asyncpg.Connection, target_dsn: str
+) -> asyncpg.Connection:
+    """Reconnect after a database restart without repeating VISION work."""
+    if not conn.is_closed():
+        return conn
+    return await asyncpg.connect(target_dsn)
+
+
 async def backfill_post_content(
     target_dsn: str,
     raw_post_ids: list[str] | None,
@@ -217,6 +226,7 @@ async def backfill_post_content(
                 if described_images == 0 and not normalized.text.strip():
                     result["skipped_posts"] += 1
                     continue
+                conn = await _ensure_open_connection(conn, target_dsn)
                 await persist_post_content(
                     conn,
                     str(row["post_id"]),