Record ArtifactReader ownership decision

This commit is contained in:
2026-11-05 03:48:04 +00:00
parent aa08d46ef6
commit e8e112186e

View File

@@ -56,10 +56,11 @@ Sources: [Resources 2](05-resources.md#2-convenience-source-conversion-expands-s
**Confirmed race under the documented collaborator contract.** The public **Confirmed race under the documented collaborator contract.** The public
reader contract permits buffer reuse after `Read` returns, before PromptKit reader contract permits buffer reuse after `Read` returns, before PromptKit
can finish copying it. Concurrent preparation with a compliant custom reader can finish copying it. Concurrent preparation with a compliant custom reader
can race. Clarify ownership/lifetime per invocation and align adapters, GoDoc, can race. [Decision 1](#decision-1-artifactreader-result-ownership-and-lifetime)
and concurrency tests. This needs a deliberate public-contract decision before selects ownership transfer on successful return; implementation remains pending.
v1.0: an immediate copy alone cannot guarantee safety if the reader is allowed Align adapters, GoDoc, and concurrency tests with that rule. An immediate copy
to mutate the buffer immediately. No default-reader defect was established. alone cannot guarantee safety under the old immediate-reuse permission. No
default-reader defect was established.
Sources: [Interfaces 1](09-interfaces.md#1-artifactreader-permits-buffer-reuse-before-promptkit-can-copy-it). Sources: [Interfaces 1](09-interfaces.md#1-artifactreader-permits-buffer-reuse-before-promptkit-can-copy-it).
@@ -443,40 +444,48 @@ This is not a second scheduling algorithm or a confirmed concurrency defect.
Sources: [Boundaries 1](11-boundaries.md#1-retire-the-test-only-capacity-client-as-a-production-scheduling-surface), Sources: [Boundaries 1](11-boundaries.md#1-retire-the-test-only-capacity-client-as-a-production-scheduling-surface),
[Dead-code retention qualification](12-deadcode.md#intentional-retention-and-related-findings). [Dead-code retention qualification](12-deadcode.md#intentional-retention-and-related-findings).
## Open Decisions ## Resolved Decisions
Work through the decisions below in this order. These are unresolved choices,
not additional findings or approved changes to public contracts. A decision
blocks its dependent remediation, not unrelated fixes. In particular, updating
the maintainer toolchain need not wait for the consumer-minimum decision.
Implementation details and optional cleanup do not become release gates merely
by appearing in this catalog.
### Decision 1: ArtifactReader Result Ownership And Lifetime ### Decision 1: ArtifactReader Result Ownership And Lifetime
**Related finding:** [4](#4-resolve-the-artifactreader-buffer-ownership-contract). **Related finding:** [4](#4-resolve-the-artifactreader-buffer-ownership-contract).
**Question:** What ownership does a successful `Read` transfer, and when may **Status:** Accepted; implementation pending.
an injected reader mutate or reuse the returned storage?
**Recommendation:** Transfer an independent result to PromptKit on successful **Decision:** A successful `Read` transfers the returned artifact and its mutable
return. The reader must stop mutating the returned artifact and its body, body storage to PromptKit. The reader must stop mutating the returned artifact
including through retained aliases. Fresh per-invocation storage is the simplest and body, including through retained aliases. Fresh independent results are the
implementation; immutable shared data can remain shared if no collaborator simplest implementation. A reader may reuse private working buffers if it copies
mutates it. This removes the impossible immediate-reuse permission without into independent result storage before returning.
adding synchronization or a release protocol to the interface. Explain the
consumer impact as a deliberate pre-1.0 contract correction.
**Alternative:** Permit borrowing until the enclosing preparation/execution Keep the existing interface signature and defensive adapter copy initially.
operation returns. This can support application-managed reuse, but a reader Removing redundant copies is a separate optimization, not part of this contract
cannot generally observe that lifetime and concurrent calls need independent correction. No borrowing lifetime or acknowledgement/release API is introduced.
storage or caller coordination. If reuse immediately after `Read` returns is
required, an explicit acknowledgement/release API is another viable design;
it enables pooling at the cost of a larger interface and lifecycle change.
**Resolve before implementation:** Select the ownership/lifetime rule and update **Rationale:** The reader controls storage until return and can therefore make
GoDoc, adapter assumptions, and the regression scenario together. Another that handoff safe. Copying only after return cannot make the current permission
unsynchronized copy is not a remedy for the current permission. to immediately reuse storage safe; a reader-local mutex also cannot protect the
caller's later copy.
**Alternatives considered:** Borrowing until the enclosing operation returns
makes the lifetime difficult for a reader to observe and requires coordination
across concurrent calls. An explicit release protocol enables pooling but adds
lifecycle machinery. Caller-provided buffers or streaming would require a
broader interface redesign. None is needed for this correction.
**Remediation follow-through:** Update GoDoc, adapter assumptions, and concurrency
regressions together. Explain the migration for readers that reuse returned
storage in release notes as a deliberate pre-1.0 contract correction. This
record does not itself implement the change.
## Open Decisions
Work through the remaining decisions below in order, retaining their original
numbers. These are unresolved choices, not additional findings or approved
changes to public contracts. A decision blocks its dependent remediation, not
unrelated fixes. In particular, updating the maintainer toolchain need not wait
for the consumer-minimum decision. Implementation details and optional cleanup
do not become release gates merely by appearing in this catalog.
### Decision 2: Provider Submission Of Multi-Resource Schemas ### Decision 2: Provider Submission Of Multi-Resource Schemas