@@ -291,11 +291,14 @@ MINTSOFT_WEBHOOK_SWEEPER_PAGE_SIZE=250
 # MINTSOFT_WRITE_ALLOWED=
 # XERO_WRITE_ALLOWED_TENANT=
 #
-# PRODUCER-SIDE HOLD (NOT YET ENFORCED): the instant from which a decision module would let IMS
-# produce LIVE work for a destination (one UTC instant in ISO-8601 with an explicit Z). In this
-# version nothing in IMS reads these variables and no producer behaves differently because of them;
-# a grant alone permits the existing outbound writes through the transport. Producers will consult
-# the decision in later changes. Leave them unset. See docs/installation.md ("Producer-side hold").
+# PRODUCER-SIDE HOLD (ENFORCED ONLY FOR THE DESTINATIONS NAMED BELOW; UNSET BY DEFAULT): the instant from which
+# IMS may produce LIVE work for a destination (one UTC instant in ISO-8601 with an explicit Z), and the list of
+# destinations whose producers obey the decision at all. Unset, every producer queues work exactly as before and a
+# grant alone permits the outbound writes through the transport. Today only the Xero producers consult the
+# decision; naming mintsoft or woocommerce changes nothing for them yet. With xero named and no grant and no
+# live-from instant set, every new Xero write becomes a recorded shadow and the Xero queue receives nothing new.
+# Leave all of these unset unless you mean to hold Xero. See docs/installation.md ("Producer-side hold").
+# PRODUCER_HOLD_ENFORCED_DESTINATIONS=
 # XERO_WRITES_LIVE_FROM=
 # MINTSOFT_WRITES_LIVE_FROM=
 # WC_WRITES_LIVE_FROM=
 
