Record ArtifactReader ownership decision
This commit is contained in:
@@ -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
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user