Skip to content

Commit 3391b22

Browse files
nshkrdotcomnshkrdotcom
committed
Add fugu readiness handoff proof
1 parent 3af32fe commit 3391b22

13 files changed

Lines changed: 575 additions & 27 deletions

‎README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ The current harness covers:
6767
- persistence-profile matrix receipts with explicit store, tier, capture, and
6868
restart-claim fields
6969
- GEPA, TRINITY, cost/budget, and adaptive-control prior-fabric proofs
70+
- fugu single-node readiness handoff for the distributed `nshkr_v2` proof plan
7071
- AITrace-backed receipt collection and release-proof mapping
7172

7273
This makes StackLab the answer to "does the stack claim have executable proof?"
@@ -292,6 +293,15 @@ root that composes Linear terminal publication, GitHub disposable PR
292293
creation/review/cleanup, Codex app-server execution, Temporal substrate status,
293294
and a local receipt without accepting static provider selectors.
294295
Provider smoke remains a provider/substrate check, not product acceptance.
296+
For fugu closeout, the guarded wrapper refuses live-provider smoke unless the
297+
caller passes explicit live and secrets-loaded flags after using the documented
298+
secret wrapper:
299+
300+
```bash
301+
mix stack_lab.fugu.readiness_handoff --json
302+
~/scripts/with_bash_secrets mix stack_lab.fugu.live_provider_smoke --allow-live --secrets-loaded -- --linear-api-key-stdin
303+
```
304+
295305
Extravaganza product behavior is externally accepted by shelling out to the
296306
product-owned command:
297307

‎docs/gn_ten_proof_matrix.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,12 @@ path, and run GitHub or Linear live commands by prefixing them with
139139
`Trinity.MezzanineRouterAdapter`, Mezzanine render handoff, Jido fake model
140140
invocation, AITrace bounded route/model/eval facts, AppKit projections, and
141141
StackLab context/router/coordination/model scanner receipts.
142+
- `fugu_single_node_readiness_handoff`: records the Phase 16 single-node
143+
provider-free handoff receipt that unblocks the `../nshkr_v2` distributed
144+
StackLab checklist. It names Context ABI, router fabric, and Extravaganza
145+
external acceptance as required upstream proofs, records that live provider
146+
checks are opt-in through explicit flags plus `~/scripts/with_bash_secrets`,
147+
and leaves distributed BEAM placement to v2.
142148
- `cost_budget_scanner`: verifies adaptive token, provider request,
143149
self-hosted GPU minute, endpoint startup, eval batch, replay, optimization
144150
search, provider pool turn, role budget, promotion, failed retry, budget

