Explicit continuation contract

All responses, instructions and outputs below are independently authored teaching materials, not actual service responses or measured model results.

Use case

A task cannot finish in one response, but the next attempt must resume correctly. An API returns one page of records, or a twelve-section document reaches its response budget after section six. These need different continuation materials: a service-issued cursor for the API, and an authored next-unit pointer for generated content.

First establish the API’s paging contract or the document outline. Field names and completion rules below are teaching conventions; actual calls follow the API documentation.

Mechanism

API pagination:

1. Save the records and next-page cursor exactly as returned. A cursor is a service-provided continuation marker, not a page number you calculate.
2. Report this page’s count and the accumulated count. Report total and remaining counts only when authoritative data supplies the total; otherwise mark them unknown.
3. Determine whether another page exists using the API contract. A valid next cursor means partial results; save it unchanged and pass it in the documented parameter next time.
4. If continuation is unavailable, the cursor expires or the request fails, retain collected results and report the reason. Do not invent a replacement cursor.

Generated documents:

1. Fix the ordered outline first and record the last complete section as work proceeds.
2. Stop after a complete section. State the actual completed count, known or unknown total, and next section.
3. Supply the outline, continuation record and necessary previous context next time. Resume at that section. If interruption was inside a section, mark it incomplete and complete or rewrite that section first.

Bad example

Shared API material: page one returns records A and B, next_cursor="svc:page-2:demo", and total=null. The teaching API defines next_cursor=null as its final-page signal. The teaching second-page response is items=[C], next_cursor=null, total=null. Both versions use the same response fixtures.

Collect all API records. After A and B, mark the result complete, write total=2 and invent C20 as the next cursor.

Shared document material: sections 1 through 12 are planned; sections 1 through 6 are complete and section 7 has not started.

The twelve-section document has reached section six. Mark delivery complete. Start over next time and use API cursor C20 as the continuation position.

The first instruction invents a total and token. The second labels partial work complete and mixes document pointers with API tokens. Both discard the actual continuation state.

Good example

API task: retain the same page-one material:

Collect all API records. Retain A and B from page one; report two returned and two accumulated.
total=null means total and remaining count are unknown. A non-null next_cursor means partial results.
Save svc:page-2:demo exactly as returned and pass it in the API's documented cursor parameter next time; do not rewrite or invent tokens.
The teaching next response is items=[C], next_cursor=null, total=null. Under this API's final-page rule, mark complete with three accumulated records; no total has been supplied by the service.
If a real API has no valid continuation method or the cursor fails, report inability to continue rather than claiming completeness.

svc:page-2:demo is an illustrative value in a teaching response. Replace it with the full actual service-issued value. Illustrative paging records are:

Page one: returned=2, accumulated=2, total=unknown, state=partial
next_cursor=svc:page-2:demo
Final page: returned=1, accumulated=3, total=unknown, state=complete (final-page signal)

Document task: retain the same outline and completion state:

Continue the twelve-section document. Sections 1 through 6 are complete; the next unit is section 7.
Outline: sections 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, delivered in this order.
Read completed content for consistent terminology, but start output at section 7 without repeating sections 1 through 6.
If the response budget runs short, stop after a complete section and report completed count, last complete section and next section.
Mark everything complete only after section 12 is fully finished. Section labels are not API cursors.

Supply your actual section titles and completed document, replacing the sample numbers. An illustrative pause record is 6/12 complete; last_complete_unit=section 6; next_unit=section 7; state=partial.

Why the change matters

An explicit partial state prevents a fragment from being mistaken for a complete result. Preserving the service cursor lets the API identify the next page. Recording a complete-section boundary identifies where generation resumes. Separate materials prevent an authored label from masquerading as a service-issued token.

Observable expectation

Inspect actual API responses, outgoing cursors and accumulated records. Cursor values match exactly, unknown totals are not guessed, and completion has a documented final-page signal. A service-supplied total of 2,000 with 20 accumulated records supports reporting 1,980 remaining; an absent total does not. Check duplicates and omission risks according to the API contract.

Compare the document with its outline: continuation starts at section 7, sections 1 through 6 are not redelivered, and the recorded last complete section matches the content. A missing section, a bare heading or a partially written section does not count as complete.

Limits

Cursors may expire and changing data may affect pagination consistency. Saving a token does not guarantee a stable snapshot. Final-page detection comes from the API contract. Document continuation needs the outline and relevant context; “continue” cannot recover lost content. Unsupported totals, execution outcomes and completion states remain unknown.