|
|
|
@@ -1,315 +1,683 @@
|
|
|
|
# Local Backend Convenience Implementation Plan
|
|
|
|
# Executable Preparation Handles Implementation Plan
|
|
|
|
|
|
|
|
|
|
|
|
**Status:** Complete.
|
|
|
|
**Status:** Accepted.
|
|
|
|
|
|
|
|
|
|
|
|
## Purpose
|
|
|
|
## Purpose
|
|
|
|
|
|
|
|
|
|
|
|
This document is the decision-complete implementation plan for
|
|
|
|
This document is the decision-complete implementation plan for
|
|
|
|
[local backend convenience](local-backend.md). It is written for a coding
|
|
|
|
[executable preparation handles](prepared-execution.md). It is written for a
|
|
|
|
agent that will implement each stage in order.
|
|
|
|
coding agent that will implement each stage in order.
|
|
|
|
|
|
|
|
|
|
|
|
The feature roadmap owns the motivation, consumer paths, policy choices,
|
|
|
|
The feature roadmap owns the motivation, consumer workflow, policy choices,
|
|
|
|
compatibility requirements, non-goals, and target end state. This document
|
|
|
|
compatibility requirements, non-goals, and target end state. This document
|
|
|
|
owns the exact proposed API, file-level changes, implementation sequence, test
|
|
|
|
owns the concrete design, file-level changes, implementation sequence, test
|
|
|
|
ownership, documentation work, validation commands, and completion gates.
|
|
|
|
ownership, documentation work, validation commands, and completion gates.
|
|
|
|
|
|
|
|
|
|
|
|
## Implementation Rules
|
|
|
|
## Implementation Rules
|
|
|
|
|
|
|
|
|
|
|
|
- Complete the stages in order. Keep the root package compiling and its
|
|
|
|
- Complete the stages in order. Keep the repository compiling and the focused
|
|
|
|
focused tests passing at every stage boundary.
|
|
|
|
tests passing at every stage boundary.
|
|
|
|
- Preserve unrelated working-tree changes. The feature roadmap may already be
|
|
|
|
- Preserve unrelated working-tree changes. In particular, retain the accepted
|
|
|
|
uncommitted when implementation begins; retain it.
|
|
|
|
roadmap and the downstream wishlist and future-roadmap edits that may
|
|
|
|
|
|
|
|
already be present.
|
|
|
|
- Follow every policy under `docs/policy/`, the task-specific reading guide in
|
|
|
|
- Follow every policy under `docs/policy/`, the task-specific reading guide in
|
|
|
|
`docs/development.md`, and the accepted behavior in
|
|
|
|
`docs/development.md`, and the accepted behavior in
|
|
|
|
`local-backend.md`.
|
|
|
|
`prepared-execution.md`.
|
|
|
|
- Keep the API in the root `promptkit` package. Do not add a public or internal
|
|
|
|
- Keep the supported API in the root `promptkit` package. Internal lifecycle,
|
|
|
|
package for this feature.
|
|
|
|
validation, and execution state must remain below Go's `internal/`
|
|
|
|
- Implement the helper as a transparent constructor for the existing
|
|
|
|
boundary.
|
|
|
|
`Backend` type. Do not add a second backend representation or bypass
|
|
|
|
- Preserve the observable behavior and ordering of existing `Engine.Prepare`
|
|
|
|
`WithBackend`.
|
|
|
|
and `Engine.Run`. Do not implement the new workflow by redefining either
|
|
|
|
- Leave normalization, validation, copying, registry construction, capacity
|
|
|
|
existing method in terms of the new public methods.
|
|
|
|
defaulting, and duplicate detection in their existing owners.
|
|
|
|
- Reuse preparation and post-preparation execution mechanics where their
|
|
|
|
- Do not add environment-variable discovery, package-global registration,
|
|
|
|
ordering is genuinely shared. Preserve `Run`'s existing early admission
|
|
|
|
implicit local defaults, model selection, profile construction, or support
|
|
|
|
boundary while ensuring `PrepareExecution` performs complete preparation
|
|
|
|
for non-OpenAI-compatible transports.
|
|
|
|
without admission.
|
|
|
|
- Keep tests lean and behavior-focused. Do not duplicate the existing
|
|
|
|
- Do not add durable serialization, retries, provider failover, background
|
|
|
|
registry and concurrency test matrices merely because the constructor
|
|
|
|
workers, a task queue, capacity reservation during preparation, or
|
|
|
|
reaches those mechanisms.
|
|
|
|
consumer-specific persistence and redaction policy.
|
|
|
|
- Update exact GoDoc with the exported declarations. Update current-state
|
|
|
|
- Keep direct API-key values in private execution state only. Every public
|
|
|
|
consumer guidance only after the corresponding API is implemented.
|
|
|
|
details value, formatted handle, JSON value, result, hash, and error must
|
|
|
|
- Do not update release notes, create a release, change a module version, or
|
|
|
|
remain credential-free.
|
|
|
|
tag a commit as part of this work.
|
|
|
|
- Keep tests lean but give durable coverage to the public compatibility,
|
|
|
|
|
|
|
|
security, concurrency, one-attempt, source-snapshot, cancellation, and
|
|
|
|
|
|
|
|
capacity invariants. Use real internal collaborators where they are fast and
|
|
|
|
|
|
|
|
deterministic and fakes at model-generation and synchronization boundaries.
|
|
|
|
|
|
|
|
- Update exact GoDoc with exported declarations. Update current-state
|
|
|
|
|
|
|
|
consumer and internal documentation only after the corresponding behavior
|
|
|
|
|
|
|
|
exists.
|
|
|
|
|
|
|
|
- Do not add release notes, change a module version, create a release, or tag
|
|
|
|
|
|
|
|
a commit as part of this work.
|
|
|
|
|
|
|
|
|
|
|
|
## Fixed Design
|
|
|
|
## Fixed Design
|
|
|
|
|
|
|
|
|
|
|
|
### Exported API
|
|
|
|
### Public API
|
|
|
|
|
|
|
|
|
|
|
|
Add these declarations to `backends.go` in package `promptkit`:
|
|
|
|
Add an opaque root-package type and these methods:
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
```go
|
|
|
|
// BackendLocal is the conventional ID used by LocalBackend. It is not a
|
|
|
|
type PreparedExecution struct {
|
|
|
|
// built-in or reserved backend and must be registered with WithBackend.
|
|
|
|
// Unexported Promptkit-owned state only.
|
|
|
|
const BackendLocal = "local"
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
// LocalBackend returns a Backend for a conventional local OpenAI-compatible
|
|
|
|
func (e *Engine) PrepareExecution(
|
|
|
|
// endpoint.
|
|
|
|
ctx context.Context,
|
|
|
|
func LocalBackend(endpoint string, concurrencyLimit int) Backend {
|
|
|
|
req RunRequest,
|
|
|
|
return Backend{
|
|
|
|
) (*PreparedExecution, error)
|
|
|
|
ID: BackendLocal,
|
|
|
|
|
|
|
|
Endpoint: endpoint,
|
|
|
|
func (p *PreparedExecution) Details() PreparedRun
|
|
|
|
ConcurrencyLimit: concurrencyLimit,
|
|
|
|
|
|
|
|
}
|
|
|
|
func (p *PreparedExecution) Discard()
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
func (e *Engine) RunPrepared(
|
|
|
|
|
|
|
|
ctx context.Context,
|
|
|
|
|
|
|
|
prepared *PreparedExecution,
|
|
|
|
|
|
|
|
) (*RunResult, error)
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Place the public handle and its handle-local methods in a new root file named
|
|
|
|
|
|
|
|
`prepared_execution.go`. Keep the two engine operations in `engine.go` beside
|
|
|
|
|
|
|
|
`Prepare` and `Run` so all engine workflows remain discoverable together.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`PreparedExecution` must contain no exported fields. It wraps one pointer to
|
|
|
|
|
|
|
|
Promptkit-owned internal state; copying the public struct therefore preserves
|
|
|
|
|
|
|
|
one shared lifecycle rather than creating another execution opportunity.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Implement both:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
|
|
|
func (p *PreparedExecution) String() string
|
|
|
|
|
|
|
|
func (p *PreparedExecution) GoString() string
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
with a constant credential- and content-free representation such as
|
|
|
|
|
|
|
|
`promptkit.PreparedExecution{opaque}`. These methods must not branch on,
|
|
|
|
|
|
|
|
inspect, or format retained execution state. Do not add a custom JSON
|
|
|
|
|
|
|
|
representation: with no exported fields, ordinary JSON encoding exposes no
|
|
|
|
|
|
|
|
state, and JSON is explicitly outside the handle contract.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The exact GoDoc must own these behaviors:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- `PrepareExecution` performs complete preparation but no model call and no
|
|
|
|
|
|
|
|
backend-capacity admission;
|
|
|
|
|
|
|
|
- the handle is bound to the creating engine and permits one
|
|
|
|
|
|
|
|
`RunPrepared` invocation;
|
|
|
|
|
|
|
|
- `Details` returns a fresh caller-owned, credential-redacted copy on every
|
|
|
|
|
|
|
|
call and remains usable after discard or execution;
|
|
|
|
|
|
|
|
- `Discard` is nil-safe and idempotent, invalidates an unclaimed handle, and
|
|
|
|
|
|
|
|
is not an execution-cancellation mechanism;
|
|
|
|
|
|
|
|
- `RunPrepared` atomically consumes the one attempt before credential
|
|
|
|
|
|
|
|
revalidation, admission, generation, or validation;
|
|
|
|
|
|
|
|
- lifecycle misuse matches `ErrInvalidRequest`, while a nil engine matches
|
|
|
|
|
|
|
|
`ErrInvalidConfig`;
|
|
|
|
|
|
|
|
- an operational execution error returns no partial `RunResult`;
|
|
|
|
|
|
|
|
- the `RunPrepared` context does not inherit from the preparation context and
|
|
|
|
|
|
|
|
governs the execution attempt; and
|
|
|
|
|
|
|
|
- handles are opaque in-process values, not serializable or restartable jobs.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
For a nil or zero-value handle, `Details` returns a zero `PreparedRun` and
|
|
|
|
|
|
|
|
`Discard` does nothing. A nil, zero-value, foreign-engine, discarded,
|
|
|
|
|
|
|
|
claimed, or used handle passed to `RunPrepared` returns an error matching
|
|
|
|
|
|
|
|
`ErrInvalidRequest`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Internal Validation Snapshot
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Extend `internal/validate/validator.go` with two internal interfaces:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
|
|
|
// PreparedValidation validates artifacts against one frozen output contract.
|
|
|
|
|
|
|
|
type PreparedValidation interface {
|
|
|
|
|
|
|
|
Validate(
|
|
|
|
|
|
|
|
ctx context.Context,
|
|
|
|
|
|
|
|
artifact *domain.Artifact,
|
|
|
|
|
|
|
|
) (domain.ValidationResult, error)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
// SchemaDocument returns the root JSON Schema document used for provider
|
|
|
|
|
|
|
|
// structured output, or nil for non-schema modes. The returned value is
|
|
|
|
|
|
|
|
// internal immutable state and must not be mutated by callers.
|
|
|
|
|
|
|
|
SchemaDocument() any
|
|
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
// ValidationPreparer freezes the validation resources for one output
|
|
|
|
|
|
|
|
// contract.
|
|
|
|
|
|
|
|
type ValidationPreparer interface {
|
|
|
|
|
|
|
|
PrepareValidation(
|
|
|
|
|
|
|
|
ctx context.Context,
|
|
|
|
|
|
|
|
contract domain.OutputContract,
|
|
|
|
|
|
|
|
) (PreparedValidation, error)
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
The exact GoDoc may be wrapped or expanded for clarity, but it must own and
|
|
|
|
The exact names may be adjusted only to avoid an actual Go naming conflict;
|
|
|
|
communicate all of these contract points:
|
|
|
|
the separation of responsibilities and method shapes are fixed.
|
|
|
|
|
|
|
|
`validate.Validator` and its existing `Validate` method remain unchanged so
|
|
|
|
|
|
|
|
the existing `Run` behavior and internal test fakes do not acquire a new
|
|
|
|
|
|
|
|
mandatory method.
|
|
|
|
|
|
|
|
|
|
|
|
- `BackendLocal` is the case-sensitive conventional ID `"local"`;
|
|
|
|
`StandardValidator` and `FSValidator` implement `ValidationPreparer`. Their
|
|
|
|
- it is neither built in nor reserved;
|
|
|
|
prepared-validation implementation:
|
|
|
|
- calling `LocalBackend` does not register anything;
|
|
|
|
|
|
|
|
- the returned value must be supplied through `WithBackend`;
|
|
|
|
|
|
|
|
- `endpoint` and `concurrencyLimit` are copied into the corresponding fields
|
|
|
|
|
|
|
|
without normalization or validation;
|
|
|
|
|
|
|
|
- `APIKeyEnv`, `ExtraParams`, and `QueueCapacity` retain their zero values; and
|
|
|
|
|
|
|
|
- normal `NewEngine` backend validation and concurrency semantics apply after
|
|
|
|
|
|
|
|
registration.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Keep `BackendOpenRouter` unchanged. `BackendLocal` must not alias an internal
|
|
|
|
- captures a value copy of the complete `OutputContract`;
|
|
|
|
registry constant because the internal registry has no special local-backend
|
|
|
|
- handles none, basic, and JSON validation without any source access;
|
|
|
|
identity or behavior.
|
|
|
|
- for JSON Schema, loads the root document, validates its dialect, registers
|
|
|
|
|
|
|
|
it with a new compiler, compiles it during `PrepareValidation`, and retains
|
|
|
|
|
|
|
|
the compiled schema;
|
|
|
|
|
|
|
|
- allows the compiler to resolve every transitive reference during that
|
|
|
|
|
|
|
|
compilation using the existing contained filesystem or `fs.FS` loader;
|
|
|
|
|
|
|
|
- returns the same loaded root document through `SchemaDocument`, so the
|
|
|
|
|
|
|
|
provider-facing structured-output constraint and later validation derive
|
|
|
|
|
|
|
|
from one root snapshot; and
|
|
|
|
|
|
|
|
- validates generated instances only against retained in-memory state. Its
|
|
|
|
|
|
|
|
`Validate` method must not reopen a path, call `fs.ReadFile`, resolve a
|
|
|
|
|
|
|
|
symlink, or invoke a schema loader after preparation succeeds.
|
|
|
|
|
|
|
|
|
|
|
|
Place `BackendLocal` near `BackendOpenRouter`, and place `LocalBackend` after
|
|
|
|
Reuse the existing JSON parsing, validation-result construction, schema
|
|
|
|
the `Backend` declaration and before `WithBackend`. This keeps the conventional
|
|
|
|
dialect checks, contained-path rules, compiler configuration, and validation
|
|
|
|
IDs, configured value, convenience constructor, and registration option
|
|
|
|
error wording. A prepared JSON Schema compilation or reference-loading failure
|
|
|
|
discoverable in one file.
|
|
|
|
is a preparation-time validation error. Existing direct calls to
|
|
|
|
|
|
|
|
`Validator.Validate`, including the existing `Run` path, retain their current
|
|
|
|
|
|
|
|
lazy compilation and source-loading behavior.
|
|
|
|
|
|
|
|
|
|
|
|
### Constructor Semantics
|
|
|
|
Do not expose the JSON Schema library's compiled type outside
|
|
|
|
|
|
|
|
`internal/validate`. Do not place compiled schemas or validation interfaces in
|
|
|
|
|
|
|
|
`internal/domain`.
|
|
|
|
|
|
|
|
|
|
|
|
`LocalBackend` is a pure struct constructor. Its complete behavior is
|
|
|
|
### Internal Prepared-Execution State
|
|
|
|
equivalent to the keyed literal shown above.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
In particular, the constructor must not:
|
|
|
|
Add `internal/usecase/prepared_execution.go`. Define an internal
|
|
|
|
|
|
|
|
`PreparedExecution` owned by one `Runner`. It contains:
|
|
|
|
|
|
|
|
|
|
|
|
- trim or parse the endpoint;
|
|
|
|
- the immutable owner `*Runner`;
|
|
|
|
- reject blank endpoints or negative limits;
|
|
|
|
- a mutex;
|
|
|
|
- choose a default limit;
|
|
|
|
- a small private lifecycle state with at least ready, claimed, and discarded
|
|
|
|
- assign an API-key environment variable;
|
|
|
|
states;
|
|
|
|
- allocate an empty `ExtraParams` map;
|
|
|
|
- a credential-redacted prepared-details snapshot that survives every
|
|
|
|
- assign a queue-capacity pointer;
|
|
|
|
lifecycle transition; and
|
|
|
|
- read process environment;
|
|
|
|
- while ready, a pointer to a private payload containing the full
|
|
|
|
- mutate package-global or engine state; or
|
|
|
|
`domain.PreparedRun` and its `validate.PreparedValidation`.
|
|
|
|
- call `WithBackend` itself.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Deferred validation is intentional. It keeps one validation path for all
|
|
|
|
The payload is the only retained object containing `RunRequest.APIKey`.
|
|
|
|
`Backend` values: `WithBackend` copies the public value into engine options,
|
|
|
|
Construct the public-details snapshot as a deep copy of the prepared run and
|
|
|
|
and `NewEngine` constructs the validated immutable registry. A positive limit
|
|
|
|
clear its `EffectiveModelParams.APIKey`. Deep-copy every mutable nested value,
|
|
|
|
with a nil queue continues to select the existing default queue capacity of
|
|
|
|
including messages, maps, target extra parameters, and the structured-output
|
|
|
|
1024; zero continues to mean unlimited; a negative value continues to make
|
|
|
|
schema. Reuse the repository's JSON-compatible copy helpers rather than
|
|
|
|
`NewEngine` fail with `ErrInvalidConfig`.
|
|
|
|
maintaining an ad hoc reflection copier.
|
|
|
|
|
|
|
|
|
|
|
|
The returned `Backend` remains an ordinary caller-owned value. Consumers can
|
|
|
|
Add these internal operations:
|
|
|
|
modify it before passing it to `WithBackend`, although task-oriented
|
|
|
|
|
|
|
|
documentation should direct materially customized configurations to an
|
|
|
|
|
|
|
|
explicit keyed `Backend` literal.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Identity And Compatibility
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Do not add `"local"` to the internal built-in or reserved ID set. A consumer
|
|
|
|
|
|
|
|
must be able to register either:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
```go
|
|
|
|
promptkit.LocalBackend(endpoint, limit)
|
|
|
|
func (r *Runner) PrepareExecution(
|
|
|
|
|
|
|
|
ctx context.Context,
|
|
|
|
|
|
|
|
req domain.RunRequest,
|
|
|
|
|
|
|
|
) (*PreparedExecution, error)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
func (p *PreparedExecution) Details() *domain.PreparedRun
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
func (p *PreparedExecution) Discard()
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
func (r *Runner) RunPrepared(
|
|
|
|
|
|
|
|
ctx context.Context,
|
|
|
|
|
|
|
|
prepared *PreparedExecution,
|
|
|
|
|
|
|
|
) (*domain.RunResult, error)
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
or:
|
|
|
|
Internal exported names are acceptable here because the root facade must call
|
|
|
|
|
|
|
|
them, but they remain inaccessible to downstream consumers through Go's
|
|
|
|
|
|
|
|
`internal` rule.
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
`PrepareExecution` performs these operations in order:
|
|
|
|
promptkit.Backend{
|
|
|
|
|
|
|
|
ID: promptkit.BackendLocal,
|
|
|
|
|
|
|
|
Endpoint: endpoint,
|
|
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
through the existing `WithBackend` option. Both forms participate in ordinary
|
|
|
|
1. call the existing request-copy boundary in the root facade before entering
|
|
|
|
duplicate-ID detection. Existing consumers that already use the literal ID
|
|
|
|
the runner;
|
|
|
|
`"local"` remain source- and behavior-compatible.
|
|
|
|
2. run `resolvePreparation`, including the existing environment credential
|
|
|
|
|
|
|
|
availability check;
|
|
|
|
|
|
|
|
3. prepare a frozen validation plan through
|
|
|
|
|
|
|
|
`validate.ValidationPreparer`;
|
|
|
|
|
|
|
|
4. construct provider structured-output metadata from the plan's root schema
|
|
|
|
|
|
|
|
document for JSON Schema mode;
|
|
|
|
|
|
|
|
5. load and hash artifacts, render the session and messages, and assemble the
|
|
|
|
|
|
|
|
complete `domain.PreparedRun`; and
|
|
|
|
|
|
|
|
6. construct the ready internal handle with independent full and redacted
|
|
|
|
|
|
|
|
snapshots.
|
|
|
|
|
|
|
|
|
|
|
|
No existing `Backend`, `WithBackend`, profile, registry, execution-target, or
|
|
|
|
Extract the artifact-loading, rendering, hashing, timing, and
|
|
|
|
capacity semantics change. Do not modify `internal/backend`,
|
|
|
|
`domain.PreparedRun` assembly portion of `completePreparation` into a helper
|
|
|
|
`internal/capacity`, `internal/domain`, `engine.go`, `profiles.go`, or
|
|
|
|
that accepts an already-resolved `*domain.StructuredOutputSpec`.
|
|
|
|
`types.go` for this feature.
|
|
|
|
`completePreparation` must continue to call the existing
|
|
|
|
|
|
|
|
`resolveStructuredOutput` first and then use that helper. This preserves
|
|
|
|
|
|
|
|
existing `Prepare` and `Run` schema behavior. `PrepareExecution` uses the
|
|
|
|
|
|
|
|
frozen validation plan's schema document to build the same structured-output
|
|
|
|
|
|
|
|
shape without calling `resolveStructuredOutput`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
When the runner has no validator, preserve the existing runner semantics:
|
|
|
|
|
|
|
|
validation is skipped and a no-op prepared plan is sufficient. When it has a
|
|
|
|
|
|
|
|
non-nil validator that does not implement `ValidationPreparer`,
|
|
|
|
|
|
|
|
`PrepareExecution` fails with `ErrValidation`; do not fall back to a plan that
|
|
|
|
|
|
|
|
would reopen sources later. The root engine's standard and `fs.FS` validators
|
|
|
|
|
|
|
|
always implement the new interface.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Claim, Cleanup, And Engine Binding
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`RunPrepared` checks engine ownership before attempting a claim. A foreign
|
|
|
|
|
|
|
|
runner returns `ErrInvalidRequest` without changing the handle. The owning
|
|
|
|
|
|
|
|
runner then locks the state and atomically:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1. accepts only the ready state;
|
|
|
|
|
|
|
|
2. changes it permanently to claimed;
|
|
|
|
|
|
|
|
3. detaches the private payload from the handle; and
|
|
|
|
|
|
|
|
4. unlocks before doing any blocking or collaborator work.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Every valid owning-engine invocation consumes the attempt at this point. Run
|
|
|
|
|
|
|
|
ID creation, credential failure, pre-canceled context, capacity rejection,
|
|
|
|
|
|
|
|
generation failure, operational validation failure, and success all leave the
|
|
|
|
|
|
|
|
handle claimed and unusable.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The execution call holds the detached payload locally and defers cleanup on
|
|
|
|
|
|
|
|
every exit. Cleanup must at minimum:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- overwrite the direct `EffectiveModelParams.APIKey` field with an empty
|
|
|
|
|
|
|
|
string;
|
|
|
|
|
|
|
|
- drop the local prepared-run pointer;
|
|
|
|
|
|
|
|
- drop the frozen-validation reference; and
|
|
|
|
|
|
|
|
- leave the separate redacted details snapshot intact.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
This is reference cleanup, not a promise of secure Go string-memory erasure.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`Discard` locks the same state. If ready, it changes the state to discarded,
|
|
|
|
|
|
|
|
detaches the payload, unlocks, and performs the same cleanup. If claimed or
|
|
|
|
|
|
|
|
already discarded, it is a no-op. Therefore a `RunPrepared`/`Discard` race has
|
|
|
|
|
|
|
|
one winner: discard prevents a claim only if it acquires the ready state
|
|
|
|
|
|
|
|
first; otherwise it does not cancel the running attempt.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`Details` locks only long enough to read the retained redacted snapshot and
|
|
|
|
|
|
|
|
returns a fresh deep copy. It must not return a pointer, slice, map, schema, or
|
|
|
|
|
|
|
|
extra-parameter tree shared with either the handle or another `Details` call.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Prepared Execution Mechanics
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Refactor the post-preparation portion of `Runner.Run` into a private execution
|
|
|
|
|
|
|
|
helper that accepts:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- a fully prepared `domain.PreparedRun`;
|
|
|
|
|
|
|
|
- a caller-supplied run ID and execution start time; and
|
|
|
|
|
|
|
|
- a validation function that accepts the artifact and repair-attempt count.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The helper owns model generation, artifact construction, content validation,
|
|
|
|
|
|
|
|
internal repair, final result assembly, and result end timing. The live
|
|
|
|
|
|
|
|
`Runner.Run` path supplies its existing `validateOutput` function. The
|
|
|
|
|
|
|
|
prepared path supplies a wrapper around the retained
|
|
|
|
|
|
|
|
`validate.PreparedValidation`. Both wrappers set the actual repair-attempt
|
|
|
|
|
|
|
|
count on the returned validation result.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Keep admission outside this shared helper:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- `Runner.Run` retains its current sequence of run-ID creation, start time,
|
|
|
|
|
|
|
|
target resolution, early admission, complete preparation, execution, and
|
|
|
|
|
|
|
|
release.
|
|
|
|
|
|
|
|
- `Runner.RunPrepared` claims the handle, creates the run ID and execution
|
|
|
|
|
|
|
|
start time, revalidates credential availability, admits the frozen backend,
|
|
|
|
|
|
|
|
executes the shared helper, and releases admission.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Extract a small private admission helper only if it preserves the exact
|
|
|
|
|
|
|
|
existing capacity wrapping and release behavior. The limited-backend lease
|
|
|
|
|
|
|
|
must cover generation, validation, and all internal repair calls and must be
|
|
|
|
|
|
|
|
released on every return.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Before admission, `RunPrepared` calls the existing `validateAPIKey` with the
|
|
|
|
|
|
|
|
frozen environment-variable name, retained direct key, and frozen requirement
|
|
|
|
|
|
|
|
flag. A missing environment credential returns an error wrapping
|
|
|
|
|
|
|
|
`ErrInvalidRequest` and `ErrAPIKeyEnvMissing`. Do not read and retain the
|
|
|
|
|
|
|
|
environment value; the model client continues to resolve it when generation
|
|
|
|
|
|
|
|
begins.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The result produced by the shared helper uses the frozen preparation values
|
|
|
|
|
|
|
|
for all provenance. For `RunPrepared`, `StartTime`, `EndTime`, and `Duration`
|
|
|
|
|
|
|
|
begin after the successful claim and exclude preparation and consumer-held
|
|
|
|
|
|
|
|
delay. For ordinary `Run`, retain the current timing boundary beginning before
|
|
|
|
|
|
|
|
preparation.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Error Mapping And Compatibility
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Do not add a new public sentinel. Internal lifecycle errors wrap
|
|
|
|
|
|
|
|
`usecase.ErrInvalidRequest`, which the existing root mapping exposes as
|
|
|
|
|
|
|
|
`promptkit.ErrInvalidRequest`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`PrepareExecution` uses the same public categories as `Prepare`.
|
|
|
|
|
|
|
|
`RunPrepared` may return:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- `ErrInvalidConfig` for a nil engine;
|
|
|
|
|
|
|
|
- `ErrInvalidRequest` for handle misuse and invalid credentials;
|
|
|
|
|
|
|
|
- `ErrAPIKeyEnvMissing` together with `ErrInvalidRequest` when the frozen
|
|
|
|
|
|
|
|
environment name is no longer set and no direct key is retained;
|
|
|
|
|
|
|
|
- `ErrCapacityExceeded` for admission rejection;
|
|
|
|
|
|
|
|
- `ErrLLMGenerate` for model-generation failures; and
|
|
|
|
|
|
|
|
- `ErrValidation` for inability to validate or repair.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Preserve wrapped collaborator and context errors according to the existing
|
|
|
|
|
|
|
|
mapping rules. A content validation rejection remains a successful
|
|
|
|
|
|
|
|
`RunResult` with `ValidationFailed`, not an operational error.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Do not change stable JSON for `PreparedRun` or `RunResult`, public request and
|
|
|
|
|
|
|
|
result ownership, provider request bodies or headers, backend selection,
|
|
|
|
|
|
|
|
capacity policies, `LLMClient`, `ArtifactReader`, `Prepare`, or `Run`.
|
|
|
|
|
|
|
|
|
|
|
|
### Test Ownership
|
|
|
|
### Test Ownership
|
|
|
|
|
|
|
|
|
|
|
|
The root external-package contract suite in `public_contract_test.go` owns the
|
|
|
|
Tests must be split by the narrowest stable owner.
|
|
|
|
new public behavior. Add one focused test named:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
`internal/validate/standard_validator_test.go` owns frozen schema mechanics.
|
|
|
|
func TestLocalBackendConstructsAndRegistersConventionalBackend(t *testing.T)
|
|
|
|
Add focused tests for both configured schema-source forms:
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The test must:
|
|
|
|
- a directory-backed `StandardValidator` test whose root schema references a
|
|
|
|
|
|
|
|
second file; after `PrepareValidation`, replace or remove both files and
|
|
|
|
|
|
|
|
prove that valid and invalid artifacts are judged by the original compiled
|
|
|
|
|
|
|
|
schema; and
|
|
|
|
|
|
|
|
- an `FSValidator` test using a mutable in-memory `fs.FS`; mutate its root and
|
|
|
|
|
|
|
|
referenced entries after `PrepareValidation` and prove the same invariant.
|
|
|
|
|
|
|
|
|
|
|
|
1. call `promptkit.LocalBackend` with a test endpoint and a positive,
|
|
|
|
Each test must also confirm that `SchemaDocument` is the original root
|
|
|
|
test-owned concurrency limit;
|
|
|
|
document used at preparation. Existing path-containment and dialect matrices
|
|
|
|
2. compare the returned value with this complete expected value:
|
|
|
|
remain the owners of those rules and must not be duplicated.
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
`internal/usecase` tests own orchestration details that cannot be observed
|
|
|
|
promptkit.Backend{
|
|
|
|
cleanly at the facade:
|
|
|
|
ID: promptkit.BackendLocal,
|
|
|
|
|
|
|
|
Endpoint: endpoint,
|
|
|
|
|
|
|
|
ConcurrencyLimit: limit,
|
|
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
A whole-value comparison is appropriate here because the exact zero-value
|
|
|
|
- `PrepareExecution` completes source loading, artifact reading, rendering,
|
|
|
|
fields are part of this small public constructor's contract.
|
|
|
|
and validation-plan creation without calling admission or generation;
|
|
|
|
3. register that returned value with `WithBackend`;
|
|
|
|
- `RunPrepared` rechecks environment credential availability before admission;
|
|
|
|
4. add an in-memory profile whose `BackendID` is
|
|
|
|
- the prepared path supplies the frozen validation plan to initial validation
|
|
|
|
`promptkit.BackendLocal`;
|
|
|
|
and every repair attempt;
|
|
|
|
5. construct an engine through the existing contract-test prompt fixture;
|
|
|
|
- admission is released on success and each error exit; and
|
|
|
|
6. call `Prepare`; and
|
|
|
|
- the ordinary `Run` admission-before-complete-preparation ordering remains
|
|
|
|
7. assert that the prepared result exposes `BackendLocal` as the selected
|
|
|
|
unchanged after refactoring.
|
|
|
|
backend and the supplied endpoint as the effective endpoint.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
This single test protects the realistic compatibility risks: accidental field
|
|
|
|
Use small test-controlled collaborators. Do not assert private enum values,
|
|
|
|
defaults, a changed conventional ID, failure to compose with `WithBackend`,
|
|
|
|
mutex layout, helper call graphs, or cleanup implementation details.
|
|
|
|
and accidental treatment of `"local"` as reserved. It also demonstrates that
|
|
|
|
|
|
|
|
the helper uses the existing backend/profile path.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Do not add separate tests for blank endpoints, malformed endpoints, negative
|
|
|
|
Add `prepared_execution_contract_test.go` in external package
|
|
|
|
limits, queue defaulting, duplicate IDs, engine isolation, runtime capacity,
|
|
|
|
`promptkit_test` for the public contract. Cover these distinct risks with the
|
|
|
|
or caller mutation. Those mechanisms are unchanged and already have tests at
|
|
|
|
smallest coherent set of tests:
|
|
|
|
their owning boundaries. Do not add internal-package tests for this root
|
|
|
|
|
|
|
|
facade constructor.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Consumer Documentation
|
|
|
|
1. **Frozen execution and independent details.** Prepare a request, mutate
|
|
|
|
|
|
|
|
caller-owned request values, mutable prompt/profile/input/schema sources,
|
|
|
|
|
|
|
|
and one returned `PreparedRun`, then run the handle. Assert that the
|
|
|
|
|
|
|
|
captured `GenerateRequest`, validation, result provenance, and a second
|
|
|
|
|
|
|
|
`Details` call all retain the original prepared state. Assert that source
|
|
|
|
|
|
|
|
collaborators are not reopened during execution.
|
|
|
|
|
|
|
|
2. **Lifecycle and engine binding.** Prove that a foreign engine is rejected
|
|
|
|
|
|
|
|
without consuming the handle, the owner can then run it once, a second
|
|
|
|
|
|
|
|
call through either the original or a copied public handle is rejected, and
|
|
|
|
|
|
|
|
details remain available.
|
|
|
|
|
|
|
|
3. **Concurrent claim.** Race two owning-engine `RunPrepared` calls against a
|
|
|
|
|
|
|
|
blocking fake client. Exactly one reaches generation and the other matches
|
|
|
|
|
|
|
|
`ErrInvalidRequest`. Run this test under the race detector.
|
|
|
|
|
|
|
|
4. **Discard and formatting security.** Retain a distinctive direct API key,
|
|
|
|
|
|
|
|
verify that `Details`, ordinary JSON encoding, `%v`, `%+v`, `%#v`, and
|
|
|
|
|
|
|
|
lifecycle errors do not contain it or rendered content, discard the handle,
|
|
|
|
|
|
|
|
and verify idempotence, execution rejection, and retained details.
|
|
|
|
|
|
|
|
5. **Credential and capacity timing.** Prove that preparation does not occupy
|
|
|
|
|
|
|
|
admission; removing a required environment credential makes execution fail
|
|
|
|
|
|
|
|
before generation; a capacity rejection consumes the handle; and the
|
|
|
|
|
|
|
|
execution result's timing excludes a test-controlled delay between
|
|
|
|
|
|
|
|
preparation and execution.
|
|
|
|
|
|
|
|
|
|
|
|
Update `docs/consumers/pkg-promptkit.md` after the API exists. Keep Go
|
|
|
|
Reuse existing root contract fixtures and capacity fakes where practical.
|
|
|
|
declarations and GoDoc as the exact API owner; the guide should help consumers
|
|
|
|
Never put a real-looking credential in a fixture. Do not test JSON equality
|
|
|
|
choose a workflow and link to `backends.go` for precise semantics.
|
|
|
|
for the opaque handle, exact lifecycle error strings, private state, run-ID
|
|
|
|
|
|
|
|
format, or clock-duration precision.
|
|
|
|
|
|
|
|
|
|
|
|
Restructure the backend guidance to present these paths in increasing order of
|
|
|
|
### Documentation Ownership
|
|
|
|
configuration:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1. **Endpoint-only profile.** Show a small in-memory `Profile` with
|
|
|
|
After implementation:
|
|
|
|
`Endpoint` and `Model`. Explain that this is the simplest choice when only
|
|
|
|
|
|
|
|
one profile needs the endpoint and shared backend identity or capacity
|
|
|
|
|
|
|
|
policy is unnecessary.
|
|
|
|
|
|
|
|
2. **Local convenience constructor.** Show
|
|
|
|
|
|
|
|
`WithBackend(promptkit.LocalBackend("http://localhost:8000/v1", 2))`
|
|
|
|
|
|
|
|
together with a profile using
|
|
|
|
|
|
|
|
`BackendID: promptkit.BackendLocal`. Explain briefly that the helper is
|
|
|
|
|
|
|
|
explicit, is not pre-registered, does not read environment variables, and
|
|
|
|
|
|
|
|
leaves the queue capacity at the existing default for a positive limit.
|
|
|
|
|
|
|
|
3. **Complete backend value.** Preserve an advanced example using a keyed
|
|
|
|
|
|
|
|
`Backend` literal for needs such as `APIKeyEnv`, an explicit
|
|
|
|
|
|
|
|
`QueueCapacity`, extra parameters, a custom ID, or multiple local
|
|
|
|
|
|
|
|
endpoints. Use a custom ID other than `"local"` in that example so the
|
|
|
|
|
|
|
|
distinction from the conventional helper is clear.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Keep the existing backend-routing, selected-backend identity, concurrency,
|
|
|
|
- exported declarations and GoDoc in `prepared_execution.go`, `engine.go`, and
|
|
|
|
credential, and error guidance unless a small wording adjustment is required
|
|
|
|
`types.go` own the exact public lifecycle, ownership, security, timing,
|
|
|
|
to make the new decision path coherent. Avoid repeating the complete field
|
|
|
|
cancellation, and error contracts;
|
|
|
|
contract or registry validation rules from GoDoc.
|
|
|
|
- `docs/consumers/pkg-promptkit.md` explains when to choose `Prepare`, `Run`,
|
|
|
|
|
|
|
|
or `PrepareExecution` plus `RunPrepared`, and shows one concise two-phase
|
|
|
|
|
|
|
|
workflow using `defer prepared.Discard()`;
|
|
|
|
|
|
|
|
- `docs/internal/sources.md` explains that prepared execution freezes all
|
|
|
|
|
|
|
|
source-derived state, including transitive schema references, while
|
|
|
|
|
|
|
|
ordinary `Prepare` remains inspection-only;
|
|
|
|
|
|
|
|
- `docs/internal/llm.md` explains that prepared generation uses the retained
|
|
|
|
|
|
|
|
target and messages, rechecks environment credential availability, and
|
|
|
|
|
|
|
|
does not reopen sources;
|
|
|
|
|
|
|
|
- `docs/internal/capacity.md` explains that `PrepareExecution` performs no
|
|
|
|
|
|
|
|
admission and that `RunPrepared` acquires and holds the normal run lease
|
|
|
|
|
|
|
|
across generation, validation, and internal repair; and
|
|
|
|
|
|
|
|
- `docs/internal/overview.md` updates the validator and use-case inventory to
|
|
|
|
|
|
|
|
mention frozen validation plans and one-attempt prepared execution.
|
|
|
|
|
|
|
|
|
|
|
|
Do not add a new maintained example, README section, format-reference entry,
|
|
|
|
Keep these documents at their established abstraction levels. Link to exact
|
|
|
|
integration-contract change, internal-document change, or release note. The
|
|
|
|
Go declarations rather than reproducing field-by-field contracts. No README,
|
|
|
|
consumer-guide snippets are sufficient for this small convenience API, and
|
|
|
|
format reference, integration contract, maintained example, architecture
|
|
|
|
none of those other documents owns the affected task or contract.
|
|
|
|
policy, release note, or release-procedure update is required because the
|
|
|
|
|
|
|
|
feature changes none of their owned concerns.
|
|
|
|
|
|
|
|
|
|
|
|
## Stage 1: Add The Public Constructor And Contract Test
|
|
|
|
## Stage 1: Add Frozen Validation Plans
|
|
|
|
|
|
|
|
|
|
|
|
**Status:** Complete.
|
|
|
|
**Status:** Pending.
|
|
|
|
|
|
|
|
|
|
|
|
### Objective
|
|
|
|
### Objective
|
|
|
|
|
|
|
|
|
|
|
|
Add the smallest public API that expresses the accepted local-backend
|
|
|
|
Create an internal validation artifact that eagerly captures every schema
|
|
|
|
convention and protect its compatibility through the root public boundary.
|
|
|
|
resource required by later validation, without changing existing validation
|
|
|
|
|
|
|
|
or engine behavior.
|
|
|
|
|
|
|
|
|
|
|
|
### Implementation Prompt
|
|
|
|
### Implementation Prompt
|
|
|
|
|
|
|
|
|
|
|
|
1. Re-read `docs/development.md`, all files under `docs/policy/`,
|
|
|
|
1. Re-read `docs/development.md`, all files under `docs/policy/`,
|
|
|
|
`local-backend.md`, `backends.go`, the backend-related portion of
|
|
|
|
`prepared-execution.md`, `internal/validate/validator.go`,
|
|
|
|
`public_contract_test.go`, and the existing backend/concurrency GoDoc before
|
|
|
|
`internal/validate/standard_validator.go`, and the focused validator tests.
|
|
|
|
editing.
|
|
|
|
2. Confirm the working tree and preserve all existing roadmap and wishlist
|
|
|
|
2. Confirm the working tree and preserve the uncommitted roadmaps and any
|
|
|
|
changes.
|
|
|
|
unrelated consumer changes.
|
|
|
|
3. Add `PreparedValidation` and `ValidationPreparer` to
|
|
|
|
3. Add the untyped exported string constant `BackendLocal = "local"` to
|
|
|
|
`internal/validate/validator.go` with the exact responsibilities in the
|
|
|
|
`backends.go` without changing `BackendOpenRouter`.
|
|
|
|
fixed design. Leave `Validator` unchanged.
|
|
|
|
4. Add `LocalBackend(endpoint string, concurrencyLimit int) Backend` to
|
|
|
|
4. Implement `PrepareValidation` for `StandardValidator` and `FSValidator`.
|
|
|
|
`backends.go` using the exact keyed-literal implementation in the fixed
|
|
|
|
Reuse the existing root resolution, resource identifiers, contained
|
|
|
|
design.
|
|
|
|
loaders, dialect checks, compiler configuration, JSON parser, and
|
|
|
|
5. Write complete GoDoc for both declarations. Make their conventional,
|
|
|
|
validation-result builder.
|
|
|
|
explicit, non-built-in, non-reserved, and deferred-validation semantics
|
|
|
|
5. Ensure the root document is registered from the already-loaded value and
|
|
|
|
unambiguous.
|
|
|
|
every transitive reference is loaded during compilation. Retain only the
|
|
|
|
6. Add
|
|
|
|
compiled schema, root document, and copied contract required for later
|
|
|
|
`TestLocalBackendConstructsAndRegistersConventionalBackend` to
|
|
|
|
validation.
|
|
|
|
`public_contract_test.go` exactly as specified under Test Ownership. Reuse
|
|
|
|
6. Ensure the prepared validator checks its validation-time context and does
|
|
|
|
the existing contract prompt fixture rather than adding a fixture or test
|
|
|
|
not touch either source after successful preparation.
|
|
|
|
helper.
|
|
|
|
7. Add the two focused frozen-reference tests described under Test Ownership.
|
|
|
|
7. Do not edit internal packages. If the constructor appears to require an
|
|
|
|
Keep existing tests unchanged except for shared test setup that materially
|
|
|
|
internal change, stop and reconcile the implementation with the fixed
|
|
|
|
reduces duplication.
|
|
|
|
transparent-constructor design instead.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Focused Validation
|
|
|
|
### Focused Validation
|
|
|
|
|
|
|
|
|
|
|
|
Run:
|
|
|
|
Run:
|
|
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
```sh
|
|
|
|
gofmt -w backends.go public_contract_test.go
|
|
|
|
gofmt -w internal/validate/validator.go \
|
|
|
|
go test . -run '^TestLocalBackendConstructsAndRegistersConventionalBackend$'
|
|
|
|
internal/validate/standard_validator.go \
|
|
|
|
|
|
|
|
internal/validate/standard_validator_test.go
|
|
|
|
|
|
|
|
go test ./internal/validate
|
|
|
|
|
|
|
|
go test -race ./internal/validate
|
|
|
|
|
|
|
|
go vet ./internal/validate
|
|
|
|
|
|
|
|
git diff --check
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Completion Gate
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Stage 1 is complete when:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- both built-in validator forms produce prepared plans;
|
|
|
|
|
|
|
|
- prepared schema validation works after root and referenced sources change or
|
|
|
|
|
|
|
|
disappear;
|
|
|
|
|
|
|
|
- provider schema metadata can use the exact root document captured by the
|
|
|
|
|
|
|
|
plan;
|
|
|
|
|
|
|
|
- existing `Validator.Validate` behavior remains unchanged; and
|
|
|
|
|
|
|
|
- focused tests, race tests, vet, formatting, and whitespace checks pass.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Stage 2: Implement Internal Handle Lifecycle And Prepared Execution
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**Status:** Pending.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Objective
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Add complete preparation, one-attempt lifecycle management, cleanup, and
|
|
|
|
|
|
|
|
source-free execution to the use-case layer while preserving existing
|
|
|
|
|
|
|
|
`Prepare` and `Run` behavior.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Implementation Prompt
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1. Re-read the completed Stage 1 declarations, `internal/usecase/runner.go`,
|
|
|
|
|
|
|
|
its focused tests, `internal/capacity`, and the execution flow described in
|
|
|
|
|
|
|
|
`prepared-execution.md`.
|
|
|
|
|
|
|
|
2. Add `internal/usecase/prepared_execution.go` with the internal handle,
|
|
|
|
|
|
|
|
payload, lifecycle transitions, deep-copying, redaction, cleanup, and
|
|
|
|
|
|
|
|
runner ownership described in the fixed design.
|
|
|
|
|
|
|
|
3. Extract the common final preparation helper that accepts resolved
|
|
|
|
|
|
|
|
structured-output metadata. Keep `completePreparation` and existing
|
|
|
|
|
|
|
|
`resolveStructuredOutput` behavior intact for `Prepare` and `Run`.
|
|
|
|
|
|
|
|
4. Implement `Runner.PrepareExecution` using
|
|
|
|
|
|
|
|
`validate.ValidationPreparer`. Build JSON Schema structured-output metadata
|
|
|
|
|
|
|
|
from the frozen plan's root document.
|
|
|
|
|
|
|
|
5. Refactor post-preparation generation, validation, repair, and result
|
|
|
|
|
|
|
|
assembly into the shared private helper. Preserve ordinary `Run` timing,
|
|
|
|
|
|
|
|
early admission, error ordering, and live validator behavior.
|
|
|
|
|
|
|
|
6. Implement `Runner.RunPrepared`: verify owner, claim once, create run ID and
|
|
|
|
|
|
|
|
execution start time, recheck credentials, acquire admission, execute
|
|
|
|
|
|
|
|
against the retained plan, release admission, and clean the detached
|
|
|
|
|
|
|
|
payload on every exit.
|
|
|
|
|
|
|
|
7. Implement nil-safe, idempotent discard and fresh redacted details copying.
|
|
|
|
|
|
|
|
Confirm the `RunPrepared`/`Discard` race is resolved solely by the shared
|
|
|
|
|
|
|
|
mutex transition.
|
|
|
|
|
|
|
|
8. Add the internal orchestration tests described under Test Ownership,
|
|
|
|
|
|
|
|
including regression coverage for ordinary `Run`'s admission ordering.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Focused Validation
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Run:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
|
|
|
gofmt -w internal/usecase/runner.go \
|
|
|
|
|
|
|
|
internal/usecase/prepared_execution.go \
|
|
|
|
|
|
|
|
internal/usecase/*_test.go
|
|
|
|
|
|
|
|
go test ./internal/usecase
|
|
|
|
|
|
|
|
go test -race ./internal/usecase
|
|
|
|
|
|
|
|
go test ./internal/validate
|
|
|
|
|
|
|
|
go vet ./internal/usecase ./internal/validate
|
|
|
|
|
|
|
|
git diff --check
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Completion Gate
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Stage 2 is complete when:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- a runner can prepare and later execute without reopening any request source;
|
|
|
|
|
|
|
|
- one valid invocation consumes the handle on every outcome;
|
|
|
|
|
|
|
|
- foreign-runner rejection does not consume the handle;
|
|
|
|
|
|
|
|
- discard and claim are race-safe and cleanup drops secret-bearing state;
|
|
|
|
|
|
|
|
- prepared execution rechecks credentials and admits only at execution time;
|
|
|
|
|
|
|
|
- frozen validation is reused across initial output and repair attempts;
|
|
|
|
|
|
|
|
- existing `Prepare` and `Run` tests retain their observable ordering and
|
|
|
|
|
|
|
|
behavior; and
|
|
|
|
|
|
|
|
- focused tests, race tests, vet, formatting, and whitespace checks pass.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Stage 3: Publish The Root Facade And Public Contract
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**Status:** Pending.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Objective
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Expose the accepted opaque handle workflow through the root package and
|
|
|
|
|
|
|
|
protect its compatibility, security, and concurrency guarantees at the
|
|
|
|
|
|
|
|
consumer boundary.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Implementation Prompt
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1. Re-read the accepted public workflow, root conversion and error-mapping
|
|
|
|
|
|
|
|
helpers, existing `Prepare` and `Run` GoDoc, and the external-package
|
|
|
|
|
|
|
|
contract-test conventions.
|
|
|
|
|
|
|
|
2. Add root `prepared_execution.go` with the opaque wrapper, `Details`,
|
|
|
|
|
|
|
|
`Discard`, `String`, and `GoString`.
|
|
|
|
|
|
|
|
3. Add `Engine.PrepareExecution` and `Engine.RunPrepared` to `engine.go`.
|
|
|
|
|
|
|
|
Reuse `toDomainRunRequest`, `fromDomainPreparedRun`,
|
|
|
|
|
|
|
|
`fromDomainRunResult`, and `mapPublicError`.
|
|
|
|
|
|
|
|
4. Add or reuse one public prepared-run deep-copy helper so every `Details`
|
|
|
|
|
|
|
|
call returns fresh nested state. Do not expose the internal handle or
|
|
|
|
|
|
|
|
retain a public direct credential.
|
|
|
|
|
|
|
|
5. Write complete GoDoc for the type and methods. Update `RunRequest`,
|
|
|
|
|
|
|
|
`PreparedRun`, and `RunResult` GoDoc only where cross-references are needed
|
|
|
|
|
|
|
|
to distinguish the new workflow; do not change their stable JSON or
|
|
|
|
|
|
|
|
ownership contracts.
|
|
|
|
|
|
|
|
6. Add `prepared_execution_contract_test.go` and cover the five risk groups
|
|
|
|
|
|
|
|
under Test Ownership. Reuse existing fixtures and fakes rather than
|
|
|
|
|
|
|
|
duplicating backend, profile, schema, and capacity matrices.
|
|
|
|
|
|
|
|
7. Explicitly inspect formatted and JSON-encoded handles, lifecycle errors,
|
|
|
|
|
|
|
|
details, captured model requests, and results for the test sentinel direct
|
|
|
|
|
|
|
|
key.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Focused Validation
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Run:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
|
|
|
gofmt -w prepared_execution.go engine.go types.go convert.go \
|
|
|
|
|
|
|
|
prepared_execution_contract_test.go
|
|
|
|
|
|
|
|
go test . -run 'PreparedExecution|RunPrepared|PrepareExecution'
|
|
|
|
|
|
|
|
go test -race . -run 'PreparedExecution|RunPrepared|PrepareExecution'
|
|
|
|
go test .
|
|
|
|
go test .
|
|
|
|
go vet .
|
|
|
|
go vet .
|
|
|
|
go build .
|
|
|
|
go build .
|
|
|
|
git diff --check
|
|
|
|
git diff --check
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Inspect the diff and confirm that this stage changes only `backends.go`,
|
|
|
|
|
|
|
|
`public_contract_test.go`, and the already-present roadmap files.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Completion Gate
|
|
|
|
### Completion Gate
|
|
|
|
|
|
|
|
|
|
|
|
Stage 1 is complete when:
|
|
|
|
Stage 3 is complete when:
|
|
|
|
|
|
|
|
|
|
|
|
- the exported constant and constructor match the fixed API;
|
|
|
|
- the public API matches the accepted shape;
|
|
|
|
- the constructor returns only the three specified non-zero fields;
|
|
|
|
- details are fresh, stable, credential-redacted copies before and after every
|
|
|
|
- the helper registers through the ordinary `WithBackend` path;
|
|
|
|
lifecycle outcome;
|
|
|
|
- `"local"` remains a valid consumer registration rather than a reserved
|
|
|
|
- default formatting and JSON expose no retained request or credential data;
|
|
|
|
built-in;
|
|
|
|
- foreign, copied, concurrent, discarded, and reused handles obey the
|
|
|
|
- the focused public-contract test passes; and
|
|
|
|
one-attempt contract;
|
|
|
|
- the root package test, vet, build, formatting, and whitespace checks pass.
|
|
|
|
- execution uses exactly the frozen request and validation state;
|
|
|
|
|
|
|
|
- preparation performs no generation or admission;
|
|
|
|
|
|
|
|
- result provenance matches details and execution timing excludes preparation
|
|
|
|
|
|
|
|
and retention delay;
|
|
|
|
|
|
|
|
- public errors preserve the required `errors.Is` identities; and
|
|
|
|
|
|
|
|
- focused public, race, package, vet, build, formatting, and whitespace checks
|
|
|
|
|
|
|
|
pass.
|
|
|
|
|
|
|
|
|
|
|
|
## Stage 2: Publish Consumer Guidance And Validate The Repository
|
|
|
|
## Stage 4: Update Documentation And Validate The Repository
|
|
|
|
|
|
|
|
|
|
|
|
**Status:** Complete.
|
|
|
|
**Status:** Pending.
|
|
|
|
|
|
|
|
|
|
|
|
### Objective
|
|
|
|
### Objective
|
|
|
|
|
|
|
|
|
|
|
|
Make the simplest suitable local-endpoint configuration easy to discover,
|
|
|
|
Publish current-state guidance at the correct documentation owners, validate
|
|
|
|
confirm the complete change across the repository, and close the temporary
|
|
|
|
the complete repository, and mark the temporary roadmaps complete.
|
|
|
|
roadmaps.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Implementation Prompt
|
|
|
|
### Implementation Prompt
|
|
|
|
|
|
|
|
|
|
|
|
1. Re-read the implemented declarations and GoDoc before describing them.
|
|
|
|
1. Re-read the implemented declarations and tests before documenting them.
|
|
|
|
2. Update `docs/consumers/pkg-promptkit.md` according to the three-path
|
|
|
|
2. Update `docs/consumers/pkg-promptkit.md`,
|
|
|
|
structure under Consumer Documentation.
|
|
|
|
`docs/internal/sources.md`, `docs/internal/llm.md`,
|
|
|
|
3. Keep examples illustrative, minimal, secret-free, and consistent with the
|
|
|
|
`docs/internal/capacity.md`, and `docs/internal/overview.md` according to
|
|
|
|
implemented declarations. Link precise semantics to `backends.go` rather
|
|
|
|
Documentation Ownership.
|
|
|
|
than duplicating its field-by-field contract.
|
|
|
|
3. Keep the consumer example concise, copyable, secret-free, and explicit
|
|
|
|
|
|
|
|
about `defer prepared.Discard()`. Link to declarations for exact lifecycle
|
|
|
|
|
|
|
|
and error semantics.
|
|
|
|
4. Follow every added or changed Markdown link and confirm its target exists.
|
|
|
|
4. Follow every added or changed Markdown link and confirm its target exists.
|
|
|
|
Confirm that all local repository-relative links in
|
|
|
|
Confirm that repository-relative links in both roadmap documents and all
|
|
|
|
`local-backend.md`, this plan, and the changed consumer guide resolve.
|
|
|
|
changed current-state documents resolve.
|
|
|
|
5. Run the complete maintainer validation sequence below.
|
|
|
|
5. Run the complete maintainer validation sequence below.
|
|
|
|
6. Inspect the final diff for accidental internal behavior changes,
|
|
|
|
6. Inspect the final diff for accidental provider-wire changes, source
|
|
|
|
generated artifacts, credentials, local workspace files, or module
|
|
|
|
reloading during prepared execution, stable-JSON changes, credentials,
|
|
|
|
replacements.
|
|
|
|
generated artifacts, local workspace files, module replacements, or
|
|
|
|
7. After every completion gate passes, set both stage statuses, this plan's
|
|
|
|
unrelated edits.
|
|
|
|
status, and the status in `local-backend.md` to `Complete`. Do not retire or
|
|
|
|
7. After every completion gate passes, set every stage status, this plan's
|
|
|
|
remove the roadmaps in the implementation change; roadmap retirement
|
|
|
|
status, and the status in `prepared-execution.md` to `Complete`. Do not
|
|
|
|
follows implementation review.
|
|
|
|
retire or remove the roadmaps in the implementation change; roadmap
|
|
|
|
|
|
|
|
retirement follows implementation review.
|
|
|
|
|
|
|
|
|
|
|
|
### Full Validation
|
|
|
|
### Full Validation
|
|
|
|
|
|
|
|
|
|
|
|
@@ -318,69 +686,37 @@ Run the complete sequence from `docs/development.md`:
|
|
|
|
```sh
|
|
|
|
```sh
|
|
|
|
go test ./...
|
|
|
|
go test ./...
|
|
|
|
go test -race ./...
|
|
|
|
go test -race ./...
|
|
|
|
|
|
|
|
go run ./examples/go-library/prepare
|
|
|
|
go vet ./...
|
|
|
|
go vet ./...
|
|
|
|
go build ./...
|
|
|
|
go build ./...
|
|
|
|
go run ./examples/go-library/prepare
|
|
|
|
|
|
|
|
gofmt -l $(git ls-files '*.go')
|
|
|
|
gofmt -l $(git ls-files '*.go')
|
|
|
|
git diff --check
|
|
|
|
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
The formatting command must produce no paths. Follow every added or changed
|
|
|
|
Then run the documented Markdown-link and repository-hygiene checks from
|
|
|
|
Markdown link and confirm its target and heading exist.
|
|
|
|
`docs/development.md`, followed by:
|
|
|
|
|
|
|
|
|
|
|
|
Also inspect:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
```sh
|
|
|
|
|
|
|
|
git diff --check
|
|
|
|
git status --short
|
|
|
|
git status --short
|
|
|
|
git diff --stat
|
|
|
|
|
|
|
|
git diff
|
|
|
|
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Confirm that:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- production changes are limited to the root convenience API;
|
|
|
|
|
|
|
|
- no internal backend, registry, capacity, profile, or engine behavior
|
|
|
|
|
|
|
|
changed;
|
|
|
|
|
|
|
|
- `BackendLocal` is conventional and consumer-registerable, not built in or
|
|
|
|
|
|
|
|
reserved;
|
|
|
|
|
|
|
|
- `LocalBackend` performs no validation, normalization, environment lookup,
|
|
|
|
|
|
|
|
registration, allocation, or hidden default selection;
|
|
|
|
|
|
|
|
- the returned `Backend` leaves `QueueCapacity` nil so existing positive-limit
|
|
|
|
|
|
|
|
defaulting remains owned by the registry;
|
|
|
|
|
|
|
|
- existing endpoint-only profiles and complete custom backends remain
|
|
|
|
|
|
|
|
documented and supported;
|
|
|
|
|
|
|
|
- current-state documentation describes only the now-implemented API and
|
|
|
|
|
|
|
|
links to the canonical GoDoc for exact semantics;
|
|
|
|
|
|
|
|
- no `go.work`, `go.work.sum`, local module replacement, credential,
|
|
|
|
|
|
|
|
generated binary, or unrelated change was introduced; and
|
|
|
|
|
|
|
|
- the feature and implementation roadmaps contain no unresolved work marked
|
|
|
|
|
|
|
|
complete.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Completion Gate
|
|
|
|
### Completion Gate
|
|
|
|
|
|
|
|
|
|
|
|
Stage 2 is complete when every target-end-state item in
|
|
|
|
Stage 4 and the feature are complete when:
|
|
|
|
`local-backend.md` is implemented, the consumer guide clearly presents all
|
|
|
|
|
|
|
|
three configuration paths, all complete validation commands pass, all changed
|
|
|
|
|
|
|
|
links resolve, and the roadmap statuses accurately report completion.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Implementation Handoff
|
|
|
|
- exact public contracts and task-oriented guidance are documented at their
|
|
|
|
|
|
|
|
canonical owners;
|
|
|
|
The implementation handoff should report:
|
|
|
|
- internal source, validation, execution, credential, and capacity boundaries
|
|
|
|
|
|
|
|
are accurately described without duplicating public GoDoc;
|
|
|
|
- the new `BackendLocal` and `LocalBackend` public API;
|
|
|
|
- all changed links resolve and no documentation claims unimplemented
|
|
|
|
- that the helper remains explicit and composes with the ordinary backend
|
|
|
|
behavior;
|
|
|
|
registry;
|
|
|
|
- the complete ordinary and race test suites pass offline;
|
|
|
|
- the focused public-contract coverage added;
|
|
|
|
- the maintained preparation example, vet, build, formatting, link, hygiene,
|
|
|
|
- the consumer-guide decision path added;
|
|
|
|
and whitespace checks pass;
|
|
|
|
- the complete validation commands and results; and
|
|
|
|
- the final diff is limited to the feature, its tests, documentation, and
|
|
|
|
- any unrelated working-tree changes that were preserved.
|
|
|
|
already-present roadmap changes; and
|
|
|
|
|
|
|
|
- both roadmap documents accurately report completion.
|
|
|
|
Do not claim that a local backend is built in, pre-registered, configured from
|
|
|
|
|
|
|
|
environment variables, or assigned a default model or concurrency limit.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Open Questions
|
|
|
|
## Open Questions
|
|
|
|
|
|
|
|
|
|
|
|
None. The feature roadmap and this plan fix the exported API, constructor
|
|
|
|
None.
|
|
|
|
semantics, identity treatment, compatibility behavior, test boundary,
|
|
|
|
|
|
|
|
documentation ownership, implementation sequence, validation gates, and
|
|
|
|
|
|
|
|
non-goals required for implementation.
|
|
|
|
|
|
|
|
|