‎docs/receipts/gn_ten_phase16/fugu_single_node_handoff.json‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
{
2+
"schema_version": "stack_lab.fugu_single_node_readiness.v1",
3+
"status": "pass",
4+
"receipt_ref": "receipt://stack_lab/fugu_single_node_readiness/latest",
5+
"handoff_scope": "single_node_provider_free_fugu_substrate",
6+
"v2_unblocker?": true,
7+
"v2_readiness_gate": {
8+
"target_docset": "../nshkr_v2",
9+
"unblocks_phase": "Phase 0 readiness audit and Phase 8 context distributed proof",
10+
"blocked_until_required_proofs_green?": true
11+
},
12+
"required_provider_free_proofs": [
13+
{
14+
"proof_id": "context_abi_roundtrip",
15+
"command": "cd examples/context_abi_roundtrip && mix stack_lab.context_abi.roundtrip --json",
16+
"receipt_ref": "receipt://stack_lab/context_abi_roundtrip/latest",
17+
"required_status": "implemented"
18+
},
19+
{
20+
"proof_id": "nshkr_router_fabric_roundtrip",
21+
"command": "cd examples/nshkr_router_fabric_roundtrip && mix stack_lab.nshkr.router_fabric.roundtrip --json",
22+
"receipt_ref": "receipt://stack_lab/nshkr_router_fabric_roundtrip/latest",
23+
"required_status": "implemented"
24+
},
25+
{
26+
"proof_id": "extravaganza_external_acceptance",
27+
"command": "mix stack_lab.extravaganza.external_acceptance --json",
28+
"receipt_ref": "receipt://stack_lab/extravaganza_external_acceptance/latest",
29+
"required_status": "implemented"
30+
}
31+
],
32+
"live_provider_profile": {
33+
"schema_version": "stack_lab.fugu_live_provider_guard.v1",
34+
"live_provider_behavior_ci_default?": false,
35+
"requires_explicit_flags": [
36+
"--allow-live",
37+
"--secrets-loaded"
38+
],
39+
"required_secret_wrapper": "~/scripts/with_bash_secrets",
40+
"guarded_command": "mix stack_lab.provider_smoke_check",
41+
"does_not_prove": [
42+
"production credential rotation",
43+
"provider billing correctness",
44+
"multi-product live-provider parity",
45+
"distributed BEAM placement"
46+
]
47+
},
48+
"persistence_and_restart_claims": {
49+
"single_node_profile": "provider_free_deterministic",
50+
"persistence_profile": "ref_only_fixture",
51+
"restart_claim": "covered_by_existing_restart_and_persistence proof rows where cited",
52+
"temporal_claim": "not started by fugu handoff",
53+
"postures": [
54+
"no live provider credentials required",
55+
"no distributed topology claim",
56+
"generated receipts stay under StackLab tmp or docs/receipts"
57+
]
58+
},
59+
"distributed_claim": {
60+
"proven?": false,
61+
"handoff_owner": "../nshkr_v2",
62+
"safe_action": "prove placement through StackLab distributed topology profiles"
63+
},
64+
"does_not_prove": [
65+
"live provider behavior",
66+
"distributed BEAM placement",
67+
"production persistence",
68+
"production credential rotation",
69+
"49-node local scale feasibility"
70+
]
71+
}

‎docs/receipts/gn_ten_phase16/fugu_single_node_handoff.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Fugu Single-Node Readiness Handoff
2+
3+
This checked-in receipt records the Phase 16 closeout posture for the fugu
4+
single-node substrate.
5+
6+
Command:
7+
8+
```bash
9+
mix stack_lab.fugu.readiness_handoff --json
10+
```
11+
12+
Required upstream provider-free proofs:
13+
14+
- `context_abi_roundtrip`;
15+
- `nshkr_router_fabric_roundtrip`;
16+
- `extravaganza_external_acceptance`.
17+
18+
Live provider behavior remains opt-in. The guarded wrapper is:
19+
20+
```bash
21+
~/scripts/with_bash_secrets mix stack_lab.fugu.live_provider_smoke --allow-live --secrets-loaded -- --linear-api-key-stdin
22+
```
23+
24+
This handoff does not prove distributed BEAM placement, production
25+
persistence, provider billing, credential rotation, or 49-node scale. Those
26+
claims belong to the `../nshkr_v2` distributed StackLab checklist or later
27+
live-provider product cutover evidence.

