@aviaratech/ai-delivery 0.3.17 → 0.3.18

package/README.md

@@ -427,6 +427,71 @@ proof. A stopped or failed publish/finish must be read back before retrying;
 never infer completion from a timed-out command. Task assignment and model
 routing belong to a separate orchestrator, not this CLI.
 
+## Bounded issue source phases
+
+The root and `@aviaratech/ai-delivery/agent` exports provide
+`withIssueSourcePhase(input, async context => { ... })` for an expressly
+authorized source graph in an existing registered issue worktree. The input
+binds its exact row and ownership witness, configured authenticated author,
+admitted executing SDK, primary controller HEAD/configuration, and separate
+candidate HEAD/index/dirty files/configuration. Declare frozen caller and input
+artifact digests, resolved command executables/argv/cwd, effective environment
+digest and overrides, completion artifacts, disjoint output roots and fixed
+RSS/output/disk bounds. Environment values stay in memory; records contain its
+digest. The selected SDK's producer commit and the consumer controller HEAD
+are separate identities.
+
+`identity` selects the configured authenticated author. Historical worktree
+custody may name a different principal: the exact canonical row digest and
+ownership witness remain bound and unchanged throughout the phase. The receipt
+binds that row separately from its authenticated actor; entering a source phase
+does not transfer custody or alias those principals.
+
+Inside the callback, prepare owned metadata and `await context.run(index)` for
+every command, in order, once. The context exposes read-only source,
+controller, authenticated actor and input identities. It permits one active
+command and expires when the callback settles. An unawaited command cancels
+the phase and triggers identity-bound descendant cleanup. This is a trusted
+cooperative callback: use its AbortSignal and issue all subprocesses through
+`run`. JavaScript is not sandboxed. Source must preserve the exact initial
+snapshot or produce the one declared commit with its exact parent/tree and
+clean postconditions. Normal commit hooks remain enabled.
+
+The existing writer fence is published before lengthy validation/scans. The
+same runner accounts for the controller and owned descendants, captured logs,
+callback output and SDK metadata under one original cumulative physical
+baseline. New command calls cannot replace the graph, environment, roots or
+allocation. Cancellation and lock compromise cancel owned work; process
+cleanup, output accounting, writer release and lock release failures remain
+distinct. Completion is sealed only after accounting and confirmed release.
+The shared writer admission check continues to exclude other worktree writers
+while this source-phase record is unsealed, including the release-to-seal interval.
+
+The finite private `ai-delivery.source-phase@1` record is stored beneath the
+Git common directory's `ai-delivery/receipts/source-phase@1`, keyed by worktree
+and complete input digests. A compatible completed record can be returned
+without entering the callback or replaying commands after validating source,
+producer, admission and artifacts. A terminal `failed-quiescent` or
+`rejected-before-work` attempt can be followed only by an expressly authorized
+new input naming its exact predecessor phaseId/recordId, original baselineId
+when present, and authorization digest in `reconciliation`. Retain original
+source/runtime/input and allocation bindings and all output/bootstrap charges;
+corrected rejected inputs supply no reusable proof. Intermediate command
+results are never replay checkpoints. A missing or mistyped predecessor can be
+corrected without discarding its rejected record: validated retention edges
+carry every rejected sibling's bootstrap charge, separately from the requested
+reconciliation and any reusable source/runtime proof. Every attempt inherits
+the retained original allocation and charges prior attempts before checking
+work authorization. Rejected requests cannot enlarge that allocation or change
+its roots. Exhaustion remains unresolved and refuses another record or writer
+claim. Interrupted intent, uncertain commits,
+changed frozen inputs or unconfirmed release remain unresolved and refuse a
+new attempt; the API supplies no previous-process recovery or force-unblock.
+
+Its receipt proves this bounded operation only. Canonical verification,
+independent acceptance, scientific holds and receiving runtime selection keep
+their existing owners and checks.
+
 ## Compatibility contract
 
 The MCP input and result contract is `ai-delivery.mcp@1`, exported as `AI_DELIVERY_MCP_CONTRACT_VERSION`. It retains the 13 `issue_*` tool names. Each tool rejects unknown fields at the request boundary. `issue_create` accepts a title with optional body, Issue Type, Points, Priority, taxonomy labels, milestone, parent and blockers; it returns `{body, created: {number, title, url}, routing}`. A linked parent is read back and cleared of Points. `issue_start({issueNumber})` always checks readiness and prepares that existing issue; `develop` gates only preparation of a newly created issue. New starts default to 2 Points. `resumeCreated` requires both `issueNumber` and `develop: true` and never creates a second issue. Immediate creation and development preflights readiness before creation and returns `ai-delivery.issue-start-registration@1` with `status: "started"` or a `created-not-started` failure and exact `safeResume` arguments. The CLI prints that recovery JSON and exits nonzero for `created-not-started`. Scratch starts derive safe names from the request or title and return the branch and worktree path. `repo` on create, start and ready check, or global CLI `--repo`, must match the repository selected by the checkout's validated Git remote; a mismatch fails before a GitHub call.

