Production's survivable `chunk_size` exists only in an operator snippet, invisible to this repository

[TBarregren]

The finding

The production site that this project's only completed clone ran against has chunk_size set to 256 KB by an operator snippet, not by the plugin. That snippet is the only thing making a full clone survivable on that host — the shipped default of 8 MiB is measured to make the run impossible rather than slow — and it exists nowhere in this repository.

If it is removed, edited, or lost in a site migration, the next run dies, and nothing in the code, the docs or the tests says why.

What would close it

Three candidate answers, and choosing between them is the triage decision:

1. Make it unnecessary. A safe shipped default (DEFAULT_CHUNK_SIZE at 8 MiB is measured dangerous, not merely untuned — decide what it becomes #27) plus a per-run chunk_size on the create payload (Accept an optional chunk_size on POST /extractions — a capability addition, not an api_version bump #28) removes the reason the snippet exists. This is the preferred shape; the other two are what to do until it lands, or if it never fully does.
2. Record it. Document the snippet, the host it applies to, and the measurement that justifies it, somewhere a cold reader will meet it — the release procedure and the operations documentation are the candidates. This is cheap and is not a substitute for 1.
3. Detect it. Have the client report the effective chunk size it is about to run against, so an operator sees the value rather than assuming it.

Why it is being filed at all

This is the same class of problem that got plans/ tracked in both repositories: a fact that decides whether the system works, living on one machine and in one person's memory. It is worth an issue precisely because it is invisible to every automated check.

Evidence for the value: docs/measurements/2026-08-19-chunk-size-curve.md and docs/measurements/2026-08-19-successful-run.md. Both carry a "What this does not establish" section — one host, one file, nothing below 256 KB tested, and one success is not a rate.

Blocked by

Nothing. Largely superseded if #27 lands a safe default and #28 lands the per-run setting.

[TBarregren]

This was generated by AI during triage.

Triage outcome: ready-for-human, blocked by #27

The three candidate answers were weighed. The outcome is option 1, with option 3 rejected on evidence and option 2 absorbed into #27's documentation round.

Option 1 — make it unnecessary. Taken.

#27 is now ready-for-agent with 256 KB as the decided default. Once that ships, production's snippet pins exactly the value the plugin already ships, and losing it in a migration costs nothing. That removes the reason this issue exists.

Option 2 — record it. Absorbed into #27.

The knob table in README.md states the file-part default with no warning attached, which the measurement makes misleading. #27's brief requires that row to state the new default and the asymmetry — too large fails a run outright, too small only slows it. A cold reader meets the fact there. Nothing further is needed here.

Option 3 — detect it. Rejected, on two findings.

The existing disclosure machinery cannot see this snippet. GET /environment discloses defines by locating define() calls in the site's wp-config.php. The production override is not a define — it is a filter on kntnt_extractor_config_chunk_size, held in a Perfmatters code-snippet collection (materialised as an mu-plugin). No define exists, so there is no record to disclose, allow-list or withhold. Adding the name to DISCLOSABLE_DEFINE_NAMES would report nothing.

And reporting the resolved value would still be weak evidence. The Config seam is constant-then-filter, so what a reported configuration says and what a run actually spends can part company — a snippet registered after the filter has already fired reads as configured and is not in force. #28's acceptance criteria already make this argument and land on the honest alternative: the part count is the only confirmation that the setting is live, since a 36 MB file yields 139 parts at 256 KB and 9 at 4 MiB. That check exists and needs no new endpoint.

So option 3 is not deferred — it is answered. It should not be re-proposed without new evidence.

What is left, and why a human has to do it

One action, on production, after #27 ships:

• Remove the chunk_size snippet from the Perfmatters collection, or decide deliberately to keep it. Leaving it is not harmless indefinitely: it is a second copy of a number that will silently override any future change to the shipped default, and it lives somewhere no grep of this repository reaches.

Not delegable: it needs authenticated access to a production site's plugin UI and a judgment call about that host. No agent should touch it.

Verification available afterwards: submit a single-file extraction against a file large enough to need multiple parts and read the part count. It confirms what the run actually spends, which no configuration report can.

Closing condition

Close this once #27 has shipped and production's snippet has been removed or deliberately retained.

[TBarregren]

This was generated by AI during triage.

Supersedes the previous comment: ready-for-human → ready-for-agent

The earlier outcome scoped this to a one-off production action, which no agent should do. On reflection that was the wrong shape: a one-off action does not survive the next site, the next operator or the next default change. The durable form is a step in the release procedure, which is text in this repository and therefore delegable.

The one-off action still has to happen, but it is a checkbox you tick once #27 ships, not the content of this ticket.

Agent Brief

Category: documentation
Summary: Add a step to the release procedure that surfaces any site pinning chunk_size away from the shipped default.

Current behavior:
The production site depends on chunk_size being 256 KB, set by a filter held in a Perfmatters code-snippet collection. Nothing in this repository knows that. docs/release-procedure.md has no step that would surface it, and the knob table in README.md documents the default without saying what a wrong value costs.

Once #27 ships 256 KB as the default, that snippet becomes a second copy of the same number — harmless today, and a silent override of any future change to the shipped default.

Desired behavior:
The release procedure carries a step that makes a pinned override visible before a release goes out, so a stale pin is found rather than discovered by a failed run. The step must be performable by a human with site access and must state:

• Why an override may exist at all — 8 MiB was measured to make a run impossible rather than slow, and the right value is host-specific
• Where an override can hide. A wp-config.php define() is one place; a filter on kntnt_extractor_config_chunk_size is the other, and it may live in an mu-plugin or in a snippet-manager plugin's collection, which no file search of the site's plugins will find
• That an override matching the shipped default should be removed, and one deviating from it should be justified in writing or removed
• How to confirm what a run actually spends: read the part count, not the configuration. A 36 MB file yields 139 parts at 256 KB and 9 at 4 MiB. A snippet registered after the filter has fired reads as configured and is not in force, so the configuration cannot answer this and the part count can

Key interfaces:

• docs/release-procedure.md — a new step, written in the evidence-based shape the existing steps use
• The knob table in README.md — DEFAULT_CHUNK_SIZE at 8 MiB is measured dangerous, not merely untuned — decide what it becomes #27 already requires this row to state the new default and the asymmetry. Do not duplicate that work; if DEFAULT_CHUNK_SIZE at 8 MiB is measured dangerous, not merely untuned — decide what it becomes #27 has landed, reference it, and if it has not, leave the table alone

Acceptance criteria:

• docs/release-procedure.md carries the step, covering all four points above
• The step names both hiding places for an override, explicitly including a snippet-manager collection
• The step directs the reader to the part count rather than to any configuration report, and explains in one line why
• The step cites docs/measurements/2026-08-19-chunk-size-curve.md as the evidence for why the value matters
• No change to README.md's knob table, to any constant, or to any code
• CHANGELOG.md carries an Unreleased entry

Out of scope:

• Reporting the effective chunk size over REST. This was considered and rejected on evidence: GET /environment discloses define() calls it locates in wp-config.php, and the production override is a filter, so there is no record to disclose. A resolved-configuration report would also be weaker evidence than the part count, for the reason given above. Do not re-propose it
• Touching any live site
• Changing the shipped default — that is DEFAULT_CHUNK_SIZE at 8 MiB is measured dangerous, not merely untuned — decide what it becomes #27

The one action left for a human

Once #27 ships: remove the chunk_size snippet from the Perfmatters collection on production, or deliberately keep it. Not part of this ticket, and not for an agent.

[TBarregren]

Recorded by an unattended run: built and then verified independently against this ticket's acceptance criteria.