‎lib/mix/tasks/stack_lab.fugu.live_provider_smoke.ex‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
defmodule Mix.Tasks.StackLab.Fugu.LiveProviderSmoke do
2+
@moduledoc """
3+
Guarded live-provider smoke wrapper for fugu closeout.
4+
5+
The command refuses to run unless live behavior is explicitly requested and
6+
the caller asserts that secrets were loaded through the documented wrapper.
7+
Provider arguments are passed after `--`.
8+
"""
9+
10+
use Mix.Task
11+
12+
alias StackLab.FuguLiveProviderGuard
13+
14+
@shortdoc "Run guarded opt-in live provider smoke for fugu"
15+
16+
@impl Mix.Task
17+
def run(args) do
18+
Mix.Task.run("app.start")
19+
20+
{guard_args, provider_args} = split_forwarded_args(args)
21+
22+
{opts, _argv, invalid} =
23+
OptionParser.parse(guard_args,
24+
strict: [
25+
allow_live: :boolean,
26+
secrets_loaded: :boolean,
27+
dry_run: :boolean,
28+
json: :boolean
29+
]
30+
)
31+
32+
if invalid != [] do
33+
Mix.raise("invalid options: #{inspect(invalid)}")
34+
end
35+
36+
guard_opts = [
37+
allow_live?: Keyword.get(opts, :allow_live, false),
38+
secrets_loaded?: Keyword.get(opts, :secrets_loaded, false),
39+
execution_mode: execution_mode(opts),
40+
command: forwarded_command(provider_args)
41+
]
42+
43+
case FuguLiveProviderGuard.validate(guard_opts) do
44+
{:ok, receipt} ->
45+
maybe_run_provider_smoke(opts, provider_args)
46+
print_success(receipt, Keyword.get(opts, :json, false))
47+
48+
{:error, reason} ->
49+
print_failure(reason, Keyword.get(opts, :json, false))
50+
end
51+
end
52+
53+
defp split_forwarded_args(args) do
54+
{guard_args, rest} = Enum.split_while(args, &(&1 != "--"))
55+
56+
case rest do
57+
["--" | provider_args] -> {guard_args, provider_args}
58+
[] -> {guard_args, []}
59+
end
60+
end
61+
62+
defp execution_mode(opts) do
63+
if Keyword.get(opts, :dry_run, false), do: "dry_run_guard_passed", else: "delegated_live_run"
64+
end
65+
66+
defp forwarded_command([]), do: "mix stack_lab.provider_smoke_check"
67+
68+
defp forwarded_command(provider_args) do
69+
Enum.join(["mix", "stack_lab.provider_smoke_check" | provider_args], " ")
70+
end
71+
72+
defp maybe_run_provider_smoke(opts, provider_args) do
73+
if Keyword.get(opts, :dry_run, false) do
74+
:ok
75+
else
76+
Mix.Task.reenable("stack_lab.provider_smoke_check")
77+
Mix.Task.run("stack_lab.provider_smoke_check", provider_args)
78+
end
79+
end
80+
81+
defp print_success(receipt, true), do: Mix.shell().info(Jason.encode!(receipt, pretty: true))
82+
83+
defp print_success(receipt, false) do
84+
Mix.shell().info("stack_lab.fugu.live_provider_smoke guard passed")
85+
Mix.shell().info("execution_mode=#{receipt["execution_mode"]}")
86+
Mix.shell().info("forwarded_command=#{receipt["forwarded_command"]}")
87+
end
88+
89+
defp print_failure(reason, true) do
90+
%{status: "fail", error: reason}
91+
|> Jason.encode!(pretty: true)
92+
|> Mix.shell().error()
93+
94+
exit({:shutdown, 1})
95+
end
96+
97+
defp print_failure(reason, false) do
98+
Mix.shell().error("stack_lab.fugu.live_provider_smoke rejected")
99+
Mix.shell().error(" #{inspect(reason)}")
100+
exit({:shutdown, 1})
101+
end
102+
end