package/dist/agent.d.ts

@@ -14,7 +14,8 @@ export { buildVelocityReport, getDeliveryRecords, recordMergedDelivery } from '.
 export type { DeliveryRecord, VelocityReport, PointBucketStatistics } from './services/deliveryRecordService.js';
 export { getIssueWorktreeStrict, listWorktreesStrict } from './services/worktreeRegistry.js';
 export { prepareIssueWorktree, prepareStandaloneWorktree } from './worktree.js';
-export { verifyIssue, createIssuePhaseEvidence, withVerificationFilesystemFixture } from './verification.js';
+export { verifyIssue, createIssuePhaseEvidence, withVerificationFilesystemFixture, withIssueSourcePhase, } from './verification.js';
+export type { IssueSourcePhaseInput, IssueSourcePhaseContext, IssueSourcePhaseReceipt } from './verification.js';
 export { discoverDeliveryRouting } from './github/discovery.js';
 export type { DeliveryRouting, DiscoveryClients } from './github/discovery.js';
 export type { DeliveryOverrides, DeliveryPolicySettings, LoadedDeliverySettings } from './config/deliveryConfig.js';

package/dist/agent.js

@@ -12,7 +12,7 @@ export { normalizeLegacyIssue, planOfflineLegacyIssueMigration } from './service
 export { buildVelocityReport, getDeliveryRecords, recordMergedDelivery } from './services/deliveryRecordService.js';
 export { getIssueWorktreeStrict, listWorktreesStrict } from './services/worktreeRegistry.js';
 export { prepareIssueWorktree, prepareStandaloneWorktree } from './worktree.js';
-export { verifyIssue, createIssuePhaseEvidence, withVerificationFilesystemFixture } from './verification.js';
+export { verifyIssue, createIssuePhaseEvidence, withVerificationFilesystemFixture, withIssueSourcePhase, } from './verification.js';
 export { discoverDeliveryRouting } from './github/discovery.js';
 export { stageRuntime, admitRuntime, RuntimeAdmissionCommitUnknownError } from './setup.js';
 //# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,8BAA8B,GAC/B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,gCAAgC,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AACpH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC/G,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,kBAAkB,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACrH,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EACL,6BAA6B,EAC7B,8BAA8B,EAC9B,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,oBAAoB,EAAE,+BAA+B,EAAE,MAAM,oCAAoC,CAAC;AAC3G,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAEpH,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,iCAAiC,EAAE,MAAM,mBAAmB,CAAC;AAE7G,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAIhE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,kCAAkC,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,8BAA8B,GAC/B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,gCAAgC,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AACpH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC/G,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,kBAAkB,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACrH,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EACL,6BAA6B,EAC7B,8BAA8B,EAC9B,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,oBAAoB,EAAE,+BAA+B,EAAE,MAAM,oCAAoC,CAAC;AAC3G,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAEpH,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EACL,WAAW,EACX,wBAAwB,EACxB,iCAAiC,EACjC,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAIhE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,kCAAkC,EAAE,MAAM,YAAY,CAAC"}