@@ -679,6 +679,11 @@ export async function generateMissingXeroTaxRates(
   reportTypeOverrides?: Record<string, string>,
 ): Promise<MissingTaxRateGenerateResult> {
   await requirePermission('settings.company')
+  // THE PRODUCER-SIDE HOLD, before anything is sent to Xero: this action writes straight to Xero with no queue row, so
+  // it asks here. A SHADOW is recorded and nothing is created (lib/domain/accounting/xero-direct-write-seam.ts).
+  const { xeroTaxRateWriteShadow } = await import('@/lib/domain/accounting/xero-direct-write-seam')
+  const shadow = await xeroTaxRateWriteShadow({ taxRateIds, reportTypeOverrides })
+  if (shadow) return { success: false, created: 0, failed: [], externalRatesCount: 0, supported: true, error: shadow.notice }
   try {
     const { getXeroTaxRates } = await import('@/lib/connectors/xero/accounts')
     const { putXeroTaxRate } = await import('@/lib/connectors/xero/tax-rates')
 
@@ -1,5 +1,6 @@
 'use server'
 
+import { xeroProducerSeamVerdict } from '@/lib/domain/accounting/xero-producer-seam'
 import { freshAuthFailureResult, requireFreshPermission, requirePermission, requireRole } from '@/lib/auth/server'
 
 import { revalidatePath } from 'next/cache'
@@ -746,6 +747,13 @@ export async function retryFailedXeroSync(
       // o3d-0m56 filter. The fence is run precisely to produce the reason: its CAS cannot match, and
       // it reads the row to say whether the STATUS or the ATTEMPT moved.
       if (entryId === undefined || expectedAttemptRevision === undefined) return { success: true, reset: 0 }
+      // THE PRODUCER-SIDE HOLD: this fence CAS can still land (the row may have failed since the candidate read above), and it
+      // writes PENDING, so the decision is asked on the row's own type and payload BEFORE the write. Held: the row stays FAILED.
+      const lateRow = await db.accountingSyncLog.findUnique({ where: { id: entryId }, select: { type: true, payload: true } })
+      if (lateRow) {
+        const lateHold = xeroProducerSeamVerdict({ connector: 'xero', type: String(lateRow.type), payload: lateRow.payload })
+        if (lateHold.kind === 'shadow') return { success: false, reset: 0, error: lateHold.notice }
+      }
       const outcome = await applyFencedAttemptDecision(db, {
         id: entryId,
         expectedAttemptRevision,
@@ -857,6 +865,13 @@ export async function retryFailedXeroSync(
         const allowed: typeof scopeCandidates = []
         const refused: Array<{ id: string; reason: string; tokenCount: number }> = []
         for (const candidate of scopeCandidates) {
+          // THE PRODUCER-SIDE HOLD AT THE RE-QUEUE: a row whose decision is SHADOW is not made claimable again. (The claim
+          // boundary in the processor would refuse to send it anyway; this stops the row cycling back to PENDING.)
+          const hold = xeroProducerSeamVerdict({ connector: 'xero', type: String(candidate.type), payload: candidate.payload })
+          if (hold.kind === 'shadow') {
+            refused.push({ id: candidate.id, reason: hold.notice, tokenCount: 1 })
+            continue
+          }
           const plan = planManualRetry({
             type: candidate.type,
             reference: `${candidate.referenceType} ${candidate.referenceId}`,
 
@@ -5094,23 +5094,35 @@ Runbook. If a feed is reported stale, first find out which side stopped: look at
 ### Producer-side hold: LIVE or SHADOW for each unit of work
 
 <!-- producer-disposition:overview -->
-THE PRODUCER-SIDE HOLD IS NOT YET ENFORCED. In this version it is a decision module only: nothing in IMS calls it, `npm run outbound:status` does not report on it, and every producer still queues work exactly as before. The only barrier is the outbound-write hold above, which reads a grant on its own: a destination whose grant is set permits the existing outbound writes through the transport whether or not the live-from variable below is set. The places that will consult the decision arrive in later changes, and the paragraphs below describe what the decision returns, not what IMS does today.
+THE PRODUCER-SIDE HOLD IS ENFORCED ONLY FOR THE DESTINATIONS NAMED IN `PRODUCER_HOLD_ENFORCED_DESTINATIONS`, WHICH IS UNSET BY DEFAULT. Unset, every producer queues work exactly as it did before the decision existed, and the only barrier is the outbound-write hold above, which reads a grant on its own: a destination whose grant is set permits the outbound writes through the transport whether or not the live-from variable below is set. Today only the Xero producers consult the decision (every place IMS creates an accounting sync log row, and the direct tax-rate creation from Settings; the one sync log type whose destination is WooCommerce, the invoice note, follows the WooCommerce setting); the WooCommerce and Mintsoft producers do not yet, so naming them in the variable changes nothing for them in this version, and `npm run outbound:status` does not report on the decision.
 
-For each destination and operation the decision is LIVE or SHADOW. A SHADOW is the record of what IMS would have written, which a later change will keep instead of queuing the work; it is never to be delivered later. The decision reads the environment only: no database and no network call. It is LIVE only when every one of these holds, and SHADOW otherwise: the outbound-write grant for the destination is readable; the live-from variable for the destination is set and readable; the current time is at or after it; the ownership map says IMS owns that operation in the installation phase that follows from the two; and the time of the business event is at or after the live-from instant (an operation whose ownership-map row requires that time is SHADOW when the producer does not supply it). A value that is absent, unreadable or inconsistent is never LIVE. There is no phase setting: an installation is in its live phase for a destination exactly when the grant and the live-from instant are both in force, so a restored backup, a clone or a new checkout never inherits it.
+For each destination and operation the decision is LIVE or SHADOW. It is LIVE only when every one of these holds, and SHADOW otherwise: the outbound-write grant for the destination is readable; the live-from variable for the destination is set and readable; the current time is at or after it; the ownership map says IMS owns that operation in the installation phase that follows from the two; and the time of the business event is at or after the live-from instant (an operation whose ownership-map row requires that time is SHADOW when the producer does not supply it). A value that is absent, unreadable or inconsistent is never LIVE. There is no phase setting: an installation is in its live phase for a destination exactly when the grant and the live-from instant are both in force, so a restored backup, a clone or a new checkout never inherits it. The decision itself reads the environment only: no database and no network call.
 
-A grant without a live-from instant, or a live-from instant without a grant, is inconsistent: the decision is SHADOW, while today the transport still allows the writes of a granted destination. A later change will report the inconsistency in `npm run outbound:status`. Never move a live-from instant earlier once work has been produced after it: that is the only change that lets work from before the move reach the destination.
+A SHADOW is the record of what IMS would have written, kept instead of queuing the work; it is never delivered later. For Xero a shadow is a row in the accounting sync log that is CANCELLED with the settlement basis `HELD_SHADOW`, plus a row in `outbound_shadow_writes` (one per distinct piece of work, counting repeats). A shadow has no outbox job, is never given an accounting event, and has its own ledger standing (shadow, not sent by IMS) that is NOT proof the document is absent from Xero: it says nothing about whether the owner of the operation wrote it, so deleting, reversing or refunding over it is refused as unproven. A destination whose enforcement is on and whose grant and live-from instant are both unset therefore queues nothing new: every Xero write IMS would have produced becomes a shadow.
+
+A grant without a live-from instant, or a live-from instant without a grant, is inconsistent: the decision is SHADOW, while the transport still allows the writes of a granted destination. A later change will report the inconsistency in `npm run outbound:status`. Never move a live-from instant earlier once work has been produced after it: that is the only change that lets work from before the move reach the destination. Rows already queued when enforcement is switched on are not changed, but the Xero queue processor asks the same decision immediately before it sends: a row whose decision is not LIVE is handed back unsent with the operator text (no retry is spent) and is never posted, and a manual re-queue or the daily-batch reset leaves such a row unclaimable. A later change will also refuse to deliver a row created before the live-from instant and retire the backlog.
 <!-- /producer-disposition:overview -->
 
+Retention and the shadow record: a shadow's sync-log row expires with the sync-log retention window (it holds no ledger claim), but the `outbound_shadow_writes` record does not, and the readers that would destroy the local record of a document (the sales-order hard delete, an edit of a posted stock movement, a stored invoice-number correction) go on refusing from that record after the row is gone; the payment-receipt retract is the one known reader that cannot yet do so (tracked). With enforcement OFF the daily-batch re-queue runs its original statement unchanged.
+
 <!-- producer-disposition:cutoffs -->
 | Variable | Destination | Value |
 |---|---|---|
 | `WC_WRITES_LIVE_FROM` | WooCommerce | one UTC instant in ISO-8601 with an explicit Z, for example 2026-12-01T00:00:00Z |
 | `MINTSOFT_WRITES_LIVE_FROM` | Mintsoft | one UTC instant in ISO-8601 with an explicit Z, for example 2026-12-01T00:00:00Z |
 | `XERO_WRITES_LIVE_FROM` | Xero | one UTC instant in ISO-8601 with an explicit Z, for example 2026-12-01T00:00:00Z |
 
-Each variable names one instant. A date without a time, a time without the Z, an offset such as +01:00, precision finer than a millisecond, surrounding whitespace, a list or any other shape is unreadable, and the decision for that destination is SHADOW. Setting a variable changes nothing in this version, because nothing consults it yet; in later changes, once the producers consult the decision, each destination will need its outbound-write grant as well, and the ownership map will decide which operations IMS may produce.
+Each variable names one instant. A date without a time, a time without the Z, an offset such as +01:00, precision finer than a millisecond, surrounding whitespace, a list or any other shape is unreadable, and the decision for that destination is SHADOW. A destination needs its outbound-write grant as well as its live-from instant before the decision can be LIVE, and the ownership map decides which operations IMS may produce. A variable has an effect only for a destination named in `PRODUCER_HOLD_ENFORCED_DESTINATIONS`.
 <!-- /producer-disposition:cutoffs -->
 
+<!-- producer-disposition:enforcement -->
+| Variable | Value |
+|---|---|
+| `PRODUCER_HOLD_ENFORCED_DESTINATIONS` | a comma-separated list of destinations from xero, mintsoft and woocommerce, or all; unset or empty enforces nothing |
+
+Names the destinations whose producers obey the decision. A destination that is named obeys it for every operation; one that is not named is untouched. A value that is not a list of known destinations or `all` (a misspelling, a destination that does not exist) enforces EVERY destination, because a typo must not leave a hold off. Switching it on for Xero on an installation with no grant and no live-from instant makes every new Xero write a shadow and stops the Xero queue from receiving new work; switching it off again does not recover shadows, which are records and not queued work. Do not switch it on for WooCommerce or Mintsoft in this version: those producers do not consult the decision yet.
+<!-- /producer-disposition:enforcement -->
+
 
 ### Connection pooling in front of `DATABASE_URL` is not supported
 
 
@@ -1987,6 +1987,7 @@ The sync log at **Integrations → Xero** shows queued transactions for the **cu
 - **Failed** — Failed after 5 retries (shows error message)
 
 - **Cancelled** (shown as **Retired**) — the row was taken out of the queue rather than completed. Usually nothing was posted (a sales order cancelled before its invoice went out, an orphaned queue row swept up). **Sometimes something was**: when the repair sweep retires a row because the sale is not live, the Xero document it names is real and is kept on the row on purpose. No sweep re-queues a retired row.
+- **Cancelled, with the reason "Not sent by IMS: writes to Xero are held on this installation (…)"** — a *shadow*. The producer-side hold recorded what IMS would have queued instead of queuing it (see "Producer-side hold" in the installation guide). It has no Xero document id, was never claimable, has no outbox job and no accounting event, and carries a **shadow** badge on this page whose tooltip says IMS did not send it. It says nothing about whether the owner it names (Xeroom, Qoblex's own Xero integration, an operator working by hand) wrote the document to Xero, so it counts as **unproven**, not as absent: deleting an order, deleting a payment receipt, reversing or re-posting over a shadow is refused until Xero itself has been checked. A queued entry that already existed when the hold was switched on is not changed, but it is handed back unsent (activity `xero_sync_producer_held_before_post`) instead of being posted while the hold says it may not be. Shadows exist only on an installation that names Xero in `PRODUCER_HOLD_ENFORCED_DESTINATIONS`; the same piece of work produced again is counted on one shadow record rather than added as another row, and Retry and Retry All never touch a shadow (they only touch Failed rows). A Failed entry that the hold would now shadow is not retried either (Retry and Retry All leave it Failed and name the hold), and neither the automatic follow-up revival nor the daily-batch reset turns it back into queued work. **The shadow row expires with the sync-log retention period, the shadow record does not.** Once the row has been deleted, deleting an order, correcting a stored invoice number and editing a posted stock adjustment are still refused, from the persistent shadow record, with the same unproven wording. One gap is known and tracked: deleting a payment receipt after the shadow row has expired is not yet refused on the shadow record, because that record does not yet carry the payment it was for.
 
 Failed entries can be investigated via the error message and retried by resetting their status in the database.
 
 
@@ -329,12 +329,20 @@ export type ConnectorEnqueueOutcome = {
    * still going to post, and rolling back an empty transaction while telling the operator "nothing
    * was sent" is the one message that guarantees nobody goes looking for it.
    */
-  reason?: 'not-configured' | 'refused' | 'already-queued' | 'handled-by-hand' | 'hand-post-deferred'
+  reason?: 'not-configured' | 'refused' | 'already-queued' | 'handled-by-hand' | 'hand-post-deferred' | 'shadowed'
   /*
    * `handled-by-hand` (o3d-j625 r7) — `queued: true` WITHOUT A WRITE, like `already-queued`: someone
    * marked this exact posting handled after posting it BY HAND, so IMS did not post it and never will
    * (posting-suppression.ts). A counterpart exists in the ledger; it is not owed; it was not IMS's.
    */
+  /*
+   * `shadowed` (producer-side hold) — `queued: true` WITHOUT A QUEUED POSTING: the producer-side hold said SHADOW for this
+   * posting (lib/security/producer-disposition.ts), so IMS recorded a shadow and created no outbox job and no accounting
+   * event. `queued: true` is the answer the business flows need - the purchase is received, the payment is registered,
+   * the batch ran - and `postingIsOwed` is false: IMS owes the ledger nothing here, because in the current phase another
+   * writer owns the operation (or none does). It is NOT a statement that the document exists in the ledger, and no caller
+   * may read it as one; the ledger standing of the shadow row is SHADOW_NOT_SENT_BY_IMS: IMS did not send it, and that is not proof of absence.
+   */
   /*
    * `hand-post-deferred` (o3d-j625 r18, Codex round 17 HIGH 1) — `queued: FALSE`, and the difference from
    * `handled-by-hand` is the whole of round 17's HIGH 1. An operator holds the hand-posting CLAIM on this
@@ -1661,6 +1669,10 @@ export async function queueAccountingSyncTx(
       if (created.suppressed === 'handled_by_hand') return answer({ queued: true, reason: 'handled-by-hand' }, context.connector)
       return answer({ queued: false, reason: 'hand-post-deferred' }, context.connector)
     }
+    // THE PRODUCER-SIDE HOLD SAID SHADOW: the posting is recorded as a shadow and nothing is queued - no outbox job and no
+    // accounting event (a shadow must not count as an IMS ledger fact). `queued: true`, with its own reason, because the
+    // posting is recorded and nothing is owed to IMS's queue; see 'shadowed' on ConnectorEnqueueOutcome.
+    if (created.shadowed) return answer({ queued: true, reason: 'shadowed' }, context.connector)
     const log = created.row
     if (context.connector === 'xero') {
       const { scheduleXeroAccountingOutbox } = await import('@/lib/connectors/xero/outbox')