‎lib/mix/tasks/stack_lab.fugu.readiness_handoff.ex‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
defmodule Mix.Tasks.StackLab.Fugu.ReadinessHandoff do
2+
@moduledoc "Writes the provider-free fugu single-node readiness handoff receipt."
3+
4+
use Mix.Task
5+
6+
alias StackLab.FuguReadinessHandoff
7+
8+
@shortdoc "Write the fugu single-node readiness handoff receipt"
9+
10+
@impl Mix.Task
11+
def run(args) do
12+
Mix.Task.run("app.start")
13+
14+
{opts, _argv, invalid} =
15+
OptionParser.parse(args,
16+
strict: [
17+
receipt: :string,
18+
json: :boolean,
19+
source_ref: :string
20+
]
21+
)
22+
23+
if invalid != [] do
24+
Mix.raise("invalid options: #{inspect(invalid)}")
25+
end
26+
27+
run_opts =
28+
[]
29+
|> maybe_put(opts, :source_ref)
30+
31+
{:ok, receipt} = FuguReadinessHandoff.run(run_opts)
32+
receipt_path = Keyword.get(opts, :receipt, FuguReadinessHandoff.default_receipt_path())
33+
path = FuguReadinessHandoff.write_receipt!(receipt, receipt_path)
34+
print_success(receipt, path, Keyword.get(opts, :json, false))
35+
end
36+
37+
defp maybe_put(run_opts, opts, key) do
38+
case Keyword.fetch(opts, key) do
39+
{:ok, value} -> Keyword.put(run_opts, key, value)
40+
:error -> run_opts
41+
end
42+
end
43+
44+
defp print_success(receipt, path, true) do
45+
receipt
46+
|> Map.put("receipt_path", path)
47+
|> Jason.encode!(pretty: true)
48+
|> Mix.shell().info()
49+
end
50+
51+
defp print_success(receipt, path, false) do
52+
Mix.shell().info("stack_lab.fugu.readiness_handoff passed")
53+
Mix.shell().info("receipt=#{path}")
54+
Mix.shell().info("receipt_ref=#{receipt["receipt_ref"]}")
55+
Mix.shell().info("v2_unblocker=#{receipt["v2_unblocker?"]}")
56+
end
57+
end

‎lib/stack_lab/fugu_live_provider_guard.ex‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
defmodule StackLab.FuguLiveProviderGuard do
2+
@moduledoc false
3+
4+
@schema_version "stack_lab.fugu_live_provider_guard.v1"
5+
@secret_wrapper "~/scripts/with_bash_secrets"
6+
@default_command "mix stack_lab.provider_smoke_check"
7+
8+
@spec validate(keyword()) :: {:ok, map()} | {:error, map()}
9+
def validate(opts) when is_list(opts) do
10+
allow_live? = Keyword.get(opts, :allow_live?, false)
11+
secrets_loaded? = Keyword.get(opts, :secrets_loaded?, false)
12+
13+
cond do
14+
allow_live? and secrets_loaded? ->
15+
{:ok, receipt(opts)}
16+
17+
allow_live? ->
18+
{:error,
19+
error("live_profile_requires_secret_wrapper",
20+
required_prefix: @secret_wrapper,
21+
safe_action: "rerun_with_secret_wrapper_or_drop_live_flag"
22+
)}
23+
24+
secrets_loaded? ->
25+
{:error,
26+
error("live_profile_requires_allow_live",
27+
required_flag: "--allow-live",
28+
safe_action: "rerun_with_explicit_live_opt_in"
29+
)}
30+
31+
true ->
32+
{:error,
33+
error("live_profile_requires_explicit_opt_in",
34+
required_flags: ["--allow-live", "--secrets-loaded"],
35+
safe_action: "run_provider_free_readiness_handoff_instead"
36+
)}
37+
end
38+
end
39+
40+
@spec claim() :: map()
41+
def claim do
42+
%{
43+
"schema_version" => @schema_version,
44+
"live_provider_behavior_ci_default?" => false,
45+
"requires_explicit_flags" => ["--allow-live", "--secrets-loaded"],
46+
"required_secret_wrapper" => @secret_wrapper,
47+
"guarded_command" => @default_command,
48+
"does_not_prove" => [
49+
"production credential rotation",
50+
"provider billing correctness",
51+
"multi-product live-provider parity",
52+
"distributed BEAM placement"
53+
]
54+
}
55+
end
56+
57+
defp receipt(opts) do
58+
claim()
59+
|> Map.merge(%{
60+
"status" => "guard_passed",
61+
"execution_mode" => Keyword.get(opts, :execution_mode, "ready_to_run"),
62+
"forwarded_command" => Keyword.get(opts, :command, @default_command)
63+
})
64+
end
65+
66+
defp error(code, details) do
67+
%{
68+
"schema_version" => @schema_version,
69+
"status" => "rejected",
70+
"code" => code,
71+
"details" => Map.new(details)
72+
}
73+
end
74+
end

0 commit comments

Comments
 (0)