mirror of
https://github.com/Sea-Haven-Industries/procurement-ingest.git
synced 2026-10-07 16:08:54 +00:00
Compare commits
4 commits
ca4f43a2cc
...
3c28df05a6
| Author | SHA1 | Date | |
|---|---|---|---|
|
3c28df05a6 | ||
|
|
004474fc1d | ||
|
|
65feb3a4d9 | ||
|
|
ff368beaa4 |
47 changed files with 2863 additions and 4451 deletions
|
|
@ -1,428 +0,0 @@
|
|||
export const meta = {
|
||||
name: 'phase-0-deploy-guards',
|
||||
description: 'Phase 0 of the procurement-ingest refactor (docs/refactor-evaluation.md): healthcheck early-return in both email processors, synchronous post-deploy smoke script wired into cd-cdk, PO cp-allowlist replaced with a non-recursive glob, and an AST bundle-consistency test. Built and adversarially verified on a branch off main, committed locally, never pushed (push is gated on /sh-security-review in the main loop).',
|
||||
phases: [
|
||||
{ title: 'Setup', detail: 'clean-tree check, branch feature/phase-0-deploy-guards off up-to-date main', model: 'haiku' },
|
||||
{ title: 'Recon', detail: '4 parallel read-only mappers over handlers, CDK/alarms/CI, and test infra', model: 'haiku' },
|
||||
{ title: 'Implement', detail: 'handlers on opus; smoke script, CDK glob + AST test on sonnet — disjoint file ownership, one branch', model: 'opus' },
|
||||
{ title: 'Verify', detail: 'mechanical gates (pytest/ruff/synth/scope) on sonnet + 3 adversarial fable lenses' },
|
||||
{ title: 'Fix', detail: 'opus fixer applies confirmed findings, full re-verify, max 3 rounds', model: 'opus' },
|
||||
{ title: 'Package', detail: 'README update, GPT-4.1 cross-family review of the diff, single commit via -F (no push)', model: 'sonnet' },
|
||||
],
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------- constants
|
||||
|
||||
const REPO = '/Users/adammoussa/Documents/repositories/seahaven/procurement-ingest'
|
||||
const BRANCH = 'feature/phase-0-deploy-guards'
|
||||
|
||||
// Pinned contract (memory lesson: define the shared contract BEFORE the
|
||||
// parallel fan-out — parallel leaves can't see each other's choices).
|
||||
const CONTRACT = `
|
||||
HEALTHCHECK CONTRACT — pinned, do not deviate or "improve":
|
||||
- Trigger: top-level direct-invoke payload only. In lambda handler ("handler"
|
||||
in handler.py), the VERY FIRST statements: if the event is a dict and
|
||||
event.get("healthcheck") is True -> return {"healthcheck": "ok"} immediately.
|
||||
- Placement: BEFORE any boto3/S3 use, BEFORE ses_auth, BEFORE iterating
|
||||
event["Records"]. It must not create any accept path for mail: real mail
|
||||
events are S3 ObjectCreated events whose top-level keys AWS controls
|
||||
("Records"); email content can never set a top-level event key.
|
||||
- Telemetry: the healthcheck branch emits NO EMF metrics and NO log line
|
||||
whose text could match the sender-auth-rejected metric-filter pattern
|
||||
(read the filter pattern in cdk/*_stack.py before choosing any log text;
|
||||
safest is a single log line exactly "healthcheck ok" or no logging).
|
||||
That alarm pages at >=1 match, so two deploys in ~30 min must not page.
|
||||
- SMOKE SCRIPT CONTRACT: scripts/post-deploy-smoke.sh invokes BOTH functions
|
||||
(po-email-processor, workorder-email-processor) with payload
|
||||
'{"healthcheck": true}' using: aws lambda invoke --invocation-type
|
||||
RequestResponse. It must check the FunctionError field of the response
|
||||
(an init ImportError returns HTTP 200 + FunctionError=Unhandled — exit-code
|
||||
checks false-pass) AND that the payload equals {"healthcheck": "ok"}.
|
||||
Non-zero exit on any failure; set -euo pipefail; region us-east-1.
|
||||
`
|
||||
|
||||
const PREAMBLE = `
|
||||
You are one of several agents building refactor Phase 0 in the git repo at
|
||||
${REPO} on branch ${BRANCH} (already checked out — do NOT switch branches,
|
||||
do NOT create branches, do NOT commit, NEVER push, do NOT run cdk deploy or
|
||||
touch AWS resources; read-only aws CLI calls are also unnecessary).
|
||||
Authoritative spec: docs/refactor-evaluation.md, section "Phase 0".
|
||||
Work ONLY in the files you are told you own. Other agents are concurrently
|
||||
editing other files in this same working tree — do not read-depend on or
|
||||
modify their files.
|
||||
${CONTRACT}
|
||||
Your final message is consumed by an orchestrator script, not a human —
|
||||
return only the structured data requested.
|
||||
`
|
||||
|
||||
// ------------------------------------------------------------------ schemas
|
||||
|
||||
const RECON = {
|
||||
type: 'object',
|
||||
required: ['summary', 'facts'],
|
||||
properties: {
|
||||
summary: { type: 'string' },
|
||||
facts: { type: 'array', items: { type: 'string' } },
|
||||
blockers: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const IMPL = {
|
||||
type: 'object',
|
||||
required: ['filesChanged', 'testsAdded', 'summary', 'checksRun'],
|
||||
properties: {
|
||||
filesChanged: { type: 'array', items: { type: 'string' } },
|
||||
testsAdded: { type: 'array', items: { type: 'string' } },
|
||||
summary: { type: 'string' },
|
||||
checksRun: { type: 'string', description: 'exact commands run + pass/fail' },
|
||||
blockers: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const CHECKS = {
|
||||
type: 'object',
|
||||
required: ['passed', 'details'],
|
||||
properties: {
|
||||
passed: { type: 'boolean' },
|
||||
details: { type: 'string', description: 'per-gate results; verbatim failure output' },
|
||||
scopeViolations: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const FINDINGS = {
|
||||
type: 'object',
|
||||
required: ['findings'],
|
||||
properties: {
|
||||
findings: {
|
||||
type: 'array',
|
||||
items: {
|
||||
type: 'object',
|
||||
required: ['title', 'severity', 'confirmed', 'evidence', 'fix'],
|
||||
properties: {
|
||||
title: { type: 'string' },
|
||||
severity: { enum: ['critical', 'high', 'medium', 'low'] },
|
||||
confirmed: { type: 'boolean', description: 'true only with concrete file:line evidence' },
|
||||
evidence: { type: 'string' },
|
||||
fix: { type: 'string' },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
const TEXT = {
|
||||
type: 'object',
|
||||
required: ['summary'],
|
||||
properties: { summary: { type: 'string' }, verdict: { type: 'string' } },
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------- setup
|
||||
|
||||
phase('Setup')
|
||||
const setup = await agent(`
|
||||
In ${REPO}: verify the working tree is clean apart from untracked .coverage
|
||||
and docs/refactor-evaluation.md (if anything ELSE is dirty, STOP and report a
|
||||
blocker — do not stash or discard anything). Then:
|
||||
git fetch origin && git checkout main && git pull --ff-only
|
||||
git checkout -b ${BRANCH}
|
||||
Also run: gh pr list --state open --json number,title,headRefName
|
||||
(memory lesson: a branch cut fresh from main misses fixes sitting in unmerged
|
||||
PRs — list them so the orchestrator can flag overlaps).
|
||||
Return facts: current HEAD sha, branch created y/n, open PR list, blockers.
|
||||
`, { label: 'setup:branch', model: 'haiku', schema: RECON })
|
||||
|
||||
if (setup && setup.blockers && setup.blockers.length) {
|
||||
return { aborted: 'setup blockers', blockers: setup.blockers, openPRs: setup.facts }
|
||||
}
|
||||
log(`Branch ${BRANCH} ready. ${setup ? setup.summary : ''}`)
|
||||
|
||||
// ------------------------------------------------------------------- recon
|
||||
|
||||
phase('Recon')
|
||||
const recon = await parallel([
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of lambdas/po/email_processor/handler.py and its tests dir.
|
||||
Report: exact def line of the lambda handler; the first statements it executes
|
||||
(S3 fetch? ses_auth call? Records iteration?) with line numbers; how existing
|
||||
handler tests load the module and fake AWS (loader idiom, moto import-order
|
||||
invariant in _po_parser_support.py); where a healthcheck test would naturally
|
||||
live; any existing early-return branches. 10-20 precise facts.`,
|
||||
{ label: 'recon:po-handler', model: 'haiku', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of lambdas/wo/email_processor/handler.py and its tests dir.
|
||||
Same report shape: handler def line, first statements executed with line
|
||||
numbers, test loader idiom (_wo_parser_support.py), where a healthcheck test
|
||||
lives, existing early returns. 10-20 precise facts.`,
|
||||
{ label: 'recon:wo-handler', model: 'haiku', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of cdk/po_stack.py, cdk/wo_stack.py and .github/workflows/.
|
||||
Report: (1) the exact PO bundling command incl. the cp allowlist at
|
||||
po_stack.py:~245-256 and the full file list of lambdas/po/email_processor/*.py
|
||||
so the glob replacement can be proven identical-output; (2) the exact
|
||||
sender-auth-rejected metric FILTER PATTERNS in both stacks (quote them
|
||||
verbatim) and their alarm eval windows; (3) deploy.yaml's inputs to the
|
||||
cd-cdk reusable workflow — fetch the pinned workflow file with
|
||||
'gh api repos/Sea-Haven-Industries/.github/contents/.github/workflows/cd-cdk.yaml?ref=fd60e4c9041784f666ac0fdefb9bec3c7fbf5143'
|
||||
(base64 -d the content) and confirm whether a post-deploy-script input exists
|
||||
and its semantics (cwd, when it runs, failure handling). If it does NOT
|
||||
exist, report that as a blocker with the closest available mechanism.
|
||||
(4) WO bundling command for comparison. 15-25 precise facts.`,
|
||||
{ label: 'recon:cdk-ci', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of test infrastructure: pytest.ini, tests/ (repo root),
|
||||
tests/conftest.py, how CI (.github/workflows/ci.yaml) invokes pytest/ruff.
|
||||
Report: how a NEW repo-root test file (tests/test_bundle_consistency.py)
|
||||
would be collected; what it can import; whether tests/ has helpers for
|
||||
locating lambda dirs; the ruff invocation used in CI. 8-15 precise facts.`,
|
||||
{ label: 'recon:tests-ci', model: 'haiku', phase: 'Recon', schema: RECON }),
|
||||
])
|
||||
|
||||
const reconOk = recon.filter(Boolean)
|
||||
const reconBlockers = reconOk.flatMap(r => r.blockers || [])
|
||||
const pack = reconOk.map(r => `## ${r.summary}\n${r.facts.join('\n')}`).join('\n\n')
|
||||
log(`Recon complete: ${reconOk.length}/4 mappers, ${reconBlockers.length} blockers`)
|
||||
|
||||
// --------------------------------------------------------------- implement
|
||||
|
||||
phase('Implement')
|
||||
const implTasks = [
|
||||
{ label: 'impl:po-healthcheck', model: 'opus', prompt: `${PREAMBLE}
|
||||
YOU OWN: lambdas/po/email_processor/handler.py and NEW test file(s) under
|
||||
lambdas/po/email_processor/tests/ ONLY.
|
||||
Task: add the healthcheck early-return branch to the PO handler exactly per
|
||||
the pinned contract. Add tests: (1) {"healthcheck": true} returns
|
||||
{"healthcheck": "ok"} with ZERO S3 calls, ZERO ses_auth calls, ZERO DynamoDB
|
||||
writes, ZERO metric emission (assert via monkeypatch/fakes per the existing
|
||||
loader idiom — preserve the moto-before-handler import ordering); (2) a normal
|
||||
S3 mail event is completely unaffected (an existing golden-path test still
|
||||
passing is necessary but ALSO assert a mail event containing the string
|
||||
"healthcheck" in its email body does NOT take the branch).
|
||||
Run before returning: ruff check lambdas/po, ruff format lambdas/po --check,
|
||||
pytest lambdas/po/email_processor/tests -q --no-cov.
|
||||
Recon context:\n${pack}` },
|
||||
|
||||
{ label: 'impl:wo-healthcheck', model: 'opus', prompt: `${PREAMBLE}
|
||||
YOU OWN: lambdas/wo/email_processor/handler.py and NEW test file(s) under
|
||||
lambdas/wo/email_processor/tests/ ONLY.
|
||||
Task: identical healthcheck branch + tests for the WO handler, per contract,
|
||||
mirroring the PO task one-for-one but using the WO test loader idiom.
|
||||
Run before returning: ruff check lambdas/wo, ruff format lambdas/wo --check,
|
||||
pytest lambdas/wo/email_processor/tests -q --no-cov.
|
||||
Recon context:\n${pack}` },
|
||||
|
||||
{ label: 'impl:smoke-script', model: 'sonnet', prompt: `${PREAMBLE}
|
||||
YOU OWN: scripts/post-deploy-smoke.sh (new) and .github/workflows/deploy.yaml ONLY.
|
||||
Task: write the synchronous smoke script per the pinned SMOKE SCRIPT CONTRACT
|
||||
(both functions, RequestResponse, FunctionError field check + payload check,
|
||||
set -euo pipefail, executable bit, shellcheck-clean). Wire it into deploy.yaml
|
||||
via the cd-cdk reusable workflow's post-deploy-script input per the recon
|
||||
facts below — if recon reported that input missing, implement the closest
|
||||
mechanism recon identified and record a blocker note instead of inventing
|
||||
workflow inputs. Do NOT restructure deploy.yaml otherwise.
|
||||
Run before returning: bash -n scripts/post-deploy-smoke.sh, and
|
||||
python3 -c "import yaml,sys;yaml.safe_load(open('.github/workflows/deploy.yaml'))".
|
||||
Recon context:\n${pack}` },
|
||||
|
||||
{ label: 'impl:bundle-glob-ast', model: 'sonnet', prompt: `${PREAMBLE}
|
||||
YOU OWN: cdk/po_stack.py (ONLY the email-processor bundling command block,
|
||||
~lines 241-258) and tests/test_bundle_consistency.py (new) ONLY.
|
||||
Task A: replace the four-file cp allowlist with a non-recursive glob:
|
||||
"cp ./*.py /asset-output/". Keep the pip install line untouched. Update the
|
||||
warning comment to explain the glob + that the AST test now enforces
|
||||
consistency. PROVE identical output: list lambdas/po/email_processor/*.py
|
||||
(non-recursive) and confirm the set equals {handler, ses_auth,
|
||||
template_parser, derived_fields}.py plus any other top-level .py that SHOULD
|
||||
ship; if extras exist (e.g. prompts or __init__), state explicitly whether
|
||||
shipping them is a no-op and why. tests/ and package/ are directories, so a
|
||||
non-recursive ./*.py glob never matches them.
|
||||
Task B: write tests/test_bundle_consistency.py: for EACH pipeline (po, wo),
|
||||
ast-parse email_processor/handler.py, collect top-level "import X" /
|
||||
"from X import ..." names, filter to first-party siblings (X.py exists in the
|
||||
same dir), and assert the bundling guarantee ships them — for PO: assert the
|
||||
po_stack.py bundling command contains the glob "cp ./*.py"; for WO: assert
|
||||
its bundling command copies them (read wo_stack.py to see its current cp -r
|
||||
form and assert accordingly). The test must FAIL if someone reverts the glob
|
||||
to an allowlist missing a sibling — include a unit-level check that simulates
|
||||
an allowlist command string missing derived_fields.py and asserts the
|
||||
detection logic catches it. No AWS/boto3/synth in the test — pure
|
||||
ast + file reads, fast.
|
||||
Run before returning: ruff check cdk tests, pytest tests/test_bundle_consistency.py -q --no-cov.
|
||||
Recon context:\n${pack}` },
|
||||
]
|
||||
|
||||
const impl = await parallel(implTasks.map(t => () =>
|
||||
agent(t.prompt, { label: t.label, model: t.model, phase: 'Implement', schema: IMPL })))
|
||||
const implOk = impl.filter(Boolean)
|
||||
const implBlockers = implOk.flatMap(r => r.blockers || [])
|
||||
log(`Implement complete: ${implOk.length}/4 agents, blockers: ${implBlockers.length}`)
|
||||
|
||||
// ---------------------------------------------------- verify + fix loop
|
||||
|
||||
const EXPECTED_SCOPE = [
|
||||
'lambdas/po/email_processor/handler.py',
|
||||
'lambdas/po/email_processor/tests/',
|
||||
'lambdas/wo/email_processor/handler.py',
|
||||
'lambdas/wo/email_processor/tests/',
|
||||
'scripts/post-deploy-smoke.sh',
|
||||
'.github/workflows/deploy.yaml',
|
||||
'cdk/po_stack.py',
|
||||
'tests/test_bundle_consistency.py',
|
||||
]
|
||||
|
||||
const mechanicalPrompt = `${PREAMBLE}
|
||||
Independent re-verification (trust-but-verify — do not rely on implementers'
|
||||
self-reports). Run ALL of, reporting each verbatim on failure:
|
||||
1. pytest -q --no-cov (repo root — all 3 roots, expect ~568+new all green)
|
||||
2. ruff check .
|
||||
3. ruff format --check .
|
||||
4. npx cdk synth po-ingest -q && npx cdk synth workorder-ingest -q
|
||||
(run inside cdk/; selectors are ARTIFACT IDs, not stack_name)
|
||||
5. bash -n scripts/post-deploy-smoke.sh; test -x scripts/post-deploy-smoke.sh
|
||||
6. git status --porcelain — every modified/added path must fall under:
|
||||
${EXPECTED_SCOPE.join(', ')} (plus untracked .coverage,
|
||||
docs/refactor-evaluation.md, .claude/workflows/). List violations.
|
||||
7. Grep the healthcheck branch in both handlers: confirm it precedes any S3
|
||||
get_object and any ses_auth call by line number.
|
||||
YOU MAY NOT edit any file. passed=true only if every gate is green and scope
|
||||
is clean.`
|
||||
|
||||
const lenses = [
|
||||
{ key: 'security', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — security lens. Try to REFUTE the safety of this diff
|
||||
(git diff main). Attack: (1) can any S3/SES-delivered email reach the
|
||||
healthcheck branch or any other new early-return (top-level key forgery via
|
||||
event shape, weird typing like event={"healthcheck":"true"} vs True)?
|
||||
(2) does placement before ses_auth weaken fail-closed behavior in ANY path?
|
||||
(3) does the smoke script or deploy.yaml change introduce injection (unquoted
|
||||
vars, payload echoed into shell)? (4) does the AST test import or execute
|
||||
handler code (it must not)? confirmed=true ONLY with a concrete exploit
|
||||
sketch + file:line.` },
|
||||
{ key: 'telemetry', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — telemetry/alarm lens. Read the sender-auth-rejected
|
||||
metric FILTER PATTERNS in cdk/po_stack.py and cdk/wo_stack.py verbatim, then
|
||||
try to prove a healthcheck invocation (incl. Lambda platform START/REPORT
|
||||
lines and any new log text) produces a filter match — that alarm pages at
|
||||
>=1. Also verify: zero EMF emission on the healthcheck path; ParseMethod
|
||||
metric contract untouched (PO emits ai_fallback BEFORE the Bedrock call —
|
||||
must not have moved); no alarm/math changes snuck into po_stack.py beyond
|
||||
the bundling block. confirmed=true only with file:line evidence.` },
|
||||
{ key: 'bundling', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — bundling/CI lens. (1) Enumerate
|
||||
lambdas/po/email_processor/*.py and prove the new glob ships EXACTLY the
|
||||
right set vs the old allowlist {handler,ses_auth,template_parser,
|
||||
derived_fields}.py — flag any extra top-level .py whose shipping is NOT a
|
||||
proven no-op, and confirm tests/ + package/ cannot match a non-recursive
|
||||
./*.py. (2) Mutation-test the AST consistency test: temporarily copy the
|
||||
detection logic and feed it an allowlist string missing derived_fields.py —
|
||||
does it fail? (do this in /tmp scratch, not by editing repo files).
|
||||
(3) Smoke script: does it actually catch FunctionError on HTTP 200 (trace the
|
||||
aws CLI output handling — --query vs jq parsing), and does a missing function
|
||||
name or region default break it? (4) deploy.yaml: is the post-deploy wiring
|
||||
consistent with the cd-cdk reusable workflow's actual input names (re-fetch
|
||||
the pinned file via gh api if needed)? confirmed=true only with evidence.` },
|
||||
]
|
||||
|
||||
let round = 0
|
||||
let checks = null
|
||||
let confirmed = []
|
||||
while (round < 3) {
|
||||
phase('Verify')
|
||||
const results = await parallel([
|
||||
() => agent(mechanicalPrompt, { label: `verify:mechanical-r${round}`, model: 'sonnet', phase: 'Verify', schema: CHECKS }),
|
||||
...lenses.map(l => () =>
|
||||
agent(l.prompt, { label: `verify:${l.key}-r${round}`, phase: 'Verify', schema: FINDINGS })),
|
||||
])
|
||||
checks = results[0]
|
||||
confirmed = results.slice(1).filter(Boolean)
|
||||
.flatMap(r => r.findings || [])
|
||||
.filter(f => f.confirmed && (f.severity === 'critical' || f.severity === 'high' || f.severity === 'medium'))
|
||||
const mechanicalGreen = checks && checks.passed
|
||||
log(`Verify round ${round}: mechanical ${mechanicalGreen ? 'GREEN' : 'RED'}, confirmed findings: ${confirmed.length}`)
|
||||
if (mechanicalGreen && confirmed.length === 0) break
|
||||
|
||||
round += 1
|
||||
if (round >= 3) break
|
||||
phase('Fix')
|
||||
await agent(`${PREAMBLE}
|
||||
You are the fix agent — you may edit any Phase-0-owned file listed here:
|
||||
${EXPECTED_SCOPE.join(', ')}.
|
||||
Fix EVERY item below with the minimal change; do not expand scope; keep the
|
||||
pinned contract intact. Re-run the specific failing check/test for each fix.
|
||||
MECHANICAL FAILURES:\n${checks ? checks.details : '(mechanical agent died — rerun everything)'}
|
||||
CONFIRMED FINDINGS:\n${JSON.stringify(confirmed, null, 2)}`,
|
||||
{ label: `fix:round-${round}`, model: 'opus', phase: 'Fix', schema: IMPL })
|
||||
}
|
||||
|
||||
const verifyClean = checks && checks.passed && confirmed.length === 0
|
||||
if (!verifyClean) {
|
||||
return {
|
||||
status: 'NEEDS ATTENTION — verify not clean after 3 rounds; branch left uncommitted',
|
||||
branch: BRANCH,
|
||||
mechanical: checks,
|
||||
unresolvedFindings: confirmed,
|
||||
implBlockers,
|
||||
reconBlockers,
|
||||
openPRs: setup ? setup.facts : [],
|
||||
}
|
||||
}
|
||||
|
||||
// ----------------------------------------------------------------- package
|
||||
|
||||
phase('Package')
|
||||
const readme = await agent(`${PREAMBLE}
|
||||
YOU OWN: README.md only. Document (in the style of the existing README):
|
||||
the {"healthcheck": true} direct-invoke contract on both processors, the
|
||||
post-deploy smoke gate (what it checks, that FunctionError is the signal),
|
||||
and the PO bundling glob + AST consistency test (replacing the allowlist
|
||||
note if one exists). Same-commit README updates are a handbook requirement.
|
||||
Run: ruff format --check . still clean (README is md, but confirm no stray
|
||||
edits). Return filesChanged.`,
|
||||
{ label: 'package:readme', model: 'sonnet', phase: 'Package', schema: IMPL })
|
||||
|
||||
const crossReview = await agent(`${PREAMBLE}
|
||||
The healthcheck branch adds a new event-contract field to both Lambda
|
||||
handlers — the handbook mandates a cross-family review for handler-signature
|
||||
/ event-shape changes. Run exactly:
|
||||
cd ${REPO} && git diff main > /tmp/phase0.diff
|
||||
python3 ~/Documents/repositories/seahaven/security-review/cross_review.py \
|
||||
"Review this diff for breaking changes. Context: procurement-ingest refactor Phase 0 per docs/refactor-evaluation.md — healthcheck early-return added to both email-processor handlers (new top-level event field, direct-invoke only), post-deploy smoke script, PO bundling cp-allowlist replaced with ./*.py glob, AST bundle-consistency test. Diff follows: $(cat /tmp/phase0.diff)"
|
||||
(cross_review.py is stateless/one-shot — the diff must be inline.) Return its
|
||||
verdict VERBATIM in summary, and set verdict to one of: PASS / FIX / BLOCK
|
||||
based on its highest finding. Do not fix anything yourself.`,
|
||||
{ label: 'package:cross-review', model: 'sonnet', phase: 'Package', schema: TEXT })
|
||||
|
||||
const commit = await agent(`${PREAMBLE.replace('do NOT commit, ', '')}
|
||||
YOU are the commit agent. Steps:
|
||||
1. Read ~/Documents/repositories/seahaven/engineering-handbook/commit-messages.md
|
||||
and follow it exactly.
|
||||
2. git add: the Phase-0 files (${EXPECTED_SCOPE.join(', ')}), README.md, AND
|
||||
docs/refactor-evaluation.md (untracked evaluation report — must land with
|
||||
this first refactor PR or it is lost) AND .claude/workflows/phase-0-deploy-guards.js.
|
||||
Do NOT add .coverage. Verify with git status that nothing unexpected is staged.
|
||||
3. ONE commit. Write the message to /tmp/phase0-commit-msg.txt and use
|
||||
git commit -F /tmp/phase0-commit-msg.txt (backticks in -m get eaten by zsh).
|
||||
Suggested subject: "feat: deploy-pipeline guards — healthcheck, smoke gate, bundle glob + AST test (refactor phase 0)".
|
||||
NO AI attribution / Co-Authored-By lines.
|
||||
4. Do NOT push. Return the commit sha + shortstat in summary.`,
|
||||
{ label: 'package:commit', model: 'sonnet', phase: 'Package', schema: IMPL })
|
||||
|
||||
return {
|
||||
status: 'BUILT — committed locally, NOT pushed',
|
||||
branch: BRANCH,
|
||||
commit: commit ? commit.summary : 'commit agent died — commit manually',
|
||||
crossFamilyReview: crossReview ? { verdict: crossReview.verdict, detail: crossReview.summary } : 'NOT RUN — outstanding',
|
||||
implementation: implOk.map(r => r.summary),
|
||||
filesChanged: implOk.flatMap(r => r.filesChanged).concat(readme ? readme.filesChanged : []),
|
||||
verifyRounds: round + 1,
|
||||
blockers: implBlockers.concat(reconBlockers),
|
||||
openPRsAtBranchTime: setup ? setup.facts : [],
|
||||
outstandingGates: [
|
||||
'/sh-security-review (MANDATORY before push — handler = untrusted-input surface); run in the main loop on the committed diff',
|
||||
'if cross-family verdict is FIX/BLOCK: resolve, re-run cross_review.py on the amended diff',
|
||||
'push + PR + gh pr checks green',
|
||||
'deploy-then-merge: deploy from branch, smoke green, one real PO + WO email each showing ParseMethod=template, all alarms green, THEN merge',
|
||||
],
|
||||
}
|
||||
|
|
@ -1,482 +0,0 @@
|
|||
export const meta = {
|
||||
name: 'phase-2-bundling-root',
|
||||
description: 'Phase 2 of the procurement-ingest refactor (docs/refactor-evaluation.md): widen both email-processor asset roots to ../lambdas (making lambdas/shared/ reachable for Phase 3) with scoped cp globs, add exclude lists (from_asset ignores .gitignore — the stale 44 MB package/ dir would poison asset hashes), and add __pycache__ excludes to the three plain from_asset calls. ZERO code change under lambdas/ — the workflow proves bundle parity by diffing the locally-synthed staged asset against the currently-deployed zip. Committed locally, never pushed.',
|
||||
phases: [
|
||||
{ title: 'Setup', detail: 'verify Phases 0+1 merged into base, branch feature/phase-2-bundling-root', model: 'haiku' },
|
||||
{ title: 'Recon', detail: '3 mappers: all five from_asset sites, deployed zip file lists (read-only AWS), AST-test shapes' },
|
||||
{ title: 'Spec', detail: 'serial opus spec: exact new bundling commands, exclude lists, and the parity-comparison rules', model: 'opus' },
|
||||
{ title: 'Implement', detail: 'sonnet per stack file + sonnet for AST-test/README updates — disjoint files', model: 'sonnet' },
|
||||
{ title: 'Verify', detail: 'mechanical gates + staged-vs-deployed parity + determinism + 2 fable lenses' },
|
||||
{ title: 'Fix', detail: 'opus fixer, full re-verify, max 3 rounds', model: 'opus' },
|
||||
{ title: 'Package', detail: 'single commit via -F (no push)', model: 'sonnet' },
|
||||
],
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------- constants
|
||||
|
||||
const REPO = '/Users/adammoussa/Documents/repositories/seahaven/procurement-ingest'
|
||||
const BRANCH = 'feature/phase-2-bundling-root'
|
||||
const BASE = (args && args.base) || 'main'
|
||||
|
||||
const CONSTRAINTS = `
|
||||
PINNED BEHAVIORAL CONSTRAINTS (docs/refactor-evaluation.md Phase 2 — violating any is a build failure):
|
||||
1. ZERO diff under lambdas/: git diff ${BASE}...HEAD -- lambdas/ must be
|
||||
EMPTY. This phase moves NO code — only cdk/, tests/test_bundle_consistency.py,
|
||||
README.md (and docs/ if needed) may change.
|
||||
2. Both email processors: Code.from_asset("../lambdas") with the bundling
|
||||
command rewritten for the new cwd (bundling cwd IS the asset root):
|
||||
pip install ... -r po/email_processor/requirements.txt -t /asset-output &&
|
||||
cp po/email_processor/*.py /asset-output/ (resp. wo/email_processor).
|
||||
The -r path change is REQUIRED. PRESERVE the pip
|
||||
"--platform manylinux2014_aarch64 --only-binary=:all:" pin exactly — its
|
||||
removal shipped x86 wheels into the ARM64 function and caused a 100%
|
||||
outage (PR #34); it is non-negotiable.
|
||||
3. Both widened from_asset calls get
|
||||
exclude=['**/__pycache__/**', '**/tests/**', '**/package/**'].
|
||||
from_asset does NOT honor .gitignore; without the package/ exclude the
|
||||
stale untracked 44 MB lambdas/po/email_processor/package/ dir diverges
|
||||
LOCAL vs CI asset hashes (CI never has it) and forces spurious redeploys.
|
||||
4. WO prod-zip shrinkage is DELIBERATE cleanup, not an accident to fix: the
|
||||
current 'cp -r .' ships tests/ (real scrubbed .eml fixtures), __pycache__,
|
||||
and requirements.txt in the production zip. The acceptance criterion for
|
||||
WO is "runtime-imported module set unchanged + smoke", NOT byte-identical
|
||||
zip. Byte-identical first-party file set applies to PO ONLY. Document the
|
||||
shrinkage explicitly (list every file class that drops out).
|
||||
5. The three plain from_asset calls (po web_ui, po site_extractor, wo web_ui
|
||||
— locate them, line numbers have shifted since the doc) each gain
|
||||
exclude=['**/__pycache__/**'] so local __pycache__ stops making their
|
||||
asset hashes nondeterministic. Nothing else about them changes.
|
||||
6. tests/test_bundle_consistency.py must be updated IN THE SAME CHANGE — it
|
||||
deliberately change-detects both bundling commands and will fail red on
|
||||
the new shapes. Update it to recognize the scoped glob
|
||||
'cp po/email_processor/*.py' (resp. wo) as the new unconditionally-safe
|
||||
shape, WITHOUT loosening it: the allowlist-revert detection, the
|
||||
detection-logic mutation test, and the PO_EXPECTED_TOP_LEVEL_MODULES
|
||||
exact-set pin must all keep their teeth. A bare-substring match that any
|
||||
commented-out glob satisfies is a regression.
|
||||
7. cdk diff on BOTH stacks must show ONLY the two functions' Code/asset
|
||||
property changes (+ CDK metadata). No logical-ID changes, no alarm, IAM,
|
||||
table, env, or function-config deltas of any kind.
|
||||
8. Do NOT delete lambdas/po/email_processor/package/ (untracked, local-only;
|
||||
deletion is Adam's call — with the exclude in place it is hash-neutral).
|
||||
Do NOT touch requirements.txt contents (Phase 7 scope).
|
||||
9. AWS access is READ-ONLY (get-function, downloading the deployed zip via
|
||||
its presigned URL). NEVER cdk deploy, never invoke, never mutate.
|
||||
`
|
||||
|
||||
const PREAMBLE = `
|
||||
You are one of several agents building refactor Phase 2 in the git repo at
|
||||
${REPO} on branch ${BRANCH} (already checked out — do NOT switch branches,
|
||||
do NOT create branches, do NOT commit, NEVER push).
|
||||
Authoritative spec: docs/refactor-evaluation.md, section "Phase 2".
|
||||
Work ONLY in the files you are told you own; other agents are concurrently
|
||||
editing other files in this same working tree.
|
||||
${CONSTRAINTS}
|
||||
Your final message is consumed by an orchestrator script, not a human —
|
||||
return only the structured data requested.
|
||||
`
|
||||
|
||||
// ------------------------------------------------------------------ schemas
|
||||
|
||||
const RECON = {
|
||||
type: 'object',
|
||||
required: ['summary', 'facts'],
|
||||
properties: {
|
||||
summary: { type: 'string' },
|
||||
facts: { type: 'array', items: { type: 'string' } },
|
||||
blockers: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const SPEC = {
|
||||
type: 'object',
|
||||
required: ['poBundling', 'woBundling', 'plainAssetEdits', 'astTestChanges', 'parityRules', 'notes'],
|
||||
properties: {
|
||||
poBundling: { type: 'string', description: 'the complete new po_stack.py from_asset block: asset path, full command string, exclude list — exact code' },
|
||||
woBundling: { type: 'string', description: 'same for wo_stack.py' },
|
||||
plainAssetEdits: { type: 'string', description: 'the three plain from_asset calls: current file:line + exact exclude addition each' },
|
||||
astTestChanges: { type: 'string', description: 'exactly how test_bundle_consistency.py recognizes the new scoped-glob shapes without losing revert detection; which assertions/regexes change and to what' },
|
||||
parityRules: { type: 'string', description: 'the staged-asset vs deployed-zip comparison rules: strict first-party .py set equality for PO; WO expected-shrinkage list + runtime-module retention; how dependency version drift is tolerated' },
|
||||
notes: { type: 'string' },
|
||||
},
|
||||
}
|
||||
|
||||
const IMPL = {
|
||||
type: 'object',
|
||||
required: ['filesChanged', 'summary', 'checksRun'],
|
||||
properties: {
|
||||
filesChanged: { type: 'array', items: { type: 'string' } },
|
||||
summary: { type: 'string' },
|
||||
checksRun: { type: 'string' },
|
||||
blockers: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const CHECKS = {
|
||||
type: 'object',
|
||||
required: ['passed', 'details'],
|
||||
properties: {
|
||||
passed: { type: 'boolean' },
|
||||
details: { type: 'string' },
|
||||
scopeViolations: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const PARITY = {
|
||||
type: 'object',
|
||||
required: ['passed', 'poVerdict', 'woVerdict', 'details'],
|
||||
properties: {
|
||||
passed: { type: 'boolean' },
|
||||
poVerdict: { type: 'string', description: 'PO staged vs deployed: identical first-party set? full evidence' },
|
||||
woVerdict: { type: 'string', description: 'WO: runtime modules retained + exact shrinkage list' },
|
||||
determinism: { type: 'string', description: 'repeat-synth + injected-__pycache__ hash results' },
|
||||
details: { type: 'string' },
|
||||
},
|
||||
}
|
||||
|
||||
const FINDINGS = {
|
||||
type: 'object',
|
||||
required: ['findings'],
|
||||
properties: {
|
||||
findings: {
|
||||
type: 'array',
|
||||
items: {
|
||||
type: 'object',
|
||||
required: ['title', 'severity', 'confirmed', 'evidence', 'fix'],
|
||||
properties: {
|
||||
title: { type: 'string' },
|
||||
severity: { enum: ['critical', 'high', 'medium', 'low'] },
|
||||
confirmed: { type: 'boolean' },
|
||||
evidence: { type: 'string' },
|
||||
fix: { type: 'string' },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------- setup
|
||||
|
||||
phase('Setup')
|
||||
const setup = await agent(`
|
||||
In ${REPO}:
|
||||
1. SEQUENCING GATE — Phases 0 AND 1 must be merged into ${BASE} (Phase 1
|
||||
also edits cdk/po_stack.py; building Phase 2 against a pre-Phase-1 stack
|
||||
file guarantees a conflict). git fetch origin, then verify on
|
||||
origin/${BASE}: (a) the healthcheck branch exists in both handlers and
|
||||
tests/test_bundle_consistency.py exists (Phase 0); (b) validate_ai_fallback
|
||||
exists in the PO pipeline and po_stack.py contains the
|
||||
ai-fallback-rejected alarm (Phase 1). If either is missing, STOP with a
|
||||
blocker naming the unmerged phase and do nothing else.
|
||||
2. Verify clean tree (untracked .coverage/.claude/ fine; other dirt = blocker,
|
||||
never stash or discard).
|
||||
3. git checkout ${BASE} && git pull --ff-only && git checkout -b ${BRANCH}
|
||||
4. gh pr list --state open --json number,title,headRefName
|
||||
Return: HEAD sha, gate evidence, open PRs, blockers.
|
||||
`, { label: 'setup:branch', model: 'haiku', schema: RECON })
|
||||
|
||||
if (!setup || (setup.blockers && setup.blockers.length)) {
|
||||
return { aborted: 'setup blockers', blockers: setup ? setup.blockers : ['setup agent died'], facts: setup ? setup.facts : [] }
|
||||
}
|
||||
log(`Branch ${BRANCH} ready off ${BASE}. ${setup.summary}`)
|
||||
|
||||
// ------------------------------------------------------------------- recon
|
||||
|
||||
phase('Recon')
|
||||
const recon = await parallel([
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of ALL FIVE Code.from_asset sites in cdk/po_stack.py and
|
||||
cdk/wo_stack.py: for each, quote verbatim with current file:line — the asset
|
||||
path, full bundling command (if bundled) or plain form, and any existing
|
||||
exclude. Also: both email_processor requirements.txt paths + contents (the
|
||||
pip -r path must be rewritten); the exact set of top-level .py files in
|
||||
lambdas/po/email_processor and lambdas/wo/email_processor (non-recursive);
|
||||
every subdirectory of each (tests/, package/, __pycache__ presence); and
|
||||
whether lambdas/ contains anything else a widened ../lambdas asset root
|
||||
would stage (shared/ existing yet? stray files at lambdas/ top level?).
|
||||
15-25 precise facts.`,
|
||||
{ label: 'recon:asset-sites', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only AWS recon (region us-east-1, READ-ONLY): for po-email-processor
|
||||
and workorder-email-processor run aws lambda get-function, download each
|
||||
Code.Location presigned zip to a scratch dir, and produce the COMPLETE file
|
||||
list of each deployed zip (unzip -l), separating (a) first-party top-level
|
||||
.py files, (b) pip-installed dependency dirs (name + version from
|
||||
.dist-info), (c) everything else (tests/, fixtures, __pycache__,
|
||||
requirements.txt — expected in the WO zip today). Also record each
|
||||
function's CodeSha256. This is the parity baseline the new bundles are
|
||||
judged against. Return the categorized lists as facts.`,
|
||||
{ label: 'recon:deployed-zips', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of tests/test_bundle_consistency.py: quote the exact
|
||||
regexes/assertions that will change — the PO executed-glob pin, the WO
|
||||
recursive-copy pin, _bundling_ships_all's two unconditionally-safe shapes,
|
||||
_extract_bundling_command's exactly-one-command demand (both stacks still
|
||||
have exactly one bundled function after Phase 2 — confirm), the
|
||||
PO_EXPECTED_TOP_LEVEL_MODULES pin, and the mutation test. State which
|
||||
assertions fail red against the Phase 2 command shapes (expected: PO glob
|
||||
pin and WO cp -r pin both fail). 8-15 facts.`,
|
||||
{ label: 'recon:ast-test', model: 'haiku', phase: 'Recon', schema: RECON }),
|
||||
])
|
||||
|
||||
const reconOk = recon.filter(Boolean)
|
||||
const pack = reconOk.map(r => `## ${r.summary}\n${r.facts.join('\n')}`).join('\n\n')
|
||||
const reconBlockers = reconOk.flatMap(r => r.blockers || [])
|
||||
log(`Recon complete: ${reconOk.length}/3 mappers, ${reconBlockers.length} blockers`)
|
||||
|
||||
// -------------------------------------------------------------------- spec
|
||||
|
||||
phase('Spec')
|
||||
const spec = await agent(`${PREAMBLE}
|
||||
You are the SPEC agent — pin every exact string before parallel
|
||||
implementation. Using the recon pack and your own reads, produce:
|
||||
- poBundling / woBundling: the complete replacement from_asset blocks as
|
||||
exact code — asset path "../lambdas", full bash -c command (pip line with
|
||||
rewritten -r path and the preserved manylinux2014_aarch64 pin, then the
|
||||
scoped non-recursive glob cp), exclude list per constraint 3. Mind the
|
||||
bundling cwd semantics: the container mounts the ASSET ROOT (../lambdas)
|
||||
as the working dir, so all paths are relative to lambdas/.
|
||||
- plainAssetEdits: the three plain from_asset calls with exact exclude
|
||||
additions.
|
||||
- astTestChanges: precise edits to test_bundle_consistency.py — the new
|
||||
scoped-glob regex (must match 'cp po/email_processor/*.py /asset-output/'
|
||||
as executed, still comment-strip-proof, still reject narrowed or
|
||||
commented-out variants), what replaces the WO cp -r pin, and confirmation
|
||||
the mutation test + exact-set pin survive unchanged in spirit.
|
||||
- parityRules: exactly how Verify judges the new bundles against the
|
||||
deployed-zip baseline from recon: PO = first-party top-level .py set must
|
||||
be IDENTICAL; dependency packages compared by NAME (version drift from the
|
||||
floor-pinned boto3 is tolerated and noted, not failed); nothing new may
|
||||
appear. WO = every first-party module in the CURRENT deployed zip that the
|
||||
handler imports (cross-check the AST sibling list) must be retained;
|
||||
expected drop list = tests/ + fixtures + __pycache__ + requirements.txt
|
||||
and NOTHING else may silently vanish; nothing new may appear.
|
||||
Recon pack:\n${pack}`,
|
||||
{ label: 'spec:pin-strings', model: 'opus', phase: 'Spec', schema: SPEC })
|
||||
|
||||
if (!spec) return { aborted: 'spec agent died — rerun workflow', reconBlockers }
|
||||
const specBlock = `BINDING SPEC (implement EXACTLY this):\n${JSON.stringify(spec, null, 2)}`
|
||||
log('Spec pinned: bundling commands, excludes, AST-test edits, parity rules')
|
||||
|
||||
// --------------------------------------------------------------- implement
|
||||
|
||||
phase('Implement')
|
||||
const impl = await parallel([
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: cdk/po_stack.py ONLY. Apply spec.poBundling (email processor
|
||||
from_asset: root, command, exclude) and the po web_ui + site_extractor
|
||||
exclude additions from spec.plainAssetEdits. Touch NOTHING else in the file
|
||||
(alarms, IAM, tables are all off-limits). Preserve/adapt the bundling
|
||||
warning comment so it stays true.
|
||||
Run before returning: ruff check cdk && cd cdk && npx cdk synth po-ingest -q
|
||||
(this runs Docker bundling — confirm the staged asset in cdk.out contains
|
||||
exactly the expected files and note the asset hash in your summary).
|
||||
${specBlock}`,
|
||||
{ label: 'impl:po-stack', model: 'sonnet', phase: 'Implement', schema: IMPL }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: cdk/wo_stack.py ONLY. Apply spec.woBundling and the wo web_ui
|
||||
exclude from spec.plainAssetEdits. Touch nothing else.
|
||||
Run before returning: ruff check cdk && cd cdk && npx cdk synth
|
||||
workorder-ingest -q (artifact-id selector, NOT stack_name) — confirm staged
|
||||
asset contents + hash in your summary.
|
||||
${specBlock}`,
|
||||
{ label: 'impl:wo-stack', model: 'sonnet', phase: 'Implement', schema: IMPL }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: tests/test_bundle_consistency.py and README.md ONLY.
|
||||
Task A: apply spec.astTestChanges. The test must PASS against the new stack
|
||||
files and still FAIL against: a reverted filename allowlist missing a
|
||||
sibling, a commented-out glob, and a narrowed glob (add/adjust the mutation
|
||||
tests to cover the new shapes — e.g. 'cp po/email_processor/handler.py'
|
||||
alone must not satisfy the scoped-glob pin).
|
||||
Task B: README — update the Deploy-Pipeline Guards bundling paragraph and
|
||||
the CI/CD + repo-layout sections for the widened ../lambdas asset root;
|
||||
document the deliberate WO prod-zip shrinkage (what dropped and why that is
|
||||
cleanup, per constraint 4) and the exclude rationale (from_asset ignores
|
||||
.gitignore; package/ hash poisoning).
|
||||
Run before returning: pytest tests/test_bundle_consistency.py -q --no-cov
|
||||
(must be green against the OTHER agents' stack edits — if they have not
|
||||
landed yet, poll by re-running up to ~10 min before reporting a blocker),
|
||||
ruff check tests.
|
||||
${specBlock}`,
|
||||
{ label: 'impl:ast-test-readme', model: 'sonnet', phase: 'Implement', schema: IMPL }),
|
||||
])
|
||||
|
||||
const implOk = impl.filter(Boolean)
|
||||
const implBlockers = implOk.flatMap(r => r.blockers || [])
|
||||
log(`Implement complete: ${implOk.length}/3 agents, blockers: ${implBlockers.length}`)
|
||||
|
||||
// ---------------------------------------------------- verify + fix loop
|
||||
|
||||
const EXPECTED_SCOPE = [
|
||||
'cdk/po_stack.py',
|
||||
'cdk/wo_stack.py',
|
||||
'tests/test_bundle_consistency.py',
|
||||
'README.md',
|
||||
]
|
||||
|
||||
const mechanicalPrompt = `${PREAMBLE}
|
||||
Independent re-verification — trust nothing self-reported. Run ALL gates,
|
||||
quoting failures verbatim:
|
||||
1. pytest -q --no-cov (repo root)
|
||||
2. ruff check . && ruff format --check .
|
||||
3. cd cdk && npx cdk synth po-ingest -q && npx cdk synth workorder-ingest -q
|
||||
4. cd cdk && npx cdk diff po-ingest ; npx cdk diff workorder-ingest —
|
||||
the ONLY resource deltas allowed are the two email-processor functions'
|
||||
Code/S3Key (asset hash) changes + CDK metadata. Any alarm/IAM/env/config/
|
||||
logical-ID delta = FAIL (constraint 7). Paste the diff summaries.
|
||||
5. ZERO-CODE-MOVE invariant: git diff ${BASE}...HEAD -- lambdas/ must output
|
||||
NOTHING.
|
||||
6. git status scope: every change under ${EXPECTED_SCOPE.join(', ')} only
|
||||
(untracked .coverage/.claude/ tolerated).
|
||||
passed=true only if all green. YOU MAY NOT edit files.`
|
||||
|
||||
const parityPrompt = `${PREAMBLE}
|
||||
You are the ARTIFACT-PARITY verifier — the load-bearing gate of this phase.
|
||||
Everything is local synth + read-only AWS.
|
||||
1. cd cdk && npx cdk synth po-ingest -q -o /tmp/phase2-synth && npx cdk
|
||||
synth workorder-ingest -q -o /tmp/phase2-synth. Locate each email
|
||||
processor's staged bundled asset dir in /tmp/phase2-synth (the asset.*
|
||||
dir containing handler.py).
|
||||
2. Re-download both deployed zips (aws lambda get-function Code.Location,
|
||||
region us-east-1) fresh — do not trust a recon cache.
|
||||
3. Judge per the spec parityRules: PO first-party top-level .py set staged
|
||||
vs deployed IDENTICAL (list both sets); dependency packages by name with
|
||||
version drift noted; NOTHING new. WO: every AST-derived handler sibling
|
||||
retained; the drop list is EXACTLY tests//fixtures/__pycache__/
|
||||
requirements.txt-class files — enumerate every dropped path class and
|
||||
every added path; anything outside the expected classes = FAIL.
|
||||
4. DETERMINISM: run the po-ingest synth twice into two fresh -o dirs —
|
||||
asset hashes must be identical. Then create a throwaway
|
||||
__pycache__/junk.pyc under lambdas/po/web_ui/ AND a dummy file under
|
||||
lambdas/po/email_processor/package/ (create the dir if absent, remember
|
||||
to DELETE everything you created afterwards), re-synth, and confirm NO
|
||||
asset hash changed (proves the excludes + the package/ hash-poisoning
|
||||
fix actually work). Report before/after hashes.
|
||||
5. Sanity: the staged PO asset must NOT contain web_ui/site_extractor
|
||||
sources, tests/, package/, or any .eml — the widened root stages more
|
||||
context but the cp glob + excludes must keep the OUTPUT clean.
|
||||
passed=true only if every check holds.`
|
||||
|
||||
const lenses = [
|
||||
{ key: 'bundling-semantics', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — bundling-semantics lens. Read the full cdk diff
|
||||
(git diff ${BASE}) plus aws-cdk-lib's documented from_asset/BundlingOptions
|
||||
semantics and try to REFUTE correctness: (1) is the bundling container cwd
|
||||
really the widened asset root, making 'pip install -r
|
||||
po/email_processor/requirements.txt' and 'cp po/email_processor/*.py'
|
||||
resolve correctly — or does an image workdir default break it? (2) do the
|
||||
exclude patterns ('**/__pycache__/**' etc.) apply to ASSET STAGING (hash
|
||||
input) and not merely the docker mount — i.e. does the package/ exclude
|
||||
actually stop local-vs-CI hash divergence? (3) does exclude affect what the
|
||||
bundling container can SEE, and could excluding tests/ break the pip
|
||||
install or cp step? (4) non-recursive scoped glob: could bash glob
|
||||
expansion inside the container (sh vs bash, nullglob) change behavior vs
|
||||
the Phase 0 top-level glob? (5) does widening the asset root change the
|
||||
ASSET HASH INPUTS such that unrelated wo/ file edits now redeploy the PO
|
||||
function (and vice versa) — if so, state the blast radius plainly so it is
|
||||
documented, not discovered. confirmed=true only with concrete evidence
|
||||
(CDK docs/source or a reproduced synth).` },
|
||||
{ key: 'guard-integrity', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — guard-integrity lens. The Phase 0 guards must come
|
||||
through Phase 2 with their teeth intact. (1) Attack the updated
|
||||
test_bundle_consistency.py: does the new scoped-glob regex accept a
|
||||
commented-out glob, a narrowed single-file cp, a glob for the WRONG
|
||||
pipeline dir (cp wo/email_processor/*.py in po_stack), or a cp missing
|
||||
/asset-output? Does the WO assertion still reject a narrowed recursive
|
||||
copy? Run the test against hand-mutated command strings to prove each
|
||||
rejection (scratch copies, not repo edits). (2) Does
|
||||
PO_EXPECTED_TOP_LEVEL_MODULES still bound what ships (the glob is now
|
||||
scoped — is the pin still checking the right directory)? (3) The smoke
|
||||
script + healthcheck are untouched by this diff — confirm zero diff to
|
||||
scripts/ and lambdas/. (4) README claims about bundling must match the new
|
||||
reality — no stale Phase 0 text contradicting the widened root.
|
||||
confirmed=true only with file:line evidence.` },
|
||||
]
|
||||
|
||||
let round = 0
|
||||
let checks = null
|
||||
let parity = null
|
||||
let confirmed = []
|
||||
while (round < 3) {
|
||||
phase('Verify')
|
||||
const results = await parallel([
|
||||
() => agent(mechanicalPrompt, { label: `verify:mechanical-r${round}`, model: 'sonnet', phase: 'Verify', schema: CHECKS }),
|
||||
() => agent(parityPrompt, { label: `verify:parity-r${round}`, model: 'opus', phase: 'Verify', schema: PARITY }),
|
||||
...lenses.map(l => () =>
|
||||
agent(l.prompt, { label: `verify:${l.key}-r${round}`, phase: 'Verify', schema: FINDINGS })),
|
||||
])
|
||||
checks = results[0]
|
||||
parity = results[1]
|
||||
confirmed = results.slice(2).filter(Boolean)
|
||||
.flatMap(r => r.findings || [])
|
||||
.filter(f => f.confirmed && f.severity !== 'low')
|
||||
const green = checks && checks.passed && parity && parity.passed
|
||||
log(`Verify round ${round}: mechanical ${checks && checks.passed ? 'GREEN' : 'RED'}, parity ${parity && parity.passed ? 'GREEN' : 'RED'}, confirmed findings: ${confirmed.length}`)
|
||||
if (green && confirmed.length === 0) break
|
||||
|
||||
round += 1
|
||||
if (round >= 3) break
|
||||
phase('Fix')
|
||||
await agent(`${PREAMBLE}
|
||||
You are the fix agent — you may edit files under: ${EXPECTED_SCOPE.join(', ')}.
|
||||
Fix EVERY item minimally; the binding spec and 9 pinned constraints hold (a
|
||||
finding that conflicts with a constraint is reported, not "fixed"). Re-run
|
||||
the specific failing gate per fix.
|
||||
MECHANICAL:\n${checks ? checks.details : '(agent died — rerun all)'}
|
||||
PARITY:\n${parity ? parity.details : '(agent died — rerun all)'}
|
||||
CONFIRMED FINDINGS:\n${JSON.stringify(confirmed, null, 2)}
|
||||
${specBlock}`,
|
||||
{ label: `fix:round-${round}`, model: 'opus', phase: 'Fix', schema: IMPL })
|
||||
}
|
||||
|
||||
const verifyClean = checks && checks.passed && parity && parity.passed && confirmed.length === 0
|
||||
if (!verifyClean) {
|
||||
return {
|
||||
status: 'NEEDS ATTENTION — verify not clean after 3 rounds; branch left uncommitted',
|
||||
branch: BRANCH,
|
||||
mechanical: checks,
|
||||
parity,
|
||||
unresolvedFindings: confirmed,
|
||||
implBlockers,
|
||||
reconBlockers,
|
||||
}
|
||||
}
|
||||
|
||||
// ----------------------------------------------------------------- package
|
||||
|
||||
phase('Package')
|
||||
const commit = await agent(`${PREAMBLE.replace('do NOT commit, ', '')}
|
||||
YOU are the commit agent:
|
||||
1. Read ~/Documents/repositories/seahaven/engineering-handbook/commit-messages.md.
|
||||
2. git add only: ${EXPECTED_SCOPE.join(', ')} and
|
||||
.claude/workflows/phase-2-bundling-root.js. NOT .coverage. Verify staged
|
||||
set with git status.
|
||||
3. ONE commit via git commit -F /tmp/phase2-commit-msg.txt (write the message
|
||||
file first; backticks in -m get eaten by zsh). Suggested subject:
|
||||
"feat: widen email-processor asset roots to lambdas/ with scoped globs + excludes (refactor phase 2)"
|
||||
Body: why (shared/ reachability for Phase 3), the WO shrinkage list, the
|
||||
package/ hash-poisoning exclude, parity evidence one-liner.
|
||||
NO AI attribution / Co-Authored-By lines.
|
||||
4. Do NOT push. Return commit sha + shortstat.`,
|
||||
{ label: 'package:commit', model: 'sonnet', phase: 'Package', schema: IMPL })
|
||||
|
||||
return {
|
||||
status: 'BUILT — committed locally, NOT pushed',
|
||||
branch: BRANCH,
|
||||
base: BASE,
|
||||
commit: commit ? commit.summary : 'commit agent died — commit manually',
|
||||
parityEvidence: parity ? { po: parity.poVerdict, wo: parity.woVerdict, determinism: parity.determinism } : null,
|
||||
implementation: implOk.map(r => r.summary),
|
||||
filesChanged: implOk.flatMap(r => r.filesChanged),
|
||||
verifyRounds: round + 1,
|
||||
blockers: implBlockers.concat(reconBlockers),
|
||||
outstandingGates: [
|
||||
'push + PR + gh pr checks green (no /sh-security-review required — no untrusted-input/auth/IAM surface; pre-push scanners still run; cross-family review not required — no IAM or handler-signature change)',
|
||||
'deploy-then-merge: deploy from branch, then the LIVE gate — aws lambda get-function zip file-list diff (PO first-party set identical; WO shrinkage exactly as documented), smoke green, one real PO + WO email each with ParseMethod=template, alarms green, THEN merge',
|
||||
'optional cleanup for Adam (hash-neutral once excludes are deployed): delete the untracked 44 MB lambdas/po/email_processor/package/ dir (doc Phase 7 item, endorsed to do with/after Phase 2)',
|
||||
],
|
||||
}
|
||||
|
|
@ -1,679 +0,0 @@
|
|||
export const meta = {
|
||||
name: 'phase-3-shared-extraction',
|
||||
description: 'Phase 3 of the procurement-ingest refactor (docs/refactor-evaluation.md): extract lambdas/shared/ — ses_auth.py (byte-identical move, zero handler diff), web_ui_auth.py (byte-identical auth block from both web_ui handlers), email_parsing.py (parse_raw_email superset, cc unconditional), emf.py (parameterized emitter preserving every envelope byte-for-byte). Bundling gains cp shared/*.py in both email-processor commands + the same staging mechanism for both web_ui functions. Requires Phases 0-2 on the base branch. Auth code moves, so push is gated on /sh-security-review in the main loop. Committed locally, never pushed.',
|
||||
phases: [
|
||||
{ title: 'Setup', detail: 'verify Phases 0+1+2 on base, branch feature/phase-3-shared-extraction', model: 'haiku' },
|
||||
{ title: 'Recon', detail: '4 mappers: the four duplicated modules, post-Phase-2 bundling sites, test-loader plumbing, deployed-zip baseline (read-only AWS)' },
|
||||
{ title: 'Spec', detail: 'serial fable spec: pin shared-module contents, handler edit lists, web_ui staging, bundling strings, EMF design, test plumbing' },
|
||||
{ title: 'Implement', detail: 'opus: shared/ + four handlers; sonnet: both CDK stacks; opus: all test plumbing + README — disjoint files', model: 'opus' },
|
||||
{ title: 'Verify', detail: 'mechanical gates + bundle-parity verifier + 3 fable lenses (auth integrity, EMF/telemetry, loader integrity)' },
|
||||
{ title: 'Fix', detail: 'opus fixer, full re-verify, max 3 rounds', model: 'opus' },
|
||||
{ title: 'Package', detail: 'single commit via -F (no push)', model: 'sonnet' },
|
||||
],
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------- constants
|
||||
|
||||
const REPO = '/Users/adammoussa/Documents/repositories/seahaven/procurement-ingest'
|
||||
const BRANCH = 'feature/phase-3-shared-extraction'
|
||||
let _args = args
|
||||
if (typeof _args === 'string') {
|
||||
try { _args = JSON.parse(_args) } catch (e) { _args = null }
|
||||
}
|
||||
const BASE = (_args && _args.base) || 'main'
|
||||
|
||||
const CONSTRAINTS = `
|
||||
PINNED BEHAVIORAL CONSTRAINTS (docs/refactor-evaluation.md Phase 3 — violating any is a build failure):
|
||||
1. THE MOVE SET IS EXACTLY FOUR MODULES, in this order of dependency risk:
|
||||
lambdas/shared/ses_auth.py, lambdas/shared/web_ui_auth.py,
|
||||
lambdas/shared/email_parsing.py, lambdas/shared/emf.py. Nothing else
|
||||
moves into shared/. lambdas/shared/ is the handbook location
|
||||
(cdk-project-layout.md); modules land FLAT in every bundle so bare-name
|
||||
imports keep working.
|
||||
2. ses_auth: FIRST verify the two current copies are still byte-identical
|
||||
(sha256 both against the ${BASE} versions — any drift since the audit is
|
||||
a blocker, not something to silently reconcile). shared/ses_auth.py is
|
||||
the EXACT bytes of that single copy; both originals are git rm'd. The
|
||||
email-processor handlers keep 'from ses_auth import
|
||||
authenticate_inbound_email' UNCHANGED — flat landing in /asset-output
|
||||
means ZERO handler diff for this move, which is what keeps fail-closed
|
||||
auth byte-identical through the change.
|
||||
3. web_ui_auth: extract exactly the byte-identical block — _get_auth_token /
|
||||
_header / is_authenticated + the four cache globals — from BOTH web_ui
|
||||
handlers. The per-stack INFRA-74 comments STAY in each handler (their
|
||||
wording has drifted deliberately; they are stack-specific — do NOT unify
|
||||
or move them into the shared module). Fail-closed semantics (unset ARN,
|
||||
Secrets Manager exception -> deny) must be unchanged; the token-cache
|
||||
globals move with the functions that read them.
|
||||
4. email_parsing.py: parse_raw_email as the SUPERSET version returning cc
|
||||
unconditionally. WO's output is bit-identical to today; PO simply
|
||||
ignores cc — do NOT "clean up" PO to consume it, and do NOT preserve two
|
||||
variants.
|
||||
5. emf.py: a generic emitter parameterized by namespace / dimension-sets /
|
||||
properties. Every call site's emitted EMF envelope must be EXACTLY what
|
||||
it emits today — the dimension-set list
|
||||
[["ParseMethod"],["ParseMethod","TemplateId"]] is load-bearing for the
|
||||
alarms and metric filters; making one-sided dimension fixes impossible
|
||||
is the point of this move. Emission ORDERING is untouchable: PO emits
|
||||
ai_fallback BEFORE the Bedrock call, WO after its gate with mutually-
|
||||
exclusive ai_fallback/ai_fallback_rejected — these two deliberate
|
||||
per-pipeline differences are pinned by tests; converting a call site
|
||||
must not move it. The deliberate-double-count comments survive.
|
||||
6. DERIVED-FIELDS EXCEPTION: if recon finds _emit_derived_agreement_metric
|
||||
lives INSIDE derived_fields.py, do NOT convert it — derived_fields.py
|
||||
and the shadow DerivedFieldAgreement telemetry are UNTOUCHABLE while the
|
||||
bake runs (this outranks the emf consolidation). Leave it as a third
|
||||
copy with a code comment pointing at shared/emf.py and report it in
|
||||
notes/blockers. Only convert it if it lives outside derived_fields.py.
|
||||
7. UNTOUCHABLE FILES (git diff ${BASE}...HEAD must be empty for each):
|
||||
both template_parser.py (990 vs 508 lines, genuinely divergent — stays
|
||||
per-pipeline), derived_fields.py, both validate_ai_fallback gate
|
||||
modules, extract_with_claude's Bedrock invocation/prompt logic. Handler
|
||||
diffs are LIMITED to: deleting moved code, import changes, and
|
||||
emitter-call swaps per the binding spec. No opportunistic refactors.
|
||||
8. Bundling (cdk): append 'cp shared/*.py /asset-output/' to BOTH
|
||||
email-processor bundling commands (Phase 2 made the bundling cwd the
|
||||
../lambdas asset root, so the path resolves as written).
|
||||
BASE-AWARENESS — READ THE ACTUAL cdk FILES ON THE BASE, DO NOT ASSUME:
|
||||
this phase is stacked on the Phase 7 branch, which ALREADY removed the
|
||||
pip install step from both email-processor commands (they are now
|
||||
CP-ONLY: no pip line, no manylinux pin, because nothing third-party is
|
||||
installed). Phase 3 moves only pure first-party modules (no new deps),
|
||||
so cp-only STAYS cp-only — you simply add another 'cp shared/*.py
|
||||
/asset-output/' line. DO NOT re-introduce a pip install step and DO NOT
|
||||
re-add the manylinux pin: there is nothing to pin when nothing installs,
|
||||
and adding a pip step back would be the regression here. (The PR #34
|
||||
lesson — never drop the manylinux pin while a pip install runs — still
|
||||
holds ONLY if recon finds a pip step actually present on the base; on
|
||||
the cp-only Phase 7 base there is none.) PRESERVE the Phase 2 exclude
|
||||
lists exactly. Both web_ui functions gain the SAME staging mechanism
|
||||
(widened-root bundled from_asset) so web_ui_auth.py ships beside their
|
||||
handler — the spec agent pins the exact form. site_extractor's
|
||||
from_asset is UNTOUCHED (Phase 6 territory).
|
||||
9. tests/test_bundle_consistency.py is updated IN THE SAME CHANGE without
|
||||
losing teeth: the PO_EXPECTED_TOP_LEVEL_MODULES exact-set pin gains the
|
||||
shared modules that now ship; the AST sibling-import check must resolve
|
||||
imports whose source file now lives under shared/; the new shared cp
|
||||
line gets its own revert/mutation detection (a commented-out
|
||||
'cp shared/*.py' must fail the test).
|
||||
10. Test plumbing in the same PR: update _SIBLING_MODULES resolution and
|
||||
_po_parser_support.py (~line 71 — verify the current line) so tests
|
||||
load ses_auth/email_parsing/emf from shared/; retire or repoint the
|
||||
fixture-hygiene test that polices the two ses_auth copies for
|
||||
byte-identity (obsolete once there is one copy — do not leave it
|
||||
failing); drop the ses_auth fixture params from test_ses_auth
|
||||
(parameterizing over two identical copies is dead weight — halves the
|
||||
run). The sys.modules save/restore dance SURVIVES for template_parser
|
||||
(still a duplicated bare name) — do not delete it. Preserve the
|
||||
load-bearing moto-before-handler import ordering.
|
||||
11. STALE-SHADOW HAZARD: after the move, no stale ses_auth.py / .pyc /
|
||||
__pycache__ copy may remain anywhere it could shadow the shared copy —
|
||||
in the repo (git rm, don't empty), in staged assets, or on any test
|
||||
sys.path. Verify explicitly.
|
||||
12. cdk diff on BOTH stacks: the only resource deltas allowed are Code/
|
||||
S3Key (asset) changes on the two email processors and the two web_ui
|
||||
functions (+ CDK metadata). No logical-ID changes, no alarm, IAM,
|
||||
table, env, runtime, or handler-property deltas of any kind.
|
||||
13. AWS access is READ-ONLY (get-function, downloading deployed zips via
|
||||
presigned URLs). NEVER cdk deploy, never invoke, never mutate.
|
||||
`
|
||||
|
||||
const PREAMBLE = `
|
||||
You are one of several agents building refactor Phase 3 in the git repo at
|
||||
${REPO} on branch ${BRANCH} (already checked out — do NOT switch branches,
|
||||
do NOT create branches, do NOT commit, NEVER push, do NOT run cdk deploy or
|
||||
touch AWS resources beyond read-only calls).
|
||||
Authoritative spec: docs/refactor-evaluation.md, section "Phase 3".
|
||||
Work ONLY in the files you are told you own; other agents are concurrently
|
||||
editing other files in this same working tree.
|
||||
${CONSTRAINTS}
|
||||
Your final message is consumed by an orchestrator script, not a human —
|
||||
return only the structured data requested.
|
||||
`
|
||||
|
||||
// ------------------------------------------------------------------ schemas
|
||||
|
||||
const RECON = {
|
||||
type: 'object',
|
||||
required: ['summary', 'facts'],
|
||||
properties: {
|
||||
summary: { type: 'string' },
|
||||
facts: { type: 'array', items: { type: 'string' } },
|
||||
blockers: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const SPEC = {
|
||||
type: 'object',
|
||||
required: ['sharedModules', 'handlerEdits', 'webUiStaging', 'bundlingEdits', 'emfDesign', 'testPlumbing', 'parityRules', 'notes'],
|
||||
properties: {
|
||||
sharedModules: { type: 'string', description: 'per shared module: exact provenance (which copy is the source, sha256), full contents decision (verbatim move vs superset vs parameterized), and the public surface each importer uses' },
|
||||
handlerEdits: { type: 'string', description: 'per handler (po/wo email_processor, po/wo web_ui): the exact deletions, import lines, and emitter-call swaps — file:line, nothing else may change' },
|
||||
webUiStaging: { type: 'string', description: 'the complete new from_asset blocks for both web_ui functions: asset path, command or cp form, exclude list — exact code' },
|
||||
bundlingEdits: { type: 'string', description: 'the two email-processor bundling command strings with cp shared/*.py appended, verbatim, plus the expected top-level module set of each resulting bundle' },
|
||||
emfDesign: { type: 'string', description: 'shared/emf.py signature + per-call-site mapping proving each emitted envelope (namespace, dimension-set list, properties) is byte-equivalent to today; the derived-agreement emitter decision per constraint 6' },
|
||||
testPlumbing: { type: 'string', description: 'every test/support file change: loader resolution, _SIBLING_MODULES, fixture-hygiene retirement, test_ses_auth de-parameterization, test_bundle_consistency edits with their mutation-detection shapes' },
|
||||
parityRules: { type: 'string', description: 'how Verify judges staged bundles vs the deployed-zip baseline: expected first-party set per function (= deployed set + the new shared modules), ses_auth byte-identity requirement, expected removals (none beyond moved-file provenance), web_ui bundle expectations' },
|
||||
notes: { type: 'string' },
|
||||
},
|
||||
}
|
||||
|
||||
const IMPL = {
|
||||
type: 'object',
|
||||
required: ['filesChanged', 'summary', 'checksRun'],
|
||||
properties: {
|
||||
filesChanged: { type: 'array', items: { type: 'string' } },
|
||||
summary: { type: 'string' },
|
||||
checksRun: { type: 'string' },
|
||||
blockers: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const CHECKS = {
|
||||
type: 'object',
|
||||
required: ['passed', 'details'],
|
||||
properties: {
|
||||
passed: { type: 'boolean' },
|
||||
details: { type: 'string' },
|
||||
scopeViolations: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const PARITY = {
|
||||
type: 'object',
|
||||
required: ['passed', 'poVerdict', 'woVerdict', 'webUiVerdict', 'details'],
|
||||
properties: {
|
||||
passed: { type: 'boolean' },
|
||||
poVerdict: { type: 'string', description: 'PO email-processor staged vs deployed: module-set delta exactly as spec, ses_auth bytes identical — full evidence' },
|
||||
woVerdict: { type: 'string', description: 'same for WO email-processor' },
|
||||
webUiVerdict: { type: 'string', description: 'both web_ui staged bundles: own *.py + web_ui_auth.py present, nothing stray, hashes deterministic' },
|
||||
details: { type: 'string' },
|
||||
},
|
||||
}
|
||||
|
||||
const FINDINGS = {
|
||||
type: 'object',
|
||||
required: ['findings'],
|
||||
properties: {
|
||||
findings: {
|
||||
type: 'array',
|
||||
items: {
|
||||
type: 'object',
|
||||
required: ['title', 'severity', 'confirmed', 'evidence', 'fix'],
|
||||
properties: {
|
||||
title: { type: 'string' },
|
||||
severity: { enum: ['critical', 'high', 'medium', 'low'] },
|
||||
confirmed: { type: 'boolean' },
|
||||
evidence: { type: 'string' },
|
||||
fix: { type: 'string' },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------- setup
|
||||
|
||||
phase('Setup')
|
||||
const setup = await agent(`
|
||||
In ${REPO}:
|
||||
1. SEQUENCING GATE — Phases 0, 1 AND 2 must all be on ${BASE} (Phase 3
|
||||
edits the same stack files as Phase 2 and depends on its widened
|
||||
../lambdas asset roots to make shared/ reachable). git fetch origin,
|
||||
then pick the base ref: origin/${BASE} if that remote ref exists,
|
||||
otherwise the local branch ${BASE} (a stacked local-only base is
|
||||
expected and fine). Verify on the base ref:
|
||||
(a) Phase 0: tests/test_bundle_consistency.py exists
|
||||
(git show <baseref>:tests/test_bundle_consistency.py | head -3);
|
||||
(b) Phase 1: validate_ai_fallback exists in the PO pipeline
|
||||
(git grep validate_ai_fallback <baseref> -- lambdas/po);
|
||||
(c) Phase 2: BOTH cdk/po_stack.py and cdk/wo_stack.py on the base ref
|
||||
contain Code.from_asset("../lambdas") for the email processors
|
||||
(git show <baseref>:cdk/po_stack.py | grep -n '\\.\\./lambdas', same
|
||||
for wo_stack.py).
|
||||
If any is missing, STOP with a blocker naming the unmet phase and do
|
||||
nothing else.
|
||||
2. Verify clean working tree (untracked .coverage / .claude/ / the local
|
||||
44 MB lambdas/po/email_processor/package/ dir are fine; any OTHER dirt =
|
||||
blocker, never stash or discard).
|
||||
3. git checkout ${BASE}; then git pull --ff-only ONLY if the branch has an
|
||||
upstream (a local-only base skips the pull — not a blocker); then
|
||||
git checkout -b ${BRANCH}
|
||||
4. gh pr list --state open --json number,title,headRefName (overlap check).
|
||||
Return facts: HEAD sha, per-phase gate evidence, open PRs, blockers.
|
||||
`, { label: 'setup:branch', model: 'haiku', schema: RECON })
|
||||
|
||||
if (!setup || (setup.blockers && setup.blockers.length)) {
|
||||
return { aborted: 'setup blockers', blockers: setup ? setup.blockers : ['setup agent died'], facts: setup ? setup.facts : [] }
|
||||
}
|
||||
log(`Branch ${BRANCH} ready off ${BASE}. ${setup.summary}`)
|
||||
|
||||
// ------------------------------------------------------------------- recon
|
||||
|
||||
phase('Recon')
|
||||
const recon = await parallel([
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of the FOUR duplicated surfaces being extracted:
|
||||
1. ses_auth.py both copies — sha256 of each (MUST match; drift = blocker),
|
||||
line count, the exact import line each email-processor handler uses,
|
||||
any other importer (git grep 'import ses_auth\\|from ses_auth').
|
||||
2. web_ui auth block — in BOTH web_ui handlers quote with file:line the
|
||||
exact boundaries of the byte-identical block (_get_auth_token, _header,
|
||||
is_authenticated, the four cache globals), diff the two blocks to prove
|
||||
byte-identity, quote each INFRA-74 comment verbatim (they differ —
|
||||
that is expected), and note everything else in each handler that CALLS
|
||||
the block.
|
||||
3. parse_raw_email both copies — where each lives (own sibling file vs
|
||||
inside handler.py), the exact cc delta between them, every call site.
|
||||
4. The THREE EMF emitters — quote each verbatim with file:line (PO
|
||||
ParseMethod emitter, WO ParseMethod emitter,
|
||||
_emit_derived_agreement_metric), namespace + dimension-set list +
|
||||
properties of each, and CRITICALLY: which FILE _emit_derived_agreement_metric
|
||||
lives in (constraint 6 hinges on whether it is inside derived_fields.py).
|
||||
Also pin current line numbers of PO's pre-Bedrock ai_fallback emit and
|
||||
WO's post-gate emit.
|
||||
25-35 precise facts.`,
|
||||
{ label: 'recon:duplicated-modules', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of the post-Phase-2 CDK bundling state: for ALL FIVE
|
||||
Code.from_asset sites in cdk/po_stack.py and cdk/wo_stack.py quote verbatim
|
||||
with current file:line — asset path, full bundling command (or plain form),
|
||||
exclude list. For the two web_ui functions additionally record: runtime,
|
||||
architecture, handler property, memory/timeout, whether any requirements.txt
|
||||
exists for them, and every function property that must NOT change when
|
||||
bundling is added. Confirm lambdas/shared/ does not exist yet and list
|
||||
anything at lambdas/ top level. 15-25 facts.`,
|
||||
{ label: 'recon:cdk-bundling', model: 'haiku', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of the test plumbing this phase must rewire:
|
||||
- tests/conftest.py importlib loader: how it resolves module paths, the
|
||||
sys.modules save/restore, _SIBLING_MODULES (exact current contents).
|
||||
- _po_parser_support.py: the independent importlib reimplementation, the
|
||||
load-bearing moto-before-handler import order (~lines 26-33), and what
|
||||
is at line ~71 (the doc cites it — quote the current code).
|
||||
- _wo_parser_support.py bare sys.path 'import handler' strategy.
|
||||
- test_ses_auth.py at root: the fixture parameterization over both copies
|
||||
(quote it), total line count, the fixture-hygiene test that polices
|
||||
byte-identity between the two copies (name + assertion).
|
||||
- test_parse_raw_email.py: how it loads both handlers' parse_raw_email.
|
||||
- tests/test_bundle_consistency.py: every assertion that will fail red
|
||||
against the Phase 3 shapes (shared cp line, PO_EXPECTED_TOP_LEVEL_MODULES,
|
||||
AST sibling-import resolution for moved modules).
|
||||
20-30 facts.`,
|
||||
{ label: 'recon:test-plumbing', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only AWS recon (region us-east-1, READ-ONLY): for po-email-processor,
|
||||
workorder-email-processor, AND both web_ui functions (find their exact
|
||||
function names via the stacks/aws lambda list-functions) run aws lambda
|
||||
get-function; for the two email processors download each Code.Location
|
||||
presigned zip to a scratch dir and produce the COMPLETE file list
|
||||
(unzip -l) separated into (a) first-party top-level .py, (b) dependency
|
||||
dirs, (c) anything else; record every function's CodeSha256 and the
|
||||
sha256 of ses_auth.py inside each deployed zip (the byte-identity baseline
|
||||
the moved copy is judged against). For the web_ui functions the current
|
||||
zip file list is the baseline their new bundled asset must cover.
|
||||
Return the categorized lists as facts.`,
|
||||
{ label: 'recon:deployed-baseline', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
])
|
||||
|
||||
const reconOk = recon.filter(Boolean)
|
||||
const pack = reconOk.map(r => `## ${r.summary}\n${r.facts.join('\n')}`).join('\n\n')
|
||||
const reconBlockers = reconOk.flatMap(r => r.blockers || [])
|
||||
.filter(b => b && !/^\s*(none|n\/a)\b/i.test(b))
|
||||
log(`Recon complete: ${reconOk.length}/4 mappers, ${reconBlockers.length} blockers`)
|
||||
if (reconBlockers.length) {
|
||||
return { aborted: 'recon blockers (likely copy drift — resolve before extracting)', blockers: reconBlockers, reconPack: pack }
|
||||
}
|
||||
|
||||
// -------------------------------------------------------------------- spec
|
||||
|
||||
phase('Spec')
|
||||
const spec = await agent(`${PREAMBLE}
|
||||
You are the SPEC agent — the single authority that pins every contested
|
||||
decision BEFORE parallel implementation (parallel leaves cannot see each
|
||||
other's choices). Using the recon pack below plus your own reads of the
|
||||
actual files, produce the binding implementation spec:
|
||||
- sharedModules: per constraint 1's four modules — provenance, contents
|
||||
decision, public surface. ses_auth is a verbatim byte-move; web_ui_auth
|
||||
is the exact block; email_parsing is the WO superset (cc unconditional);
|
||||
emf is the parameterized emitter.
|
||||
- handlerEdits: for each of the four handlers, the exact minimal edit list
|
||||
(constraint 7 — deletions, imports, emitter-call swaps ONLY). State
|
||||
explicitly that the two email-processor ses_auth import lines are
|
||||
UNCHANGED.
|
||||
- webUiStaging: complete replacement from_asset blocks for both web_ui
|
||||
functions — widened root, cp command staging the function's own *.py
|
||||
plus web_ui_auth.py (pin whether to cp shared/*.py or just
|
||||
shared/web_ui_auth.py — pick ONE rule, state why), Phase-2-style
|
||||
excludes. Mind bundling cwd semantics: the container mounts the asset
|
||||
root (../lambdas) as the working dir. If a no-Docker staging form is
|
||||
viable and simpler, you may pin that instead — but ONE mechanism for
|
||||
both, exact code.
|
||||
- bundlingEdits: both email-processor command strings verbatim with
|
||||
'cp shared/*.py /asset-output/' appended, plus the exact expected
|
||||
top-level module set of each resulting bundle (this feeds
|
||||
PO_EXPECTED_TOP_LEVEL_MODULES and the parity gate).
|
||||
- emfDesign: the shared emitter signature and a per-call-site table
|
||||
proving envelope byte-equivalence; resolve the derived-agreement emitter
|
||||
per constraint 6 based on where recon found it.
|
||||
- testPlumbing: every file, every edit — loader resolution for shared/,
|
||||
_SIBLING_MODULES, _po_parser_support.py, _wo_parser_support.py if it
|
||||
needs the shared path, fixture-hygiene retirement, test_ses_auth
|
||||
de-parameterization, test_parse_raw_email (single implementation now —
|
||||
what does it exercise?), test_bundle_consistency edits including the new
|
||||
mutation shapes (commented-out shared cp must fail).
|
||||
- parityRules: exactly how Verify judges staged bundles vs recon's
|
||||
deployed baseline — per-function expected first-party set (deployed set
|
||||
minus nothing, plus the shared modules per your cp rule), ses_auth
|
||||
sha256 must equal the deployed zips' copy, web_ui bundles must cover
|
||||
their deployed file list plus web_ui_auth.py, nothing else may appear
|
||||
or vanish.
|
||||
Recon pack:\n${pack}`,
|
||||
{ label: 'spec:pin-extraction', phase: 'Spec', schema: SPEC })
|
||||
|
||||
if (!spec) return { aborted: 'spec agent died — rerun workflow', reconBlockers }
|
||||
const specBlock = `BINDING SPEC (from the spec agent — implement EXACTLY this):\n${JSON.stringify(spec, null, 2)}`
|
||||
log('Spec pinned: shared modules, handler edits, web_ui staging, bundling strings, EMF design, test plumbing')
|
||||
|
||||
// --------------------------------------------------------------- implement
|
||||
|
||||
phase('Implement')
|
||||
const impl = await parallel([
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: everything under lambdas/ EXCEPT the tests/ directories (another
|
||||
agent owns all test and support files). Do not touch cdk/ or README.
|
||||
Task: execute the four moves per spec.sharedModules + spec.handlerEdits +
|
||||
spec.emfDesign, in the spec's order:
|
||||
1. git mv (or create+git rm preserving exact bytes) ses_auth.py ->
|
||||
lambdas/shared/ses_auth.py; delete both originals; prove sha256
|
||||
equality in your summary. Handler import lines untouched.
|
||||
2. Create lambdas/shared/web_ui_auth.py from the byte-identical block;
|
||||
replace the block in BOTH web_ui handlers with the import; keep each
|
||||
INFRA-74 comment in place.
|
||||
3. Create lambdas/shared/email_parsing.py (superset); rewire both
|
||||
email-processor call sites.
|
||||
4. Create lambdas/shared/emf.py; swap the emitter call sites per
|
||||
spec.emfDesign — honoring constraint 6 (derived_fields.py stays
|
||||
untouched if the third emitter lives there) and constraint 5 (emission
|
||||
ordering does not move).
|
||||
Delete every now-empty moved-out file with git rm (constraint 11).
|
||||
Run before returning: ruff check lambdas && ruff format lambdas --check,
|
||||
plus an import smoke: python3 -c with sys.path prepended for
|
||||
lambdas/shared + each function dir, importing every touched module (tests
|
||||
are NOT yours to run — the plumbing agent lands them in parallel).
|
||||
${specBlock}`,
|
||||
{ label: 'impl:shared-lambdas', model: 'opus', phase: 'Implement', schema: IMPL }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: cdk/po_stack.py and cdk/wo_stack.py ONLY (and only the from_asset
|
||||
regions — alarms, IAM, tables, env are all off-limits).
|
||||
Task: apply spec.bundlingEdits (append the shared cp to both
|
||||
email-processor commands — the base is the Phase 7 CP-ONLY bundling, so
|
||||
just add another 'cp shared/*.py /asset-output/' line; DO NOT re-add a pip
|
||||
install step or a manylinux pin, there is nothing third-party to install
|
||||
(constraint 8); preserve the Phase 2 excludes verbatim) and
|
||||
spec.webUiStaging (both web_ui functions). Touch nothing else;
|
||||
site_extractor's from_asset stays byte-identical.
|
||||
Run before returning: ruff check cdk && cd cdk &&
|
||||
npx cdk synth po-ingest -q -o /tmp/phase3-synth &&
|
||||
npx cdk synth workorder-ingest -q -o /tmp/phase3-synth (artifact-id
|
||||
selectors, NOT stack_name). Docker bundling runs — confirm each staged
|
||||
email-processor asset contains the shared modules and each staged web_ui
|
||||
asset contains web_ui_auth.py; note asset hashes in your summary. If the
|
||||
lambdas/ moves have not landed yet the synth will fail on missing files —
|
||||
poll by re-running up to ~10 min before reporting a blocker.
|
||||
${specBlock}`,
|
||||
{ label: 'impl:cdk-stacks', model: 'sonnet', phase: 'Implement', schema: IMPL }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: all test and support files (tests/ at repo root including
|
||||
tests/test_bundle_consistency.py and tests/conftest.py,
|
||||
lambdas/po/email_processor/tests/, lambdas/wo/email_processor/tests/)
|
||||
and README.md ONLY.
|
||||
Task A: apply spec.testPlumbing in full — loader/_SIBLING_MODULES
|
||||
resolution for shared/, _po_parser_support.py edit (preserving the
|
||||
moto-before-handler ordering comment), fixture-hygiene retirement,
|
||||
test_ses_auth de-parameterization, test_parse_raw_email update,
|
||||
test_bundle_consistency updates WITHOUT losing teeth (constraint 9 — the
|
||||
new shared cp pin must reject a commented-out or narrowed variant; keep
|
||||
the existing mutation tests green).
|
||||
Task B: README — document lambdas/shared/ in the repo-layout section
|
||||
(which modules live there, the flat-landing import rule, the bundling cp
|
||||
that ships them), update the bundling/deploy-guards paragraphs for the
|
||||
shared cp + web_ui staging, and note that ses_auth is now single-sourced
|
||||
(one hardening fix lands once). Match existing README style.
|
||||
Run before returning: pytest -q --no-cov at repo root (must be green
|
||||
against the OTHER agents' edits — they land in parallel; poll by
|
||||
re-running up to ~10 min before reporting a blocker) and ruff check on
|
||||
every file you touched.
|
||||
${specBlock}`,
|
||||
{ label: 'impl:test-plumbing-readme', model: 'opus', phase: 'Implement', schema: IMPL }),
|
||||
])
|
||||
|
||||
const implOk = impl.filter(Boolean)
|
||||
const implBlockers = implOk.flatMap(r => r.blockers || [])
|
||||
log(`Implement complete: ${implOk.length}/3 agents, blockers: ${implBlockers.length}`)
|
||||
|
||||
// ---------------------------------------------------- verify + fix loop
|
||||
|
||||
const EXPECTED_SCOPE = [
|
||||
'lambdas/shared/',
|
||||
'lambdas/po/email_processor/',
|
||||
'lambdas/wo/email_processor/',
|
||||
'lambdas/po/web_ui/',
|
||||
'lambdas/wo/web_ui/',
|
||||
'cdk/po_stack.py',
|
||||
'cdk/wo_stack.py',
|
||||
'tests/',
|
||||
'README.md',
|
||||
]
|
||||
|
||||
const mechanicalPrompt = `${PREAMBLE}
|
||||
Independent re-verification — trust nothing self-reported. Run ALL gates,
|
||||
quoting failures verbatim:
|
||||
1. pytest -q --no-cov (repo root, all three roots green)
|
||||
2. ruff check . && ruff format --check .
|
||||
3. cd cdk && npx cdk synth po-ingest -q && npx cdk synth workorder-ingest -q
|
||||
4. cd cdk && npx cdk diff po-ingest ; npx cdk diff workorder-ingest —
|
||||
constraint 12: only the four functions' Code/S3Key (+ metadata) deltas.
|
||||
Any alarm/IAM/env/runtime/handler-prop/logical-ID delta = FAIL. Paste
|
||||
the diff summaries.
|
||||
5. UNTOUCHABLES (each must output NOTHING):
|
||||
git diff ${BASE}...HEAD -- lambdas/po/email_processor/derived_fields.py
|
||||
git diff ${BASE}...HEAD -- lambdas/po/email_processor/template_parser.py
|
||||
git diff ${BASE}...HEAD -- lambdas/wo/email_processor/template_parser.py
|
||||
plus both validate_ai_fallback gate modules (resolve their filenames
|
||||
first) and lambdas/po/site_extractor/.
|
||||
6. BYTE-IDENTITY: sha256 of lambdas/shared/ses_auth.py equals sha256 of
|
||||
git show ${BASE}:lambdas/po/email_processor/ses_auth.py (and the wo
|
||||
copy). Both originals gone from the tree (git ls-files check) and no
|
||||
stray ses_auth.py/__pycache__ anywhere under lambdas/ outside shared/
|
||||
(constraint 11).
|
||||
7. ORDERING PINS: grep line numbers proving PO's ai_fallback emit still
|
||||
precedes the Bedrock invoke and WO's emits are untouched relative to
|
||||
${BASE} (the wo handler diff must contain ONLY the spec's edit classes).
|
||||
8. INFRA-74: both web_ui handlers still contain their own INFRA-74
|
||||
comment verbatim per ${BASE}.
|
||||
9. git status --porcelain scope check: every modified/added/deleted path
|
||||
under ${EXPECTED_SCOPE.join(', ')} (untracked .coverage/.claude/
|
||||
package/ tolerated).
|
||||
passed=true only if all green. YOU MAY NOT edit files.`
|
||||
|
||||
const parityPrompt = `${PREAMBLE}
|
||||
You are the BUNDLE-PARITY verifier — the load-bearing gate of this phase.
|
||||
Everything is local synth + read-only AWS.
|
||||
1. cd cdk && npx cdk synth po-ingest -q -o /tmp/phase3-parity &&
|
||||
npx cdk synth workorder-ingest -q -o /tmp/phase3-parity. Locate all
|
||||
four staged assets (two email processors, two web_ui).
|
||||
2. Re-download both email-processor deployed zips fresh (aws lambda
|
||||
get-function Code.Location, us-east-1) — do not trust a recon cache —
|
||||
and fetch both web_ui functions' deployed file lists.
|
||||
3. Judge per spec.parityRules: per email processor, staged first-party
|
||||
top-level .py set == deployed set PLUS exactly the shared modules the
|
||||
spec's cp rule ships (list both sets; nothing else may appear or
|
||||
vanish); sha256 of staged ses_auth.py == sha256 of the ses_auth.py
|
||||
inside each deployed zip (fail-closed auth byte-identical through the
|
||||
move); dependency packages compared by name, version drift noted not
|
||||
failed. Per web_ui function: staged bundle covers the deployed file
|
||||
list plus web_ui_auth.py, nothing stray (no tests/, no other
|
||||
pipeline's sources, no .eml, no package/).
|
||||
4. DETERMINISM: synth po-ingest twice into fresh -o dirs — identical
|
||||
asset hashes, including the NEW web_ui assets. Then drop a throwaway
|
||||
__pycache__/junk.pyc under lambdas/shared/ (delete it afterwards),
|
||||
re-synth, and confirm the excludes keep every hash unchanged.
|
||||
5. IMPORT-RESOLUTION sanity: inside each staged email-processor asset
|
||||
dir run python3 -c "import handler" with that dir alone on sys.path
|
||||
(env-var stubs as needed) — proves the flat landing satisfies every
|
||||
import including 'from ses_auth import ...' with the moved copy.
|
||||
passed=true only if every check holds.`
|
||||
|
||||
const lenses = [
|
||||
{ key: 'auth-integrity', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — auth-integrity lens. Auth code moved; try to prove
|
||||
the move WEAKENED it. (1) ses_auth: byte-compare the shared copy against
|
||||
${BASE}'s copies yourself; then attack import resolution — in the BUNDLE
|
||||
and in TESTS, which ses_auth wins if anything shadows (stale .pyc, a
|
||||
same-named module on sys.path, the tests loader resolving the old path
|
||||
silently to a stub)? Could a test now pass against a MOCK of ses_auth
|
||||
where it previously exercised the real module? (2) web_ui_auth: diff the
|
||||
extracted block against both originals — any dropped line, changed
|
||||
global, or reordered check? Is the fail-closed path (unset ARN, Secrets
|
||||
exception, wrong token -> 401 before any table access) provably
|
||||
unchanged? Do the four cache globals still behave per-function (module
|
||||
now shared — could cross-importer state ever leak)? (3) The gate call
|
||||
sites: could any handler path now reach S3-fetch/Bedrock/save before
|
||||
authenticate_inbound_email or is_authenticated, where it could not
|
||||
before? confirmed=true only with a concrete exploit sketch or
|
||||
file:line proof.` },
|
||||
{ key: 'telemetry-emf', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — EMF/telemetry lens. The alarms and metric filters
|
||||
consume exact EMF shapes; a silent envelope change breaks paging without
|
||||
failing any test. Read shared/emf.py + every converted call site
|
||||
(git diff ${BASE}) and the synthesized templates' metric filters/alarms.
|
||||
Verify per call site: namespace exact, dimension-set list EXACT
|
||||
([["ParseMethod"],["ParseMethod","TemplateId"]] where applicable, order
|
||||
included), property keys/types identical, timestamp/CloudWatchMetrics
|
||||
envelope structure identical — construct a sample emission per call site
|
||||
and diff it against ${BASE}'s hand-built _aws dict output. Then the
|
||||
ordering pins: PO ai_fallback still pre-Bedrock, WO still post-gate
|
||||
mutually-exclusive, the deliberate double-count comment intact. Finally
|
||||
constraint 6: where does _emit_derived_agreement_metric live and was the
|
||||
decision honored (derived_fields.py diff empty)? confirmed=true only
|
||||
with evidence.` },
|
||||
{ key: 'loader-integrity', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — test/loader-integrity lens. The three loading idioms
|
||||
were rewired; attack them. (1) Does test_ses_auth now exercise the REAL
|
||||
lambdas/shared/ses_auth.py (trace the loader path), and did
|
||||
de-parameterization silently drop any assertion that only ran under one
|
||||
param? (2) Fixture-hygiene: the byte-identity police is retired — does
|
||||
anything still guard against a future stray ses_auth.py copy reappearing
|
||||
in a pipeline dir (should the bundle-consistency or a hygiene test)? If
|
||||
nothing does, that is a finding. (3) sys.modules save/restore: prove it
|
||||
still isolates template_parser between pipelines (run two cross-pipeline
|
||||
tests back to back); prove moto-before-handler ordering survived in
|
||||
_po_parser_support.py. (4) test_bundle_consistency: hand-mutate command
|
||||
strings on scratch copies — a commented-out 'cp shared/*.py', a shared
|
||||
glob narrowed to one file, and a PO_EXPECTED_TOP_LEVEL_MODULES missing a
|
||||
shared module must each FAIL. (5) Run pytest twice in one session and in
|
||||
file-shuffled order (-p no:randomly not installed? then two explicit
|
||||
orderings) to smoke out import-order coupling introduced by the shared
|
||||
path. confirmed=true only with file:line or reproduced-failure
|
||||
evidence.` },
|
||||
]
|
||||
|
||||
let round = 0
|
||||
let checks = null
|
||||
let parity = null
|
||||
let confirmed = []
|
||||
while (round < 3) {
|
||||
phase('Verify')
|
||||
const results = await parallel([
|
||||
() => agent(mechanicalPrompt, { label: `verify:mechanical-r${round}`, model: 'sonnet', phase: 'Verify', schema: CHECKS }),
|
||||
() => agent(parityPrompt, { label: `verify:parity-r${round}`, model: 'opus', phase: 'Verify', schema: PARITY }),
|
||||
...lenses.map(l => () =>
|
||||
agent(l.prompt, { label: `verify:${l.key}-r${round}`, phase: 'Verify', schema: FINDINGS })),
|
||||
])
|
||||
checks = results[0]
|
||||
parity = results[1]
|
||||
confirmed = results.slice(2).filter(Boolean)
|
||||
.flatMap(r => r.findings || [])
|
||||
.filter(f => f.confirmed && f.severity !== 'low')
|
||||
const green = checks && checks.passed && parity && parity.passed
|
||||
log(`Verify round ${round}: mechanical ${checks && checks.passed ? 'GREEN' : 'RED'}, parity ${parity && parity.passed ? 'GREEN' : 'RED'}, confirmed findings: ${confirmed.length}`)
|
||||
if (green && confirmed.length === 0) break
|
||||
|
||||
round += 1
|
||||
if (round >= 3) break
|
||||
phase('Fix')
|
||||
await agent(`${PREAMBLE}
|
||||
You are the fix agent — you may edit files under: ${EXPECTED_SCOPE.join(', ')}.
|
||||
Fix EVERY item below minimally; the binding spec and 13 pinned constraints
|
||||
still hold (a finding that conflicts with a constraint is reported, not
|
||||
"fixed" — the constraint wins, esp. constraint 6's derived_fields
|
||||
untouchability and constraint 5's emission ordering). Re-run the specific
|
||||
failing gate/test per fix.
|
||||
MECHANICAL:\n${checks ? checks.details : '(agent died — rerun all gates)'}
|
||||
PARITY:\n${parity ? parity.details : '(agent died — rerun all)'}
|
||||
CONFIRMED FINDINGS:\n${JSON.stringify(confirmed, null, 2)}
|
||||
${specBlock}`,
|
||||
{ label: `fix:round-${round}`, model: 'opus', phase: 'Fix', schema: IMPL })
|
||||
}
|
||||
|
||||
const verifyClean = checks && checks.passed && parity && parity.passed && confirmed.length === 0
|
||||
if (!verifyClean) {
|
||||
return {
|
||||
status: 'NEEDS ATTENTION — verify not clean after 3 rounds; branch left uncommitted',
|
||||
branch: BRANCH,
|
||||
mechanical: checks,
|
||||
parity,
|
||||
unresolvedFindings: confirmed,
|
||||
implBlockers,
|
||||
reconBlockers,
|
||||
spec,
|
||||
}
|
||||
}
|
||||
|
||||
// ----------------------------------------------------------------- package
|
||||
|
||||
phase('Package')
|
||||
const commit = await agent(`${PREAMBLE.replace('do NOT commit, ', '')}
|
||||
YOU are the commit agent:
|
||||
1. Read ~/Documents/repositories/seahaven/engineering-handbook/commit-messages.md
|
||||
and follow it exactly.
|
||||
2. git add only paths under: ${EXPECTED_SCOPE.join(', ')} and
|
||||
.claude/workflows/phase-3-shared-extraction.js. NOT .coverage, NOT
|
||||
package/. Verify the staged set with git status — the deletions of the
|
||||
moved originals MUST be staged too.
|
||||
3. ONE commit; write the message to /tmp/phase3-commit-msg.txt and use
|
||||
git commit -F /tmp/phase3-commit-msg.txt (backticks in -m get eaten by
|
||||
zsh). Suggested subject:
|
||||
"feat: extract lambdas/shared/ — single-source ses_auth, web_ui auth, email parsing, EMF emitter (refactor phase 3)"
|
||||
Body: the four moves with the byte-identity evidence one-liner for
|
||||
ses_auth, the flat-landing import rule, the shared cp bundling change +
|
||||
web_ui staging, the derived-agreement emitter decision (constraint 6),
|
||||
and the test-plumbing summary. NO AI attribution / Co-Authored-By
|
||||
lines.
|
||||
4. Do NOT push. Return commit sha + shortstat in summary.`,
|
||||
{ label: 'package:commit', model: 'sonnet', phase: 'Package', schema: IMPL })
|
||||
|
||||
return {
|
||||
status: 'BUILT — committed locally, NOT pushed',
|
||||
branch: BRANCH,
|
||||
base: BASE,
|
||||
commit: commit ? commit.summary : 'commit agent died — commit manually',
|
||||
spec: { sharedModules: spec.sharedModules, webUiStaging: spec.webUiStaging, emfDesign: spec.emfDesign, derivedAgreementNote: spec.notes },
|
||||
parityEvidence: parity ? { po: parity.poVerdict, wo: parity.woVerdict, webUi: parity.webUiVerdict } : null,
|
||||
implementation: implOk.map(r => r.summary),
|
||||
filesChanged: implOk.flatMap(r => r.filesChanged),
|
||||
verifyRounds: round + 1,
|
||||
blockers: implBlockers.concat(reconBlockers),
|
||||
outstandingGates: [
|
||||
'/sh-security-review (MANDATORY before push — auth code moved: ses_auth + the web_ui auth gate are exactly the authentication surface; run on the committed diff, and re-run after any post-review fix to this code)',
|
||||
'cross-family cross_review.py NOT mandatory (no IAM change; handler event/return contracts unchanged — internal module moves only). Opt-in if judgment says so',
|
||||
'push + PR + gh pr checks green',
|
||||
'deploy-then-merge: deploy from branch, smoke green, one real PO + WO email each, watch BOTH sender-auth-rejected alarms through live mail (the auth move must not change accept/reject behavior), verify web_ui login still works, THEN merge — and note the post-merge CI redeploy being a no-op (unchanged asset hashes) is itself a verification signal',
|
||||
],
|
||||
}
|
||||
|
|
@ -1,684 +0,0 @@
|
|||
export const meta = {
|
||||
name: 'phase-4-cdk-common',
|
||||
description: 'Phase 4 of the procurement-ingest refactor (docs/refactor-evaluation.md): collapse the 379 identical CDK lines into cdk/common.py as PLAIN FUNCTIONS taking (scope, id, ...) — called with the SAME Stack scope and the SAME construct ids the stacks use today, so every logical ID is byte-stable (Construct-subclass wrapping is forbidden: it would reparent the tree and attempt REPLACEMENT of the RETAIN-protected purchase-orders/WorkOrders tables and named buckets = data loss). Extracts add_ddb_alarms, add_sender_auth_rejected_alarm, add_standard_lambda_alarms, make_bedrock_invoke_statement (account/region-derived ARN, not hardcoded 328440206208), make_email_bucket, make_processor_dlq, make_fallback_rate_alarm — preserving every per-function alarm variance byte-for-byte. Same PR: account on both cdk.Environment, constructs== exact pin, stale-comment fix, CfnOutputs for five function ARNs + consumed table names. ZERO cdk diff on both stacks is the acceptance test. The make_bedrock_invoke_statement IAM PolicyStatement move triggers mandatory GPT-4.1 cross-family review even though semantics are identical. Committed locally, never pushed.',
|
||||
phases: [
|
||||
{ title: 'Setup', detail: 'verify Phases 0+1+2+3 on base, branch feature/phase-4-cdk-common', model: 'haiku' },
|
||||
{ title: 'Recon', detail: '4 mappers: the 379 duplicated CDK lines + per-function alarm variance, the two inline Bedrock PolicyStatements, the fallback-rate + rejected alarm math (post-Phase-1), app.py/pins/outputs surface' },
|
||||
{ title: 'Spec', detail: 'serial fable spec: pin common.py contents + every function signature, per-stack call-site rewrites, alarm-variance table, Bedrock IAM equivalence, fallback-rate call params, app/pins/CfnOutputs, zero-diff judging rules' },
|
||||
{ title: 'Implement', detail: 'opus: cdk/common.py; opus: both stacks (rewire + CfnOutputs); sonnet: app.py + requirements pin + README — disjoint files', model: 'opus' },
|
||||
{ title: 'Verify', detail: 'mechanical gates + zero-cdk-diff verifier (the load-bearing gate) + 3 fable lenses (logical-ID safety, alarm variance, IAM equivalence)' },
|
||||
{ title: 'Fix', detail: 'opus fixer, full re-verify, max 3 rounds', model: 'opus' },
|
||||
{ title: 'Package', detail: 'single commit via -F (no push); runs cross_review.py inline on the IAM diff', model: 'sonnet' },
|
||||
],
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------- constants
|
||||
|
||||
const REPO = '/Users/adammoussa/Documents/repositories/seahaven/procurement-ingest'
|
||||
const BRANCH = 'feature/phase-4-cdk-common'
|
||||
let _args = args
|
||||
if (typeof _args === 'string') {
|
||||
try { _args = JSON.parse(_args) } catch (e) { _args = null }
|
||||
}
|
||||
const BASE = (_args && _args.base) || 'main'
|
||||
|
||||
const CONSTRAINTS = `
|
||||
PINNED BEHAVIORAL CONSTRAINTS (docs/refactor-evaluation.md Phase 4 — violating any is a build failure):
|
||||
1. EXTRACT AS PLAIN FUNCTIONS taking (scope, id, ...), called with the SAME
|
||||
scope (the Stack instance) and the SAME construct ids the stacks use
|
||||
today -> 100% logical-ID-safe. NEVER wrap in Construct subclasses: a
|
||||
subclass inserts a tree node, changes EVERY child logical ID, and would
|
||||
attempt REPLACEMENT of the RETAIN-protected purchase-orders / WorkOrders
|
||||
tables and the named buckets = DATA LOSS. This is THE load-bearing rule
|
||||
of the phase — every other check exists to defend it.
|
||||
2. New module cdk/common.py. Extract exactly:
|
||||
- _DDB_ALARM_OPERATIONS + add_ddb_alarms
|
||||
- add_sender_auth_rejected_alarm
|
||||
- add_standard_lambda_alarms(scope, id_prefix, fn, name_prefix, topic, *,
|
||||
duration_statistic, errors=True, dlq=None, descriptions=...)
|
||||
- make_bedrock_invoke_statement (DERIVE the inference-profile ARN + the
|
||||
per-region foundation-model ARNs from Stack.of(scope).account /
|
||||
Stack.of(scope).region — NOT hardcoded 328440206208)
|
||||
- make_email_bucket
|
||||
- make_processor_dlq
|
||||
- make_fallback_rate_alarm(namespace, rejected_included, period, threshold,
|
||||
floor, evaluation_periods, datapoints_to_alarm) reproducing the
|
||||
expression strings / FILL / labels BYTE-FOR-BYTE.
|
||||
3. PER-FUNCTION ALARM VARIANCE — preserve EXACTLY, do NOT homogenize:
|
||||
PO email-processor duration p99 vs wo-email-processor p95; po-web-ui
|
||||
throttles+duration only; site_extractor no-DLQ; wo web_ui has ZERO alarms
|
||||
(do NOT let the shared helper silently add any); every bespoke alarm
|
||||
DESCRIPTION string is passed through verbatim.
|
||||
4. FALLBACK-RATE RECONCILIATION (post-Phase-1): PO's template-fallback-rate
|
||||
EXCLUDES the rejected series (byte-identical to today, a pre-call
|
||||
double-count would result otherwise) -> call make_fallback_rate_alarm with
|
||||
rejected_included=False; WO's INCLUDES rejected -> rejected_included=True.
|
||||
The two REJECTED alarms are a DIFFERENT shape and are NOT
|
||||
make_fallback_rate_alarm: PO's ai-fallback-rejected is a 6h count-floor
|
||||
IF(FILL(rej,0)>=1,...) alarm (added in Phase 1); WO's is the 5-min /
|
||||
2-of-6 sparse idiom. Keep those as DISTINCT call sites (or a separate
|
||||
dedicated helper) — do NOT force them through make_fallback_rate_alarm.
|
||||
NO element-wise MAX anywhere (post-#102 rule).
|
||||
5. Do NOT import stack-specific services (kms / ssm / event_sources) into
|
||||
common.py — only the constructs the shared helpers actually need.
|
||||
6. SAME PR, net-new & logical-ID-safe additions:
|
||||
- add account='328440206208' to BOTH cdk.Environment calls
|
||||
- pin constructs== to the exact installed version (not a floor >=)
|
||||
- fix the stale "2.259.0" version comments
|
||||
- add CfnOutputs for the FIVE function ARNs + the consumed table names.
|
||||
These are additive; CfnOutputs and account are ID-safe. Verify none of
|
||||
them perturbs an existing logical ID.
|
||||
7. ZERO lambdas/ diff: git diff ${BASE}...HEAD -- lambdas/ must be EMPTY.
|
||||
This phase is CDK-ONLY. tests/ may gain a cdk-diff / synth-only test for
|
||||
the acceptance gate, but NO other tests/ change and NO lambdas/ change.
|
||||
8. ZERO cdk diff on BOTH stacks is the acceptance test: npx cdk diff
|
||||
po-ingest and npx cdk diff workorder-ingest must show ZERO resource
|
||||
changes (no logical-ID, alarm, IAM, table, bucket, env, or metadata
|
||||
delta beyond CDK-tooling noise). The CfnOutputs are the ONLY net-new
|
||||
resources allowed to appear, and only as additions.
|
||||
9. The wo artifact id is 'workorder-ingest' (the construct id / 2nd
|
||||
positional arg), NOT 'WorkorderIngestStack' (that is stack_name). ALWAYS
|
||||
drive synth/diff by the artifact id: npx cdk synth workorder-ingest,
|
||||
npx cdk diff workorder-ingest. Using the stack_name selector fails.
|
||||
10. NO cdk deploy, NO invoke, NO AWS mutation. Read-only AWS only if needed
|
||||
(e.g. confirming deployed alarm names) — the diff gate is a pure local
|
||||
synth-vs-synth comparison.
|
||||
`
|
||||
|
||||
const PREAMBLE = `
|
||||
You are one of several agents building refactor Phase 4 in the git repo at
|
||||
${REPO} on branch ${BRANCH} (already checked out — do NOT switch branches,
|
||||
do NOT create branches, do NOT commit, NEVER push, do NOT run cdk deploy or
|
||||
touch AWS resources beyond read-only calls).
|
||||
Authoritative spec: docs/refactor-evaluation.md, section "Phase 4".
|
||||
Work ONLY in the files you are told you own; other agents are concurrently
|
||||
editing other files in this same working tree.
|
||||
${CONSTRAINTS}
|
||||
Your final message is consumed by an orchestrator script, not a human —
|
||||
return only the structured data requested.
|
||||
`
|
||||
|
||||
// ------------------------------------------------------------------ schemas
|
||||
|
||||
const RECON = {
|
||||
type: 'object',
|
||||
required: ['summary', 'facts'],
|
||||
properties: {
|
||||
summary: { type: 'string' },
|
||||
facts: { type: 'array', items: { type: 'string' } },
|
||||
blockers: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const SPEC = {
|
||||
type: 'object',
|
||||
required: ['commonModule', 'poStackEdits', 'woStackEdits', 'alarmVariance', 'bedrockStatement', 'fallbackRateCalls', 'appAndPins', 'diffRules', 'notes'],
|
||||
properties: {
|
||||
commonModule: { type: 'string', description: 'the full cdk/common.py: every function (add_ddb_alarms + _DDB_ALARM_OPERATIONS, add_sender_auth_rejected_alarm, add_standard_lambda_alarms, make_bedrock_invoke_statement, make_email_bucket, make_processor_dlq, make_fallback_rate_alarm) with its EXACT signature, and the exact imports it needs (no stack-specific kms/ssm/event_sources per constraint 5)' },
|
||||
poStackEdits: { type: 'string', description: 'cdk/po_stack.py: every inline block replaced by a common.* call, file:line, with the exact scope + construct-id + kwargs each call passes so the emitted resource is byte-identical; plus the PO CfnOutput additions (function ARNs + consumed table names)' },
|
||||
woStackEdits: { type: 'string', description: 'cdk/wo_stack.py: same — call-site rewrites file:line preserving construct ids, plus WO CfnOutput additions; explicitly note wo web_ui gets NO alarms (constraint 3)' },
|
||||
alarmVariance: { type: 'string', description: 'the per-function alarm-variance table proving each helper call reproduces exactly what the inline code emits today: PO p99 vs wo-email-processor p95, po-web-ui throttles+duration only, site_extractor no-DLQ, wo web_ui ZERO alarms, every bespoke description string mapped verbatim' },
|
||||
bedrockStatement: { type: 'string', description: 'make_bedrock_invoke_statement: the exact actions + resources, showing how the inference-profile ARN and per-region FM ARNs are derived from Stack.of(scope).account/.region, and PROVING the derived strings resolve in-account to the SAME ARNs the two inline PolicyStatements hardcode today' },
|
||||
fallbackRateCalls: { type: 'string', description: 'the make_fallback_rate_alarm call params for PO (rejected_included=False) and WO (rejected_included=True) reproducing the expression/FILL/label strings byte-for-byte; PLUS how the two DISTINCT rejected alarms stay distinct call sites (PO 6h count-floor IF(FILL(rej,0)>=1,...); WO 5-min/2-of-6 sparse) — NOT folded into make_fallback_rate_alarm, NO element-wise MAX' },
|
||||
appAndPins: { type: 'string', description: 'app.py account= additions to both cdk.Environment calls; the exact constructs== pin (installed version); the stale "2.259.0" comment fix locations + new text; confirmation none perturbs a logical ID' },
|
||||
diffRules: { type: 'string', description: 'exactly how Verify proves zero cdk diff: synth BASE and HEAD into separate temp dirs, diff the two stacks templates, ANY resource/logical-ID/property delta = FAIL, the ONLY allowed additions are the net-new CfnOutputs' },
|
||||
notes: { type: 'string' },
|
||||
},
|
||||
}
|
||||
|
||||
const IMPL = {
|
||||
type: 'object',
|
||||
required: ['filesChanged', 'summary', 'checksRun'],
|
||||
properties: {
|
||||
filesChanged: { type: 'array', items: { type: 'string' } },
|
||||
summary: { type: 'string' },
|
||||
checksRun: { type: 'string' },
|
||||
blockers: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const CHECKS = {
|
||||
type: 'object',
|
||||
required: ['passed', 'details'],
|
||||
properties: {
|
||||
passed: { type: 'boolean' },
|
||||
details: { type: 'string' },
|
||||
scopeViolations: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const DIFF = {
|
||||
type: 'object',
|
||||
required: ['passed', 'poDiffVerdict', 'woDiffVerdict', 'details'],
|
||||
properties: {
|
||||
passed: { type: 'boolean' },
|
||||
poDiffVerdict: { type: 'string', description: 'po-ingest BASE-synth vs HEAD-synth: ZERO resource/logical-ID/property changes (CfnOutputs the only allowed net-new additions) — full template-diff evidence' },
|
||||
woDiffVerdict: { type: 'string', description: 'workorder-ingest (artifact id, NOT WorkorderIngestStack): same zero-change evidence' },
|
||||
details: { type: 'string' },
|
||||
},
|
||||
}
|
||||
|
||||
const FINDINGS = {
|
||||
type: 'object',
|
||||
required: ['findings'],
|
||||
properties: {
|
||||
findings: {
|
||||
type: 'array',
|
||||
items: {
|
||||
type: 'object',
|
||||
required: ['title', 'severity', 'confirmed', 'evidence', 'fix'],
|
||||
properties: {
|
||||
title: { type: 'string' },
|
||||
severity: { enum: ['critical', 'high', 'medium', 'low'] },
|
||||
confirmed: { type: 'boolean' },
|
||||
evidence: { type: 'string' },
|
||||
fix: { type: 'string' },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------- setup
|
||||
|
||||
phase('Setup')
|
||||
const setup = await agent(`
|
||||
In ${REPO}:
|
||||
1. SEQUENCING GATE — Phases 0, 1, 2 AND 3 must all be on ${BASE} (Phase 4
|
||||
dedups BOTH cdk stacks, which Phases 1 (po_stack alarms), 2 (bundling
|
||||
roots) and 3 (shared cp) all edited — building against a pre-Phase-3
|
||||
stack file guarantees a conflict and a wrong diff baseline). git fetch
|
||||
origin, then pick the base ref: origin/${BASE} if that remote ref
|
||||
exists, otherwise the local branch ${BASE} (a stacked local-only base is
|
||||
expected and fine). Verify on the base ref:
|
||||
(a) Phase 3: lambdas/shared/ exists
|
||||
(git ls-tree <baseref> -- lambdas/shared | head);
|
||||
(b) Phase 2: BOTH cdk/po_stack.py and cdk/wo_stack.py contain
|
||||
Code.from_asset("../lambdas") for the email processors
|
||||
(git show <baseref>:cdk/po_stack.py | grep -n '\\.\\./lambdas', same
|
||||
for wo_stack.py);
|
||||
(c) Phase 1: the po-email-processor-ai-fallback-rejected alarm /
|
||||
EmailProcessorAiFallbackRejectedAlarm construct exists in po_stack.py
|
||||
(git show <baseref>:cdk/po_stack.py | grep -n 'ai-fallback-rejected\\|AiFallbackRejected').
|
||||
If Phase 3 is not on ${BASE}, STOP with a blocker (Phase 4 needs the
|
||||
post-Phase-3 stack files as its zero-diff baseline). If any other phase
|
||||
is missing, STOP with a blocker naming the unmet phase and do nothing
|
||||
else.
|
||||
2. Verify clean working tree (untracked .coverage / .claude/ / the local
|
||||
lambdas/po/email_processor/package/ dir are fine; any OTHER dirt =
|
||||
blocker, never stash or discard).
|
||||
3. git checkout ${BASE}; then git pull --ff-only ONLY if the branch has an
|
||||
upstream (a local-only base skips the pull — not a blocker); then
|
||||
git checkout -b ${BRANCH}
|
||||
4. gh pr list --state open --json number,title,headRefName (overlap check).
|
||||
Return facts: HEAD sha, per-phase gate evidence, open PRs, blockers.
|
||||
`, { label: 'setup:branch', model: 'haiku', schema: RECON })
|
||||
|
||||
if (!setup || (setup.blockers && setup.blockers.length)) {
|
||||
return { aborted: 'setup blockers', blockers: setup ? setup.blockers : ['setup agent died'], facts: setup ? setup.facts : [] }
|
||||
}
|
||||
log(`Branch ${BRANCH} ready off ${BASE}. ${setup.summary}`)
|
||||
|
||||
// ------------------------------------------------------------------- recon
|
||||
|
||||
phase('Recon')
|
||||
const recon = await parallel([
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of the ~379 duplicated CDK lines and the PER-FUNCTION ALARM
|
||||
VARIANCE that MUST survive the dedup (constraint 3). In cdk/po_stack.py and
|
||||
cdk/wo_stack.py, quote verbatim with file:line:
|
||||
1. _DDB_ALARM_OPERATIONS + add_ddb_alarms (both copies — are they
|
||||
byte-identical? diff them).
|
||||
2. add_sender_auth_rejected_alarm (both copies).
|
||||
3. Every add_standard_lambda_alarms-shaped block: for EACH function
|
||||
(po email-processor, wo email-processor, po web_ui, wo web_ui,
|
||||
po site_extractor) list the exact alarm set, the duration statistic
|
||||
(prove PO email p99 vs wo email p95), whether throttles/errors/dlq
|
||||
alarms are present, and QUOTE every bespoke alarm description string.
|
||||
CRITICALLY: confirm wo web_ui has ZERO alarms today.
|
||||
4. make_email_bucket / make_processor_dlq shaped blocks (both copies), and
|
||||
which functions get a DLQ (site_extractor has none).
|
||||
5. The exact construct ids (2nd positional arg to every alarm / bucket /
|
||||
dlq / statement construct) — these are the logical-ID roots that must be
|
||||
passed UNCHANGED into the shared helpers.
|
||||
30-40 precise facts. Any block that is NOT actually identical between
|
||||
stacks (genuine drift) is a blocker to report, not to silently reconcile.`,
|
||||
{ label: 'recon:duplicated-cdk', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of the two inline Bedrock IAM PolicyStatements (the
|
||||
make_bedrock_invoke_statement source — constraint 2, the cross-family-review
|
||||
surface). In both stacks quote verbatim with file:line: the full
|
||||
iam.PolicyStatement (effect, actions, resources, conditions). For EACH
|
||||
resource ARN record whether the account (328440206208) and region are
|
||||
hardcoded or referenced, and enumerate every inference-profile ARN and every
|
||||
per-region foundation-model ARN. Determine the EXACT list of regions / model
|
||||
ids baked into the resources so the derived form (Stack.of(scope).account /
|
||||
.region) can be proven to resolve to the identical strings in-account. Note
|
||||
which principal/role each statement is attached to and how (add_to_role_policy
|
||||
vs inline policy). 15-25 facts.`,
|
||||
{ label: 'recon:bedrock-iam', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of the fallback-rate + rejected alarm math AS IT STANDS
|
||||
POST-PHASE-1 (constraint 4). In both stacks quote verbatim with file:line:
|
||||
1. PO's template-fallback-rate alarm: the full metric-math expression
|
||||
string(s), every FILL(), every label, the period/threshold/
|
||||
evaluation_periods/datapoints_to_alarm — and CONFIRM it EXCLUDES the
|
||||
rejected series today (rejected_included=False).
|
||||
2. WO's template-fallback-rate alarm: same, and CONFIRM it INCLUDES the
|
||||
rejected series (rejected_included=True).
|
||||
3. PO's ai-fallback-rejected alarm (added in Phase 1): confirm it is the
|
||||
6h count-floor IF(FILL(rej,0)>=1,...) shape — quote the expression.
|
||||
4. WO's rejected alarm: confirm it is the 5-min / 2-of-6 sparse idiom —
|
||||
quote it. These two are DIFFERENT shapes and must stay distinct call
|
||||
sites, NOT folded into make_fallback_rate_alarm.
|
||||
5. Confirm NO element-wise MAX exists anywhere in either expression
|
||||
(post-#102 rule).
|
||||
Return the exact parameter values each make_fallback_rate_alarm call must
|
||||
carry so Verify can prove byte-identity. 15-25 facts.`,
|
||||
{ label: 'recon:fallback-alarms', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of the app.py / pins / outputs surface (constraint 6):
|
||||
1. cdk/app.py: quote both cdk.Environment(...) calls verbatim with line
|
||||
numbers (region-only today; account must be added).
|
||||
2. The constructs dependency pin: quote cdk/requirements.txt line(s) and
|
||||
find the stale "2.259.0" version comment(s) wherever they live (app.py,
|
||||
stacks, requirements — grep the whole cdk/ tree) with file:line and the
|
||||
actual installed constructs / aws-cdk-lib versions.
|
||||
3. The five Lambda function construct variables in the stacks whose ARNs
|
||||
need CfnOutputs (po email-processor, po web_ui, po site_extractor,
|
||||
wo email-processor, wo web_ui) and the table constructs whose names are
|
||||
consumed (purchase-orders, WorkOrders, and any comments table) — quote
|
||||
the construct handles + ids so the CfnOutputs reference them correctly.
|
||||
4. Any existing CfnOutput in either stack (WO reportedly has zero).
|
||||
5. Confirm the wo artifact id is 'workorder-ingest' (the 2nd positional
|
||||
arg to the Stack constructor in app.py), distinct from
|
||||
stack_name='WorkorderIngestStack' (constraint 9).
|
||||
15-25 facts.`,
|
||||
{ label: 'recon:app-pins-outputs', model: 'haiku', phase: 'Recon', schema: RECON }),
|
||||
])
|
||||
|
||||
const reconOk = recon.filter(Boolean)
|
||||
const pack = reconOk.map(r => `## ${r.summary}\n${r.facts.join('\n')}`).join('\n\n')
|
||||
const reconBlockers = reconOk.flatMap(r => r.blockers || [])
|
||||
.filter(b => b && !/^\s*(none|n\/a)\b/i.test(b))
|
||||
log(`Recon complete: ${reconOk.length}/4 mappers, ${reconBlockers.length} advisory notes`)
|
||||
// Recon "blockers" for this phase are advisory design-notes / intended
|
||||
// constraint-2 & 6 work items (derive the Bedrock ARN from Stack.of(scope),
|
||||
// add account= to the environments, exact-pin constructs, fix the stale
|
||||
// aws-cdk-lib version comment, decide the one common sender-auth docstring),
|
||||
// NOT stop conditions — main-loop verified. The real gate is the ZERO cdk diff
|
||||
// acceptance test in Verify. Fold the notes into the spec context instead of
|
||||
// aborting so the spec agent must address each.
|
||||
const reconAdvisories = reconBlockers.length
|
||||
? `\n\nRECON ADVISORIES (recon flagged these; they are the intended constraint-2/6 work + a docstring choice, NOT drift that blocks dedup — resolve each per the constraints; the zero-cdk-diff test is the real acceptance gate):\n- ${reconBlockers.join('\n- ')}`
|
||||
: ''
|
||||
|
||||
// -------------------------------------------------------------------- spec
|
||||
|
||||
phase('Spec')
|
||||
const spec = await agent(`${PREAMBLE}
|
||||
You are the SPEC agent — the single authority that pins every contested
|
||||
decision BEFORE parallel implementation (parallel leaves cannot see each
|
||||
other's choices). Using the recon pack below plus your own reads of the
|
||||
actual files, produce the binding implementation spec:
|
||||
- commonModule: the full cdk/common.py — every function per constraint 2
|
||||
with its EXACT signature (add_standard_lambda_alarms keyword-only params
|
||||
exactly as the doc pins them), and ONLY the imports the helpers need
|
||||
(constraint 5 — no kms/ssm/event_sources). Every function is a PLAIN
|
||||
function taking (scope, id, ...) — NO Construct subclass anywhere
|
||||
(constraint 1).
|
||||
- poStackEdits / woStackEdits: for each stack, the exact call-site rewrites
|
||||
(file:line) mapping each inline block to a common.* call, passing the
|
||||
SAME scope (the Stack) and the SAME construct id it uses today so every
|
||||
logical ID is byte-stable; plus the CfnOutput additions (five function
|
||||
ARNs split across the two stacks + consumed table names). State
|
||||
explicitly that wo web_ui receives NO alarm call (constraint 3).
|
||||
- alarmVariance: the per-function variance table (constraint 3) proving each
|
||||
helper call reproduces today's emitted alarms EXACTLY — PO p99 vs wo-email
|
||||
p95, po-web-ui throttles+duration only, site_extractor no-DLQ, wo web_ui
|
||||
zero alarms, every bespoke description string mapped verbatim.
|
||||
- bedrockStatement: make_bedrock_invoke_statement's actions + resources and
|
||||
the derivation of the inference-profile / per-region FM ARNs from
|
||||
Stack.of(scope).account/.region, with a proof table showing each derived
|
||||
string equals the inline hardcoded ARN in-account (this is the
|
||||
cross-family-review surface — be exhaustive).
|
||||
- fallbackRateCalls: the make_fallback_rate_alarm call params for PO
|
||||
(rejected_included=False) and WO (rejected_included=True) reproducing the
|
||||
expression/FILL/label strings byte-for-byte, PLUS the plan for keeping the
|
||||
two DISTINCT rejected alarms as separate call sites (PO 6h count-floor,
|
||||
WO 5-min/2-of-6) — NOT folded, NO element-wise MAX (constraint 4).
|
||||
- appAndPins: app.py account= on both Environment calls; the exact
|
||||
constructs== pin; the stale "2.259.0" comment fix (file:line + new text);
|
||||
confirmation each is logical-ID-neutral.
|
||||
- diffRules: exactly how Verify proves ZERO cdk diff — synth ${BASE} and
|
||||
HEAD each into a separate temp dir, diff both stacks' templates, ANY
|
||||
resource/logical-ID/property delta = FAIL, the ONLY allowed net-new is
|
||||
the CfnOutputs; drive synth/diff by artifact id (po-ingest /
|
||||
workorder-ingest, constraint 9).
|
||||
Recon pack:\n${pack}${reconAdvisories}`,
|
||||
{ label: 'spec:pin-common', phase: 'Spec', schema: SPEC })
|
||||
|
||||
if (!spec) return { aborted: 'spec agent died — rerun workflow', reconBlockers }
|
||||
const specBlock = `BINDING SPEC (from the spec agent — implement EXACTLY this):\n${JSON.stringify(spec, null, 2)}`
|
||||
log('Spec pinned: common.py contents, per-stack rewrites, alarm variance, Bedrock IAM, fallback-rate calls, app/pins/outputs')
|
||||
|
||||
// --------------------------------------------------------------- implement
|
||||
|
||||
phase('Implement')
|
||||
const impl = await parallel([
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: cdk/common.py ONLY (create it). Do not touch po_stack.py,
|
||||
wo_stack.py, app.py, requirements.txt, README, tests, or anything under
|
||||
lambdas/.
|
||||
Task: author cdk/common.py per spec.commonModule EXACTLY — every function
|
||||
(add_ddb_alarms + _DDB_ALARM_OPERATIONS, add_sender_auth_rejected_alarm,
|
||||
add_standard_lambda_alarms with the pinned keyword-only signature,
|
||||
make_bedrock_invoke_statement deriving ARNs from Stack.of(scope).account/
|
||||
.region, make_email_bucket, make_processor_dlq, make_fallback_rate_alarm)
|
||||
as a PLAIN function taking (scope, id, ...) — NEVER a Construct subclass
|
||||
(constraint 1). Import ONLY what the helpers need — no kms/ssm/
|
||||
event_sources (constraint 5). Match the fallback-rate expression/FILL/label
|
||||
strings byte-for-byte (constraint 4). Do NOT put the two rejected alarms in
|
||||
make_fallback_rate_alarm.
|
||||
Run before returning: ruff check cdk/common.py && ruff format cdk/common.py
|
||||
--check, plus a py_compile import smoke (python3 -c "import common" from
|
||||
cdk/ with the CDK venv). Full synth is the stacks agent's job — but if you
|
||||
can import common cleanly, report it.
|
||||
${specBlock}`,
|
||||
{ label: 'impl:common-module', model: 'opus', phase: 'Implement', schema: IMPL }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: cdk/po_stack.py and cdk/wo_stack.py ONLY. Do not touch
|
||||
cdk/common.py (another agent authors it), app.py, requirements.txt, README,
|
||||
or lambdas/.
|
||||
Task: apply spec.poStackEdits + spec.woStackEdits — replace each inline
|
||||
block with the matching common.* call, passing the SAME scope (the Stack
|
||||
instance, NOT a new Construct) and the SAME construct id used today so every
|
||||
logical ID is byte-stable (constraint 1). Preserve every per-function alarm
|
||||
variance (constraint 3): PO email p99 / wo email p95, po-web-ui throttles+
|
||||
duration only, site_extractor no-DLQ, wo web_ui gets NO alarm call, bespoke
|
||||
descriptions passed verbatim. Wire the fallback-rate calls per
|
||||
spec.fallbackRateCalls (PO rejected_included=False, WO True) and keep the
|
||||
two rejected alarms as distinct call sites (constraint 4). Add the CfnOutputs
|
||||
per spec (function ARNs + consumed table names) — additive, ID-safe.
|
||||
Import from common (bare 'import common' / 'from common import ...' — cdk/
|
||||
is on sys.path via app.py's imports). Touch nothing else (tables, KMS, SSM,
|
||||
event sources, the RETAIN policies stay byte-identical).
|
||||
Run before returning: ruff check cdk && cd cdk &&
|
||||
npx cdk synth po-ingest -q -o /tmp/phase4-synth &&
|
||||
npx cdk synth workorder-ingest -q -o /tmp/phase4-synth (artifact-id
|
||||
selectors, NOT stack_name — constraint 9). If cdk/common.py has not landed
|
||||
yet the synth fails on the missing import — poll by re-running up to ~10 min
|
||||
before reporting a blocker. Confirm both stacks synth and note that the
|
||||
ONLY template delta vs ${BASE} is the net-new CfnOutputs (spot-check a
|
||||
couple of alarm logical IDs are unchanged).
|
||||
${specBlock}`,
|
||||
{ label: 'impl:cdk-stacks', model: 'opus', phase: 'Implement', schema: IMPL }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: cdk/app.py, cdk/requirements.txt and README.md ONLY. Do not touch
|
||||
common.py, the stacks, tests, or lambdas/.
|
||||
Task A: apply spec.appAndPins — add account='328440206208' to BOTH
|
||||
cdk.Environment calls in app.py, pin constructs== to the exact installed
|
||||
version in cdk/requirements.txt, and fix the stale "2.259.0" comment(s) at
|
||||
the file:line spec.appAndPins gives (only those in files you own — if a
|
||||
stale comment lives in a stack file, note it for the stacks agent, do NOT
|
||||
edit their file). Every edit here must be logical-ID-neutral (account on
|
||||
Environment does not change resource logical IDs; verify in your summary).
|
||||
Task B: README — document cdk/common.py in the CDK/architecture section
|
||||
(the shared plain-function helpers, the logical-ID-safety rule, the
|
||||
account/region-derived Bedrock ARN, the new CfnOutputs), and note the
|
||||
account is now explicit on both stacks. Match existing README style. If the
|
||||
README documents the stacks' resource inventory, keep it accurate.
|
||||
Run before returning: ruff check cdk (app.py) and a py_compile of app.py;
|
||||
you cannot run the full synth without the stacks agent's edits — if you want
|
||||
to smoke-test, poll cd cdk && npx cdk synth po-ingest -q up to ~10 min, but
|
||||
a clean app.py parse is sufficient for your scope.
|
||||
${specBlock}`,
|
||||
{ label: 'impl:app-pins-readme', model: 'sonnet', phase: 'Implement', schema: IMPL }),
|
||||
])
|
||||
|
||||
const implOk = impl.filter(Boolean)
|
||||
const implBlockers = implOk.flatMap(r => r.blockers || [])
|
||||
log(`Implement complete: ${implOk.length}/3 agents, blockers: ${implBlockers.length}`)
|
||||
|
||||
// ---------------------------------------------------- verify + fix loop
|
||||
|
||||
const EXPECTED_SCOPE = [
|
||||
'cdk/common.py',
|
||||
'cdk/po_stack.py',
|
||||
'cdk/wo_stack.py',
|
||||
'cdk/app.py',
|
||||
'cdk/requirements.txt',
|
||||
'README.md',
|
||||
'tests/',
|
||||
]
|
||||
|
||||
const mechanicalPrompt = `${PREAMBLE}
|
||||
Independent re-verification — trust nothing self-reported. Run ALL gates,
|
||||
quoting failures verbatim:
|
||||
1. pytest -q --no-cov (repo root — all suites green; a synth-only cdk-diff
|
||||
test may now exist under tests/)
|
||||
2. ruff check . && ruff format --check .
|
||||
3. cd cdk && npx cdk synth po-ingest -q && npx cdk synth workorder-ingest -q
|
||||
(artifact-id selectors, NOT stack_name — constraint 9)
|
||||
4. ZERO-CODE invariant (constraint 7): git diff ${BASE}...HEAD -- lambdas/
|
||||
must output NOTHING.
|
||||
5. NO CONSTRUCT SUBCLASS (constraint 1): grep cdk/common.py for
|
||||
'class .*Construct' / 'class .*(Construct)' — there must be NONE; every
|
||||
extracted symbol is a plain 'def'. Report any subclass as a hard FAIL.
|
||||
6. cdk/common.py imports NO kms/ssm/event_sources (constraint 5) — grep and
|
||||
confirm.
|
||||
7. Both cdk.Environment calls in app.py carry account='328440206208';
|
||||
constructs== is an exact pin (not >=); no "2.259.0" stale comment
|
||||
remains (grep the cdk/ tree).
|
||||
8. CfnOutputs: five function ARNs + the consumed table names are present
|
||||
across the two stacks (grep CfnOutput).
|
||||
9. git status --porcelain scope check: every modified/added path under
|
||||
${EXPECTED_SCOPE.join(', ')} (untracked .coverage/.claude/package/
|
||||
tolerated). No lambdas/ or non-cdk-diff tests/ change.
|
||||
passed=true only if all green. YOU MAY NOT edit files.`
|
||||
|
||||
const diffPrompt = `${PREAMBLE}
|
||||
You are the ZERO-CDK-DIFF verifier — the load-bearing gate of this phase
|
||||
(the doc names it the acceptance test). Everything is local synth-vs-synth.
|
||||
1. From a clean worktree state, synth the BASE templates: check out (via
|
||||
git worktree add or git stash-free 'git show'-based synth — prefer
|
||||
'git worktree add /tmp/phase4-base ${BASE}' so HEAD is untouched), then
|
||||
in that BASE tree cd cdk && npx cdk synth po-ingest -q -o
|
||||
/tmp/phase4-diff-base && npx cdk synth workorder-ingest -q -o
|
||||
/tmp/phase4-diff-base.
|
||||
2. Synth the HEAD templates: in the working tree cd cdk && npx cdk synth
|
||||
po-ingest -q -o /tmp/phase4-diff-head && npx cdk synth workorder-ingest
|
||||
-q -o /tmp/phase4-diff-head. (Both by ARTIFACT ID, constraint 9.)
|
||||
3. Diff the two CloudFormation templates per stack
|
||||
(/tmp/phase4-diff-base/<stack>.template.json vs
|
||||
/tmp/phase4-diff-head/<stack>.template.json). Normalize only CDK-tooling
|
||||
noise (the CDKMetadata Analytics string, asset-hash-derived S3Key values
|
||||
that were ALSO equal on BASE). Then judge:
|
||||
- ZERO logical-ID changes (no renamed/removed/added Resources except the
|
||||
net-new CfnOutputs).
|
||||
- ZERO alarm property deltas (thresholds, statistics p99/p95, expression
|
||||
strings, FILL, labels, evaluation_periods, datapoints_to_alarm).
|
||||
- ZERO IAM deltas: the Bedrock PolicyStatement actions/resources must be
|
||||
byte-identical after the account/region derivation resolves in-account.
|
||||
- ZERO DynamoDB table / bucket / DLQ / env / runtime deltas.
|
||||
- The ONLY allowed net-new is the Outputs block (the five function ARNs
|
||||
+ consumed table names).
|
||||
ANY delta outside that allowance = FAIL. Paste the actual per-stack
|
||||
template diff (or 'identical' with the normalized-noise list).
|
||||
4. Cross-check with the live tool: cd cdk && npx cdk diff po-ingest ;
|
||||
npx cdk diff workorder-ingest against the deployed state must also show
|
||||
only the CfnOutput additions (network permitting; if AWS creds are
|
||||
read-only-absent, the BASE-vs-HEAD template diff in steps 1-3 is
|
||||
authoritative).
|
||||
5. Clean up any /tmp worktrees you created (git worktree remove).
|
||||
passed=true only if BOTH stacks show zero resource change beyond the
|
||||
CfnOutput additions.`
|
||||
|
||||
const lenses = [
|
||||
{ key: 'logical-id-safety', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — logical-ID-safety lens (the load-bearing rule,
|
||||
constraint 1). Try to prove a construct-id or tree-shape change slipped in.
|
||||
(1) Read cdk/common.py: is EVERY extracted symbol a plain 'def' taking
|
||||
(scope, id, ...)? Any 'class X(Construct)' / Construct subclass / nested
|
||||
Construct is an automatic CRITICAL — a subclass reparents the tree and
|
||||
would attempt REPLACEMENT of the RETAIN-protected purchase-orders /
|
||||
WorkOrders tables and the named buckets. (2) For every rewritten call site
|
||||
in both stacks, prove the scope passed is the Stack instance (self), NOT a
|
||||
new intermediate construct, and the construct id string is IDENTICAL to the
|
||||
BASE inline id (git diff ${BASE} the id strings). (3) Synth BASE and HEAD
|
||||
and diff the full Resources logical-ID SET — it must be identical (only
|
||||
Outputs added). Any renamed/removed logical ID = confirmed CRITICAL.
|
||||
(4) Confirm the RETAIN removal policies on the tables and the bucket
|
||||
names/policies are byte-identical post-refactor. confirmed=true only with a
|
||||
concrete logical-ID delta or a subclass-smell file:line.` },
|
||||
{ key: 'alarm-variance', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — alarm-variance lens (constraint 3). The shared helpers
|
||||
must NOT homogenize the deliberate per-function differences. Read
|
||||
cdk/common.py + every helper call site + the synthesized templates' alarms.
|
||||
Prove each of these survived EXACTLY: (1) PO email-processor duration alarm
|
||||
uses p99, wo-email-processor uses p95 — quote both from the synthesized
|
||||
templates. (2) po-web-ui has ONLY throttles+duration alarms (no errors/dlq
|
||||
beyond what it had). (3) site_extractor has NO DLQ alarm. (4) wo web_ui has
|
||||
ZERO alarms — prove the shared helper did NOT silently add any (search the
|
||||
wo template for any alarm whose dimensions point at the wo web_ui
|
||||
function). (5) Every bespoke alarm description string is byte-identical to
|
||||
BASE (diff the AlarmDescription fields). (6) Fallback-rate: PO excludes the
|
||||
rejected series (rejected_included=False), WO includes it; the two rejected
|
||||
alarms kept their distinct shapes (PO 6h count-floor, WO 5-min/2-of-6); NO
|
||||
element-wise MAX anywhere. confirmed=true only with a template-level diff
|
||||
showing a homogenized or dropped alarm.` },
|
||||
{ key: 'iam-equivalence', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — IAM-equivalence lens (the cross-family-review surface).
|
||||
make_bedrock_invoke_statement moved the PolicyStatement construction and
|
||||
swapped hardcoded 328440206208 for Stack.of(scope).account/.region. Prove
|
||||
the produced IAM is IDENTICAL. (1) Synth both stacks and extract the Bedrock
|
||||
PolicyStatement from each template; diff actions and resources against
|
||||
${BASE}'s synthesized statements — the resolved ARN strings (account +
|
||||
region substituted) must be byte-identical in-account. (2) Confirm the
|
||||
resources still enumerate the SAME inference-profile ARN and the SAME
|
||||
per-region foundation-model ARNs (no region dropped/added, no wildcard
|
||||
broadening). (3) Confirm effect/conditions/principal attachment unchanged
|
||||
and the statement is attached to the SAME role. (4) Flag any broadening
|
||||
(e.g. a Ref/Sub that resolves to a wildcard, or Stack.region producing a
|
||||
different region than the hardcoded one) as confirmed HIGH. confirmed=true
|
||||
only with the two synthesized statements diffed.` },
|
||||
]
|
||||
|
||||
let round = 0
|
||||
let checks = null
|
||||
let diff = null
|
||||
let confirmed = []
|
||||
while (round < 3) {
|
||||
phase('Verify')
|
||||
const results = await parallel([
|
||||
() => agent(mechanicalPrompt, { label: `verify:mechanical-r${round}`, model: 'sonnet', phase: 'Verify', schema: CHECKS }),
|
||||
() => agent(diffPrompt, { label: `verify:cdk-diff-r${round}`, model: 'opus', phase: 'Verify', schema: DIFF }),
|
||||
...lenses.map(l => () =>
|
||||
agent(l.prompt, { label: `verify:${l.key}-r${round}`, phase: 'Verify', schema: FINDINGS })),
|
||||
])
|
||||
checks = results[0]
|
||||
diff = results[1]
|
||||
confirmed = results.slice(2).filter(Boolean)
|
||||
.flatMap(r => r.findings || [])
|
||||
.filter(f => f.confirmed && f.severity !== 'low')
|
||||
const green = checks && checks.passed && diff && diff.passed
|
||||
log(`Verify round ${round}: mechanical ${checks && checks.passed ? 'GREEN' : 'RED'}, cdk-diff ${diff && diff.passed ? 'GREEN' : 'RED'}, confirmed findings: ${confirmed.length}`)
|
||||
if (green && confirmed.length === 0) break
|
||||
|
||||
round += 1
|
||||
if (round >= 3) break
|
||||
phase('Fix')
|
||||
await agent(`${PREAMBLE}
|
||||
You are the fix agent — you may edit files under: ${EXPECTED_SCOPE.join(', ')}.
|
||||
Fix EVERY item below minimally; the binding spec and 10 pinned constraints
|
||||
still hold (a finding that conflicts with a constraint is reported, not
|
||||
"fixed" — the constraint wins, esp. constraint 1's plain-function /
|
||||
no-Construct-subclass rule, constraint 3's alarm variance, and constraint 4's
|
||||
distinct rejected alarms / no element-wise MAX). Re-run the specific failing
|
||||
gate per fix (the zero-cdk-diff check is authoritative — a fix that
|
||||
introduces ANY logical-ID or property delta is worse than the finding).
|
||||
MECHANICAL:\n${checks ? checks.details : '(agent died — rerun all gates)'}
|
||||
CDK-DIFF:\n${diff ? diff.details : '(agent died — rerun all)'}
|
||||
CONFIRMED FINDINGS:\n${JSON.stringify(confirmed, null, 2)}
|
||||
${specBlock}`,
|
||||
{ label: `fix:round-${round}`, model: 'opus', phase: 'Fix', schema: IMPL })
|
||||
}
|
||||
|
||||
const verifyClean = checks && checks.passed && diff && diff.passed && confirmed.length === 0
|
||||
if (!verifyClean) {
|
||||
return {
|
||||
status: 'NEEDS ATTENTION — verify not clean after 3 rounds; branch left uncommitted',
|
||||
branch: BRANCH,
|
||||
mechanical: checks,
|
||||
cdkDiff: diff,
|
||||
unresolvedFindings: confirmed,
|
||||
implBlockers,
|
||||
reconBlockers,
|
||||
spec,
|
||||
}
|
||||
}
|
||||
|
||||
// ----------------------------------------------------------------- package
|
||||
|
||||
phase('Package')
|
||||
const commit = await agent(`${PREAMBLE.replace('do NOT commit, ', '')}
|
||||
YOU are the commit agent:
|
||||
1. MANDATORY GPT-4.1 CROSS-FAMILY REVIEW (the doc mandates it for the
|
||||
make_bedrock_invoke_statement IAM PolicyStatement move, even though
|
||||
semantics are identical). Capture the Bedrock-statement diff first:
|
||||
git diff ${BASE}...HEAD -- cdk/common.py cdk/po_stack.py cdk/wo_stack.py
|
||||
(isolate the make_bedrock_invoke_statement + its two call sites), then
|
||||
RUN inline:
|
||||
python3 ~/Documents/repositories/seahaven/security-review/cross_review.py
|
||||
"Review this CDK IAM PolicyStatement move for breaking changes: the two
|
||||
inline Bedrock invoke PolicyStatements (hardcoded account 328440206208)
|
||||
were consolidated into make_bedrock_invoke_statement in cdk/common.py,
|
||||
deriving the inference-profile + per-region foundation-model ARNs from
|
||||
Stack.of(scope).account/.region. Confirm the produced actions/resources
|
||||
are byte-identical in-account and no privilege broadening. <paste diff>"
|
||||
Record the verdict verbatim in your summary. If cross_review.py is
|
||||
unavailable, DO NOT block the local commit but flag the review as
|
||||
OUTSTANDING in your summary (it must be run before merge).
|
||||
2. Read ~/Documents/repositories/seahaven/engineering-handbook/commit-messages.md
|
||||
and follow it exactly.
|
||||
3. git add only paths under: ${EXPECTED_SCOPE.join(', ')} and
|
||||
.claude/workflows/phase-4-cdk-common.js. NOT .coverage, NOT package/,
|
||||
NOT cdk.out. Verify the staged set with git status.
|
||||
4. ONE commit; write the message to /tmp/phase4-commit-msg.txt and use
|
||||
git commit -F /tmp/phase4-commit-msg.txt (backticks in -m get eaten by
|
||||
zsh). Suggested subject:
|
||||
"feat: extract cdk/common.py — dedup 379 CDK lines as logical-ID-safe plain helpers (refactor phase 4)"
|
||||
Body: the plain-function (scope, id, ...) approach and WHY no Construct
|
||||
subclass (RETAIN-table replacement), the account/region-derived Bedrock
|
||||
ARN, the zero-cdk-diff acceptance evidence for both stacks, the
|
||||
account=/constructs pin/stale-comment/CfnOutput net-new additions, and
|
||||
the cross_review.py verdict one-liner. NO AI attribution / Co-Authored-By
|
||||
lines.
|
||||
5. Do NOT push. Return commit sha + shortstat + the cross_review.py verdict
|
||||
in summary.`,
|
||||
{ label: 'package:commit', model: 'sonnet', phase: 'Package', schema: IMPL })
|
||||
|
||||
return {
|
||||
status: 'BUILT — committed locally, NOT pushed',
|
||||
branch: BRANCH,
|
||||
base: BASE,
|
||||
commit: commit ? commit.summary : 'commit agent died — commit manually',
|
||||
spec: { commonModule: spec.commonModule, bedrockStatement: spec.bedrockStatement, fallbackRateCalls: spec.fallbackRateCalls, appAndPins: spec.appAndPins, notes: spec.notes },
|
||||
diffEvidence: diff ? { po: diff.poDiffVerdict, wo: diff.woDiffVerdict } : null,
|
||||
implementation: implOk.map(r => r.summary),
|
||||
filesChanged: implOk.flatMap(r => r.filesChanged),
|
||||
verifyRounds: round + 1,
|
||||
blockers: implBlockers.concat(reconBlockers),
|
||||
outstandingGates: [
|
||||
'MANDATORY cross-family GPT-4.1 review (cross_review.py) on the make_bedrock_invoke_statement IAM PolicyStatement move — the Package agent runs it inline and records the verdict; confirm that verdict is clean (or re-run) before merge. If cross_review.py was unavailable at commit time, this review is OUTSTANDING — do not merge without it.',
|
||||
'/sh-security-review NOT required (pure CDK refactor — no untrusted-input/auth-logic change; the pre-push scanners still run as the unattended backstop)',
|
||||
'push + PR + gh pr checks green',
|
||||
'deploy-then-merge with cdk diff zero-change on BOTH stacks as the live acceptance signal: deploy from branch, confirm cdk diff po-ingest / cdk diff workorder-ingest show only the CfnOutput additions, both stacks reach UPDATE_COMPLETE, all alarms still OK, THEN merge (a no-op resource redeploy is itself the verification signal). Drive synth/diff by artifact id workorder-ingest, NOT stack_name WorkorderIngestStack (constraint 9).',
|
||||
'update the Confluence "AWS Architecture Map" if the new CfnOutputs / account-explicit envs change the documented resource inventory',
|
||||
],
|
||||
}
|
||||
|
|
@ -1,692 +0,0 @@
|
|||
export const meta = {
|
||||
name: 'phase-5-handler-decomposition',
|
||||
description: 'Phase 5 of the procurement-ingest refactor (docs/refactor-evaluation.md): decompose both email-processor God-handlers into flat siblings along the seams that already work. PO handler.py splits into handler.py (event loop + auth + routing) / extraction.py (extract_with_claude + prompt import; parse_raw_email already lives in shared/email_parsing.py) / enrichment.py (enrich_parsed, pad_zip — PO-only) / telemetry.py (the EMF ParseMethod emit wrappers) / persistence.py (_write_fields/_merge_update/save_* with save_new_po+save_revision collapsed into one behavior-identical _save_merge). WO splits into ~5 concerns, keeping validate_ai_fallback + the [0-9]+ work_order_id key guard in the handler loop ahead of both saves and _header_date_iso/comment_id determinism with persistence. EXTRACTION_PROMPT moves to prompts.py (re-exported into handler for 4 tests). Lazy cached boto3 accessors in I/O modules; pure modules import no boto3. Requires Phases 0-3 on the base branch (relies on the flat-sibling lambdas/shared/ pattern + the Phase 0/2/3 bundling glob that auto-ships new siblings). Untrusted-input parse/extract/gate/auth-routing code moves, so push is gated on /sh-security-review in the main loop. Committed locally, never pushed.',
|
||||
phases: [
|
||||
{ title: 'Setup', detail: 'verify Phases 0+1+2+3 on base (lambdas/shared/ + ses_auth/web_ui_auth/email_parsing/emf present), branch feature/phase-5-handler-decomposition', model: 'haiku' },
|
||||
{ title: 'Recon', detail: '4 mappers: PO handler seams + save_new_po/save_revision byte-compare, WO handler seams + key-guard/date-determinism, bundling glob + AST test + monkeypatch/loader patch surface, deployed-zip baseline (read-only AWS)' },
|
||||
{ title: 'Spec', detail: 'serial fable spec: pin per-pipeline module split, _save_merge collapse proof, prompts.py move + re-export, lazy boto3 accessor shape, patch-surface + PO_EXPECTED_TOP_LEVEL_MODULES edits, behavior-pin tests' },
|
||||
{ title: 'Implement', detail: 'opus: PO siblings + handler; opus: WO siblings + handler; opus: all test plumbing + bundle-test + README — disjoint files', model: 'opus' },
|
||||
{ title: 'Verify', detail: 'mechanical CHECKS (suite/goldens/ruff/synth/AST/zero cdk+shared+derived diff/ordering greps) + 3 fable lenses (behavior-preservation, boto3-laziness, save-merge-collapse)' },
|
||||
{ title: 'Fix', detail: 'opus fixer, full re-verify, max 3 rounds', model: 'opus' },
|
||||
{ title: 'Package', detail: 'single commit via -F (no push)', model: 'sonnet' },
|
||||
],
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------- constants
|
||||
|
||||
const REPO = '/Users/adammoussa/Documents/repositories/seahaven/procurement-ingest'
|
||||
const BRANCH = 'feature/phase-5-handler-decomposition'
|
||||
let _args = args
|
||||
if (typeof _args === 'string') {
|
||||
try { _args = JSON.parse(_args) } catch (e) { _args = null }
|
||||
}
|
||||
const BASE = (_args && _args.base) || 'main'
|
||||
|
||||
const CONSTRAINTS = `
|
||||
PINNED BEHAVIORAL CONSTRAINTS (docs/refactor-evaluation.md Phase 5 — violating any is a build failure):
|
||||
1. PO SPLIT INTO FLAT SIBLINGS under lambdas/po/email_processor/ (same dir,
|
||||
flat-landing so bare-name imports keep working — the ses_auth/
|
||||
template_parser/derive_all pattern):
|
||||
handler.py -- event loop + fail-closed auth + email_type routing ONLY.
|
||||
extraction.py -- extract_with_claude + _EMAIL_TAG_RE; imports
|
||||
EXTRACTION_PROMPT from prompts. parse_raw_email is
|
||||
ALREADY in shared/email_parsing.py after Phase 3 --
|
||||
import it, do NOT recreate a PO copy.
|
||||
enrichment.py -- enrich_parsed + pad_zip (PO-ONLY; WO has NO enrichment
|
||||
stage). The derived-field block moves here as a PURE
|
||||
code move.
|
||||
telemetry.py -- the EMF ParseMethod emit wrappers (_emit_parse_method_metric
|
||||
and the derived-agreement emit call surface used by
|
||||
enrichment) -- but see constraint 4: derived_fields.py
|
||||
and its shadow telemetry BEHAVIOR are untouchable.
|
||||
persistence.py -- _write_fields / _merge_update / save_*. COLLAPSE the
|
||||
byte-identical save_new_po/save_revision into ONE
|
||||
_save_merge, behavior-identical to BOTH originals
|
||||
INCLUDING the sticky-cancel ConditionExpression guard;
|
||||
save_cancellation stays its own function.
|
||||
2. WO SPLIT is ~5 concerns, NOT 7 (WO has no enrichment stage). Its split MUST
|
||||
keep validate_ai_fallback AND the re.fullmatch(r"[0-9]+", work_order_id) key
|
||||
guard in the handler loop AHEAD of BOTH save_work_order and save_event
|
||||
(the guard protects the DynamoDB partition key + the '#'-delimited comment_id
|
||||
range-key segment), and MUST keep _header_date_iso / comment_id determinism
|
||||
WITH persistence (the retry-idempotent event_id key). Do not move the guard
|
||||
below either save; do not fork comment_id determinism from save_event.
|
||||
3. Move EXTRACTION_PROMPT (the large ~181-line prompt) to prompts.py with
|
||||
cross-reference headers to derived_fields (the trade/site/fiscal rule tables
|
||||
have a second authoritative copy there). KEEP a re-export in handler
|
||||
('from prompts import EXTRACTION_PROMPT') since 4 tests dereference
|
||||
handler.EXTRACTION_PROMPT. Do the same shape for WO if its prompt moves.
|
||||
4. BEHAVIOR-PRESERVATION (immovable, pin with tests):
|
||||
* PO emits ParseMethod=ai_fallback BEFORE the Bedrock call (handler loop:
|
||||
_emit_parse_method_metric fires before extract_with_claude); the
|
||||
ai_fallback_rejected emit is the additive second datapoint on rejection.
|
||||
* WO emits AFTER its gate, with mutually-exclusive ai_fallback /
|
||||
ai_fallback_rejected (a rejected WO email emits ONLY ai_fallback_rejected).
|
||||
* Shadow DerivedFieldAgreement telemetry stays ai_fallback-only.
|
||||
* derived_fields.py and the shadow-telemetry BEHAVIOR are UNTOUCHABLE (the
|
||||
bake is in progress). Moving enrich_parsed into enrichment.py must be a
|
||||
PURE code move -- byte-identical logic, ZERO behavior change.
|
||||
git diff ${BASE}...HEAD -- lambdas/po/email_processor/derived_fields.py
|
||||
MUST be empty.
|
||||
5. SIGNATURES PRESERVED: handler(event, context) unchanged (event shape +
|
||||
return contract identical) on BOTH pipelines; the save_* public contract
|
||||
unchanged (the _save_merge collapse must be behavior-identical to both
|
||||
save_new_po and save_revision -- callers route new_po/revision through it).
|
||||
Goldens UNCHANGED.
|
||||
6. BUNDLING: the Phase 0 top-level cp glob (cp ./*.py or cp <fn>/*.py) plus the
|
||||
AST bundle-consistency test already ship & verify new flat siblings
|
||||
automatically -- but the exact-set pin PO_EXPECTED_TOP_LEVEL_MODULES (and the
|
||||
WO equivalent) must be updated for the new sibling modules IN THE SAME CHANGE,
|
||||
keeping the test's teeth (a new sibling that is NOT added to the expected set,
|
||||
or a commented-out cp, must still fail the AST test).
|
||||
7. LAZY CACHED boto3 accessors in the I/O modules (extraction.py's bedrock,
|
||||
persistence.py's dynamodb, handler.py's s3 -- whatever each module actually
|
||||
uses); PURE modules (enrichment.py logic, prompts.py, telemetry.py if it
|
||||
makes no AWS call) import NO boto3. Update the
|
||||
monkeypatch.setattr(handler, "dynamodb", fake) patch surface in the SAME
|
||||
change -- tests must patch the NEW module's accessor (e.g. the persistence
|
||||
module), everywhere the tests patch it. Preserve the moto-before-handler
|
||||
import ordering (_po_parser_support.py:26-33 -- verify current lines) or the
|
||||
moto-backed suites hit real AWS.
|
||||
8. ZERO cdk/ diff (git diff ${BASE}...HEAD -- cdk/ must be empty) and ZERO
|
||||
lambdas/shared/ diff (Phase 3's shared modules are untouchable here).
|
||||
9. UNTOUCHABLE FILES (git diff ${BASE}...HEAD must be empty for each):
|
||||
lambdas/po/email_processor/derived_fields.py, both template_parser.py, both
|
||||
validate_ai_fallback gate modules, lambdas/shared/*, cdk/*, and
|
||||
lambdas/po/site_extractor/ + both web_ui/ (Phase 5 touches only the two
|
||||
email processors). No opportunistic refactors -- every handler diff is a
|
||||
pure move (delete-here/add-there), an import line, or the _save_merge
|
||||
collapse per the binding spec.
|
||||
10. AWS access is READ-ONLY (get-function, downloading deployed zips via
|
||||
presigned URLs). NEVER cdk deploy, never invoke, never mutate.
|
||||
`
|
||||
|
||||
const PREAMBLE = `
|
||||
You are one of several agents building refactor Phase 5 in the git repo at
|
||||
${REPO} on branch ${BRANCH} (already checked out — do NOT switch branches,
|
||||
do NOT create branches, do NOT commit, NEVER push, do NOT run cdk deploy or
|
||||
touch AWS resources beyond read-only calls).
|
||||
Authoritative spec: docs/refactor-evaluation.md, section "Phase 5 — Handler
|
||||
decomposition + lazy boto3 clients".
|
||||
Work ONLY in the files you are told you own; other agents are concurrently
|
||||
editing other files in this same working tree.
|
||||
${CONSTRAINTS}
|
||||
Your final message is consumed by an orchestrator script, not a human —
|
||||
return only the structured data requested.
|
||||
`
|
||||
|
||||
// ------------------------------------------------------------------ schemas
|
||||
|
||||
const RECON = {
|
||||
type: 'object',
|
||||
required: ['summary', 'facts'],
|
||||
properties: {
|
||||
summary: { type: 'string' },
|
||||
facts: { type: 'array', items: { type: 'string' } },
|
||||
blockers: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const SPEC = {
|
||||
type: 'object',
|
||||
required: ['poSplit', 'woSplit', 'promptMove', 'botoLaziness', 'saveMergeCollapse', 'testPlumbing', 'behaviorPins', 'notes'],
|
||||
properties: {
|
||||
poSplit: { type: 'string', description: 'per PO sibling (handler/extraction/enrichment/telemetry/persistence): exact functions/constants it owns, its imports, and the source file:line ranges moved into it — nothing else may change; state explicitly that parse_raw_email is imported from shared/email_parsing.py and enrich_parsed is a byte-identical move' },
|
||||
woSplit: { type: 'string', description: 'per WO sibling (~5 concerns): exact ownership, and the pinned proof that validate_ai_fallback + the [0-9]+ key guard stay in the handler loop ahead of both saves and _header_date_iso/comment_id determinism stays with persistence' },
|
||||
promptMove: { type: 'string', description: 'prompts.py contents (which prompt(s) move), the cross-reference headers to derived_fields, and the exact re-export line kept in each handler so handler.EXTRACTION_PROMPT still resolves (name the 4 tests that dereference it)' },
|
||||
botoLaziness: { type: 'string', description: 'per module: which boto3 client/resource it needs, the lazy cached accessor shape (module-level None + get_x() cache), which modules import NO boto3, and the exact new monkeypatch target(s) that replace monkeypatch.setattr(handler, "dynamodb", fake) everywhere tests patch it' },
|
||||
saveMergeCollapse: { type: 'string', description: 'the single _save_merge signature + body, with a line-by-line proof it is behavior-identical to BOTH save_new_po and save_revision including the sticky-cancel ConditionExpression path; how the router calls it for new_po vs revision' },
|
||||
testPlumbing: { type: 'string', description: 'every test/support file change: loader/_SIBLING_MODULES resolution for the new siblings, _po_parser_support.py/_wo_parser_support.py edits (moto-before-handler ordering preserved), the monkeypatch patch-surface rewrites, PO_EXPECTED_TOP_LEVEL_MODULES + WO equivalent edits with mutation-detection shapes, and the new behavior-pin tests' },
|
||||
behaviorPins: { type: 'string', description: 'the exact tests/assertions pinning: PO ai_fallback emit precedes the Bedrock invoke; WO emits mutually-exclusive; shadow telemetry ai_fallback-only; _save_merge parity; the WO key-guard ordering' },
|
||||
notes: { type: 'string' },
|
||||
},
|
||||
}
|
||||
|
||||
const IMPL = {
|
||||
type: 'object',
|
||||
required: ['filesChanged', 'summary', 'checksRun'],
|
||||
properties: {
|
||||
filesChanged: { type: 'array', items: { type: 'string' } },
|
||||
summary: { type: 'string' },
|
||||
checksRun: { type: 'string' },
|
||||
blockers: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const CHECKS = {
|
||||
type: 'object',
|
||||
required: ['passed', 'details'],
|
||||
properties: {
|
||||
passed: { type: 'boolean' },
|
||||
details: { type: 'string' },
|
||||
scopeViolations: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const FINDINGS = {
|
||||
type: 'object',
|
||||
required: ['findings'],
|
||||
properties: {
|
||||
findings: {
|
||||
type: 'array',
|
||||
items: {
|
||||
type: 'object',
|
||||
required: ['title', 'severity', 'confirmed', 'evidence', 'fix'],
|
||||
properties: {
|
||||
title: { type: 'string' },
|
||||
severity: { enum: ['critical', 'high', 'medium', 'low'] },
|
||||
confirmed: { type: 'boolean' },
|
||||
evidence: { type: 'string' },
|
||||
fix: { type: 'string' },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------- setup
|
||||
|
||||
phase('Setup')
|
||||
const setup = await agent(`
|
||||
In ${REPO}:
|
||||
1. SEQUENCING GATE — Phases 0, 1, 2 AND 3 must all be on ${BASE}. Phase 5
|
||||
relies on the flat-sibling lambdas/shared/ pattern + the Phase 0/2/3
|
||||
bundling glob that auto-ships new siblings, and parse_raw_email now lives in
|
||||
shared/email_parsing.py after Phase 3. git fetch origin, then pick the base
|
||||
ref: origin/${BASE} if that remote ref exists, otherwise the local branch
|
||||
${BASE} (a stacked local-only base is expected and fine). Verify on the base
|
||||
ref:
|
||||
(a) Phase 0: tests/test_bundle_consistency.py exists
|
||||
(git show <baseref>:tests/test_bundle_consistency.py | head -3);
|
||||
(b) Phase 1: validate_ai_fallback exists in the PO pipeline
|
||||
(git grep validate_ai_fallback <baseref> -- lambdas/po);
|
||||
(c) Phase 2: BOTH cdk/po_stack.py and cdk/wo_stack.py on the base ref
|
||||
contain Code.from_asset("../lambdas") for the email processors
|
||||
(git show <baseref>:cdk/po_stack.py | grep -n '\\.\\./lambdas', same for
|
||||
wo_stack.py);
|
||||
(d) Phase 3: lambdas/shared/ EXISTS on the base ref and the four shared
|
||||
modules are present — ses_auth.py, web_ui_auth.py, email_parsing.py,
|
||||
emf.py (git show <baseref>:lambdas/shared/email_parsing.py | head -3 for
|
||||
each; and confirm parse_raw_email lives in shared/email_parsing.py, NOT
|
||||
in the PO email_processor dir, on the base ref).
|
||||
If ANY is missing — ESPECIALLY Phase 3 (no lambdas/shared/ or no
|
||||
email_parsing.py on base) — STOP with a blocker naming the unmet phase and
|
||||
do nothing else.
|
||||
2. Verify clean working tree (untracked .coverage / .claude/ / the local
|
||||
44 MB lambdas/po/email_processor/package/ dir are fine; any OTHER dirt =
|
||||
blocker, never stash or discard).
|
||||
3. git checkout ${BASE}; then git pull --ff-only ONLY if the branch has an
|
||||
upstream (a local-only base skips the pull — not a blocker); then
|
||||
git checkout -b ${BRANCH}
|
||||
4. gh pr list --state open --json number,title,headRefName (overlap check).
|
||||
Return facts: HEAD sha, per-phase gate evidence (especially the Phase 3
|
||||
shared/ + email_parsing.py proof), open PRs, blockers.
|
||||
`, { label: 'setup:branch', model: 'haiku', schema: RECON })
|
||||
|
||||
if (!setup || (setup.blockers && setup.blockers.length)) {
|
||||
return { aborted: 'setup blockers', blockers: setup ? setup.blockers : ['setup agent died'], facts: setup ? setup.facts : [] }
|
||||
}
|
||||
log(`Branch ${BRANCH} ready off ${BASE}. ${setup.summary}`)
|
||||
|
||||
// ------------------------------------------------------------------- recon
|
||||
|
||||
phase('Recon')
|
||||
const recon = await parallel([
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of the PO email-processor God-handler
|
||||
(lambdas/po/email_processor/handler.py) and its decomposition seams:
|
||||
1. Quote with file:line the exact boundaries of every function/constant that
|
||||
moves and where it lands per constraint 1: EXTRACTION_PROMPT + _EMAIL_TAG_RE
|
||||
+ extract_with_claude (-> extraction.py/prompts.py); _emit_parse_method_metric
|
||||
+ _derived_agreement + _emit_derived_agreement_metric (-> telemetry.py, but
|
||||
note which of these the derived-agreement path needs and whether any lives in
|
||||
derived_fields.py per constraint 4); enrich_parsed + pad_zip (-> enrichment.py);
|
||||
_write_fields + _merge_update + save_new_po + save_revision + save_cancellation
|
||||
(-> persistence.py).
|
||||
2. save_new_po vs save_revision: diff their BODIES line by line and prove they
|
||||
are byte-identical modulo the docstring/log string (the D9 collapse target).
|
||||
Quote both verbatim so the spec can pin _save_merge.
|
||||
3. The handler loop (handler.py:662-758 currently): quote the exact ordering —
|
||||
healthcheck early-return, Records loop, s3.get_object, authenticate_inbound_email,
|
||||
parse_raw_email, try_deterministic_parse, _emit_parse_method_metric (PRE-Bedrock),
|
||||
extract_with_claude, validate_ai_fallback, ai_fallback_rejected emit + continue,
|
||||
po_number guard, enrich_parsed, email_type routing to save_*.
|
||||
4. Which boto3 clients each moving chunk uses (s3, dynamodb resource, bedrock
|
||||
client) and the current module-level client lines (handler.py:27-29).
|
||||
5. The current 'from derived_fields import derive_all',
|
||||
'from ses_auth import authenticate_inbound_email',
|
||||
'from template_parser import ...' import lines and what parse_raw_email's
|
||||
import will become (shared/email_parsing.py after Phase 3 -- confirm on the
|
||||
working tree whether it is already imported from there).
|
||||
6. Which tests dereference handler.EXTRACTION_PROMPT (grep) and which patch
|
||||
handler.dynamodb / handler.bedrock / handler.s3.
|
||||
25-35 precise facts.`,
|
||||
{ label: 'recon:po-handler', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of the WO email-processor God-handler
|
||||
(lambdas/wo/email_processor/handler.py) and its ~5-concern split:
|
||||
1. Quote with file:line every function/constant and the concern it belongs to:
|
||||
EXTRACTION_PROMPT + _EMAIL_TAG_RE + extract_with_bedrock; emit_parse_metric;
|
||||
save_work_order; _header_date_iso + save_event; the handler loop.
|
||||
2. The handler loop (handler.py:350-435 currently): quote the exact ordering —
|
||||
healthcheck, Records loop, s3.get_object, authenticate_inbound_email,
|
||||
parse_raw_email, try_deterministic_parse, extract_with_bedrock,
|
||||
validate_ai_fallback, ai_fallback_rejected emit + continue, emit_parse_metric
|
||||
(POST-gate), the re.fullmatch(r"[0-9]+", work_order_id) key guard,
|
||||
save_work_order, save_event. CRITICAL per constraint 2: pin that the gate +
|
||||
the [0-9]+ key guard both precede BOTH saves, and that comment_id determinism
|
||||
(_header_date_iso + the object-key sha suffix, handler.py:277-347) is coupled
|
||||
to save_event.
|
||||
3. Prove WO has NO enrichment stage (no enrich_parsed equivalent) so its split
|
||||
is 5 concerns not 7.
|
||||
4. WO's EMF emit is mutually-exclusive (rejected email emits ONLY
|
||||
ai_fallback_rejected then continues; accepted email emits emit_parse_metric
|
||||
once AFTER the gate) -- quote the exact lines proving this, contrasted with
|
||||
PO's pre-Bedrock double-count.
|
||||
5. boto3 clients WO uses (handler.py:27-29) and which WO tests patch
|
||||
handler.dynamodb / handler.bedrock and dereference handler.EXTRACTION_PROMPT.
|
||||
6. _wo_parser_support.py bare-sys.path 'import handler' strategy and how it
|
||||
will resolve the new siblings.
|
||||
20-30 precise facts.`,
|
||||
{ label: 'recon:wo-handler', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of the bundling glob, the AST bundle-consistency test, and the
|
||||
test patch/loader surface this phase must rewire:
|
||||
1. tests/test_bundle_consistency.py: quote PO_EXPECTED_TOP_LEVEL_MODULES
|
||||
(currently {"handler","ses_auth","template_parser","derived_fields"} on
|
||||
pre-Phase-3 — read the value ON THIS BRANCH after Phase 3 has added the
|
||||
shared modules), whether a WO_EXPECTED_TOP_LEVEL_MODULES (or equivalent)
|
||||
exists, the _first_party_sibling_imports AST logic, the exact-set assertion,
|
||||
and every mutation-detection assertion (a commented-out cp / a missing module
|
||||
in the expected set must fail). Confirm the Phase 0 cp glob form in both
|
||||
stacks (cp ./*.py or cp <fn>/*.py) auto-ships NEW flat siblings with no cdk
|
||||
edit needed this phase.
|
||||
2. tests/conftest.py importlib loader: how it resolves module paths, the
|
||||
sys.modules save/restore, _SIBLING_MODULES exact current contents (which
|
||||
bare names it lists per pipeline).
|
||||
3. lambdas/po/email_processor/tests/_po_parser_support.py: the independent
|
||||
importlib reimplementation, the load-bearing moto-before-handler import order
|
||||
(~lines 26-33 — quote it), and how handler + its new siblings get loaded.
|
||||
4. lambdas/wo/email_processor/tests/_wo_parser_support.py: same.
|
||||
5. Every place tests do monkeypatch.setattr(handler, "dynamodb"/"bedrock"/"s3",
|
||||
fake) — grep both pipelines' tests and quote each file:line (this is the
|
||||
patch surface constraint 7 says must move to the new module accessors).
|
||||
6. Which tests reference handler.save_new_po / handler.save_revision /
|
||||
handler.enrich_parsed / handler.extract_with_claude / handler.EXTRACTION_PROMPT
|
||||
directly (they may need repointing after the split).
|
||||
20-30 facts.`,
|
||||
{ label: 'recon:bundling-tests', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only AWS recon (region us-east-1, READ-ONLY): for po-email-processor and
|
||||
workorder-email-processor (find exact function names via the stacks/aws lambda
|
||||
list-functions) run aws lambda get-function; download each Code.Location
|
||||
presigned zip to a scratch dir and produce the COMPLETE top-level file list
|
||||
(unzip -l) separated into (a) first-party top-level .py, (b) dependency dirs,
|
||||
(c) anything else; record each function's CodeSha256. This deployed first-party
|
||||
module set is the baseline the post-split staged bundle is judged against: after
|
||||
the split the staged bundle's first-party .py set must be exactly the deployed
|
||||
set MINUS nothing PLUS the new sibling modules (extraction/enrichment/telemetry/
|
||||
persistence/prompts for PO, the WO equivalents) and with the collapsed
|
||||
save_new_po/save_revision still resolvable via imports (no NEW top-level module
|
||||
should vanish that a handler still imports). Confirm parse_raw_email is NOT a
|
||||
top-level module in either deployed email-processor zip if Phase 3 already
|
||||
shipped it from shared/ (it lands flat as email_parsing.py). Return the
|
||||
categorized lists as facts.`,
|
||||
{ label: 'recon:deployed-baseline', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
])
|
||||
|
||||
const reconOk = recon.filter(Boolean)
|
||||
const pack = reconOk.map(r => `## ${r.summary}\n${r.facts.join('\n')}`).join('\n\n')
|
||||
const reconBlockers = reconOk.flatMap(r => r.blockers || [])
|
||||
.filter(b => b && !/^\s*(none|n\/a)\b/i.test(b))
|
||||
log(`Recon complete: ${reconOk.length}/4 mappers, ${reconBlockers.length} advisory notes`)
|
||||
// Recon "blockers" here are downstream guidance (verify the WO dynamodb
|
||||
// monkeypatch surface per constraint 7 before persistence.py's split;
|
||||
// compare the post-split staged bundle against the local pre-Phase-5 bundle,
|
||||
// NOT the stale pre-Phase-3 deployed AWS zip), NOT stop conditions — main-loop
|
||||
// verified Phase 3 is on base and the seams move cleanly. The real gates are
|
||||
// pytest-green (catches any missed monkeypatch surface) and the bundle-parity
|
||||
// verifier. Fold the notes into the spec context instead of aborting.
|
||||
const reconAdvisories = reconBlockers.length
|
||||
? `\n\nRECON ADVISORIES (recon flagged these; they are downstream verification guidance — the impl must update the full dynamodb/bedrock/s3 monkeypatch surface (constraint 7) so no test breaks, and the parity check compares against the local pre-Phase-5 staged bundle not the pre-Phase-3 deployed zip — NOT reasons to stop; pytest-green + bundle-parity are the real gates):\n- ${reconBlockers.join('\n- ')}`
|
||||
: ''
|
||||
|
||||
// -------------------------------------------------------------------- spec
|
||||
|
||||
phase('Spec')
|
||||
const spec = await agent(`${PREAMBLE}
|
||||
You are the SPEC agent — the single authority that pins every contested
|
||||
decision BEFORE parallel implementation (parallel leaves cannot see each
|
||||
other's choices). Using the recon pack below plus your own reads of the actual
|
||||
files, produce the binding implementation spec:
|
||||
- poSplit: per constraint 1's five PO siblings — exact functions/constants each
|
||||
owns, the imports each needs, and the source line ranges moved. State
|
||||
explicitly: parse_raw_email is imported from shared/email_parsing.py (NOT
|
||||
recreated); enrich_parsed + its derived-field block move into enrichment.py as
|
||||
a BYTE-IDENTICAL logic move (constraint 4). Resolve where the derived-agreement
|
||||
emit surface lives (telemetry.py vs left in enrichment) WITHOUT touching
|
||||
derived_fields.py.
|
||||
- woSplit: per constraint 2's ~5 WO concerns — ownership, plus the explicit pin
|
||||
that validate_ai_fallback + the [0-9]+ key guard stay in the handler loop
|
||||
AHEAD of both saves and _header_date_iso/comment_id determinism stays coupled
|
||||
to persistence (save_event). WO has NO enrichment stage.
|
||||
- promptMove: prompts.py contents (PO prompt for sure; WO prompt too if it moves),
|
||||
the cross-reference headers to derived_fields, and the EXACT re-export line
|
||||
each handler keeps so handler.EXTRACTION_PROMPT still resolves (name the 4 PO
|
||||
tests + any WO tests that dereference it).
|
||||
- botoLaziness: per module, the lazy cached boto3 accessor shape (module-level
|
||||
None cache + get_x()); which modules import NO boto3 (pure: enrichment logic,
|
||||
prompts, telemetry if it emits via print only); and the EXACT new monkeypatch
|
||||
target(s) replacing monkeypatch.setattr(handler, "dynamodb", fake) at every
|
||||
test site recon found — pick ONE consistent rule (patch the owning module's
|
||||
accessor/attribute) and state why. Preserve the moto-before-handler ordering.
|
||||
- saveMergeCollapse: the single _save_merge signature + body with a line-by-line
|
||||
proof it is behavior-identical to BOTH save_new_po and save_revision including
|
||||
the sticky-cancel ConditionExpression path; how the router dispatches new_po
|
||||
vs revision through it; save_cancellation stays separate.
|
||||
- testPlumbing: every file, every edit — _SIBLING_MODULES additions for the new
|
||||
bare names, _po_parser_support.py / _wo_parser_support.py loader edits (moto
|
||||
ordering preserved), the monkeypatch patch-surface rewrites, repointing any
|
||||
test that referenced handler.save_new_po/enrich_parsed/etc. to the new module,
|
||||
PO_EXPECTED_TOP_LEVEL_MODULES + the WO equivalent updated to the new sibling
|
||||
set (with mutation shapes: a missing sibling in the set, or a commented-out cp,
|
||||
must FAIL the AST test), and the NEW behavior-pin tests.
|
||||
- behaviorPins: the exact new tests/assertions pinning constraint 4 & 5 — PO
|
||||
ai_fallback emit precedes the Bedrock invoke (a throttle test is the cleanest
|
||||
proof), WO emits mutually-exclusive, shadow telemetry ai_fallback-only,
|
||||
_save_merge parity to both originals, WO key-guard ordering ahead of both saves.
|
||||
Recon pack:\n${pack}${reconAdvisories}`,
|
||||
{ label: 'spec:pin-decomposition', phase: 'Spec', schema: SPEC })
|
||||
|
||||
if (!spec) return { aborted: 'spec agent died — rerun workflow', reconBlockers }
|
||||
const specBlock = `BINDING SPEC (from the spec agent — implement EXACTLY this):\n${JSON.stringify(spec, null, 2)}`
|
||||
log('Spec pinned: PO split, WO split, prompt move, boto3 laziness, _save_merge collapse, test plumbing, behavior pins')
|
||||
|
||||
// --------------------------------------------------------------- implement
|
||||
|
||||
phase('Implement')
|
||||
const impl = await parallel([
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: lambdas/po/email_processor/ EXCEPT its tests/ directory (another agent
|
||||
owns all test and support files). Do not touch cdk/, lambdas/wo/,
|
||||
lambdas/shared/, or README.
|
||||
Task: execute the PO split per spec.poSplit + spec.promptMove +
|
||||
spec.botoLaziness + spec.saveMergeCollapse:
|
||||
1. Create prompts.py (EXTRACTION_PROMPT + cross-ref headers); keep the
|
||||
re-export line in handler.py.
|
||||
2. Create extraction.py (extract_with_claude + _EMAIL_TAG_RE, lazy bedrock
|
||||
accessor, imports EXTRACTION_PROMPT from prompts and parse_raw_email from
|
||||
the shared email_parsing module).
|
||||
3. Create enrichment.py (enrich_parsed + pad_zip + the derived-field block as a
|
||||
BYTE-IDENTICAL logic move — derived_fields.py stays untouched; no boto3).
|
||||
4. Create telemetry.py (the EMF ParseMethod emit wrappers per spec) — pure
|
||||
(print-only, no boto3) unless spec says otherwise.
|
||||
5. Create persistence.py (_write_fields, _merge_update, the collapsed _save_merge
|
||||
behavior-identical to BOTH save_new_po and save_revision incl. the sticky-
|
||||
cancel guard, save_cancellation; lazy dynamodb accessor).
|
||||
6. Rewrite handler.py down to the event loop + auth + routing, importing from
|
||||
the new siblings; keep handler(event, context) signature + the healthcheck
|
||||
early-return + the PRE-Bedrock ai_fallback emit ordering EXACTLY.
|
||||
Every change is a pure move / import line / the _save_merge collapse — no
|
||||
opportunistic refactors (constraint 9). derived_fields.py diff MUST stay empty.
|
||||
Run before returning: ruff check lambdas/po && ruff format lambdas/po --check,
|
||||
plus an import smoke: python3 -c with sys.path prepended for lambdas/shared +
|
||||
the PO function dir, importing every new module + handler (tests are NOT yours
|
||||
to run — the plumbing agent lands them in parallel).
|
||||
${specBlock}`,
|
||||
{ label: 'impl:po-siblings', model: 'opus', phase: 'Implement', schema: IMPL }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: lambdas/wo/email_processor/ EXCEPT its tests/ directory (another agent
|
||||
owns all test and support files). Do not touch cdk/, lambdas/po/,
|
||||
lambdas/shared/, or README.
|
||||
Task: execute the WO ~5-concern split per spec.woSplit + spec.promptMove +
|
||||
spec.botoLaziness:
|
||||
1. Create prompts.py if the WO prompt moves (re-export kept in handler).
|
||||
2. Create extraction.py (extract_with_bedrock + _EMAIL_TAG_RE, lazy bedrock).
|
||||
3. Create telemetry.py (emit_parse_metric) — pure unless spec says otherwise.
|
||||
4. Create persistence.py (save_work_order, _header_date_iso, save_event —
|
||||
comment_id determinism stays coupled here; lazy dynamodb).
|
||||
5. Rewrite handler.py to the event loop + auth + routing, KEEPING
|
||||
validate_ai_fallback + the re.fullmatch(r"[0-9]+", work_order_id) key guard
|
||||
in the loop AHEAD of BOTH saves (constraint 2), the POST-gate mutually-
|
||||
exclusive emit ordering, the healthcheck early-return, and handler(event,
|
||||
context) signature EXACTLY.
|
||||
Pure moves / imports only (constraint 9). No enrichment stage exists — do not
|
||||
invent one.
|
||||
Run before returning: ruff check lambdas/wo && ruff format lambdas/wo --check,
|
||||
plus an import smoke: python3 -c with sys.path prepended for lambdas/shared +
|
||||
the WO function dir, importing every new module + handler.
|
||||
${specBlock}`,
|
||||
{ label: 'impl:wo-siblings', model: 'opus', phase: 'Implement', schema: IMPL }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: all test and support files (tests/ at repo root including
|
||||
tests/test_bundle_consistency.py and tests/conftest.py,
|
||||
lambdas/po/email_processor/tests/, lambdas/wo/email_processor/tests/) and
|
||||
README.md ONLY.
|
||||
Task A: apply spec.testPlumbing in full — _SIBLING_MODULES additions for the new
|
||||
bare names, _po_parser_support.py / _wo_parser_support.py loader edits
|
||||
(PRESERVING the moto-before-handler ordering comment + import), rewrite the
|
||||
monkeypatch patch surface everywhere tests patch handler.dynamodb/bedrock/s3 to
|
||||
the new module accessors per spec.botoLaziness, repoint any test that referenced
|
||||
handler.save_new_po / handler.save_revision / handler.enrich_parsed /
|
||||
handler.extract_with_claude to the new modules (KEEP handler.EXTRACTION_PROMPT
|
||||
resolving via the re-export — do NOT repoint those 4 tests), and update
|
||||
PO_EXPECTED_TOP_LEVEL_MODULES + the WO equivalent to the new sibling set WITHOUT
|
||||
losing teeth (constraint 6 — a missing sibling in the set or a commented-out cp
|
||||
must FAIL the AST test; keep existing mutation tests green).
|
||||
Task B: add the NEW behavior-pin tests per spec.behaviorPins — PO ai_fallback
|
||||
emit precedes the Bedrock invoke (throttle-based proof), WO emits mutually-
|
||||
exclusive, shadow telemetry ai_fallback-only, _save_merge parity to both
|
||||
originals, WO key-guard ordering ahead of both saves.
|
||||
Task C: README — update the repo-layout / module map for the new PO+WO sibling
|
||||
modules (the flat-landing import rule already ships them via the Phase 0 glob),
|
||||
note the save_new_po/save_revision collapse into _save_merge and prompts.py.
|
||||
Match existing README style; goldens stay UNCHANGED.
|
||||
Run before returning: pytest -q --no-cov at repo root (must be green against the
|
||||
OTHER agents' edits — they land in parallel; poll by re-running up to ~10 min
|
||||
before reporting a blocker) and ruff check on every file you touched.
|
||||
${specBlock}`,
|
||||
{ label: 'impl:test-plumbing-readme', model: 'opus', phase: 'Implement', schema: IMPL }),
|
||||
])
|
||||
|
||||
const implOk = impl.filter(Boolean)
|
||||
const implBlockers = implOk.flatMap(r => r.blockers || [])
|
||||
log(`Implement complete: ${implOk.length}/3 agents, blockers: ${implBlockers.length}`)
|
||||
|
||||
// ---------------------------------------------------- verify + fix loop
|
||||
|
||||
const EXPECTED_SCOPE = [
|
||||
'lambdas/po/email_processor/',
|
||||
'lambdas/wo/email_processor/',
|
||||
'tests/',
|
||||
'README.md',
|
||||
]
|
||||
|
||||
const mechanicalPrompt = `${PREAMBLE}
|
||||
Independent re-verification — trust nothing self-reported. Run ALL gates,
|
||||
quoting failures verbatim:
|
||||
1. pytest -q --no-cov (repo root, all three roots green; GOLDENS UNCHANGED —
|
||||
git diff ${BASE}...HEAD on any golden .json/.eml fixture must be empty).
|
||||
2. ruff check . && ruff format --check .
|
||||
3. cd cdk && npx cdk synth po-ingest -q && npx cdk synth workorder-ingest -q
|
||||
(artifact-id selectors, NOT stack_name). The Docker bundling runs — confirm
|
||||
each staged email-processor asset now contains the new sibling modules.
|
||||
4. AST BUNDLE TEST: the test_bundle_consistency.py suite is GREEN and its teeth
|
||||
hold — on a scratch copy, comment out the cp glob line and drop a sibling
|
||||
from PO_EXPECTED_TOP_LEVEL_MODULES (and the WO equivalent); EACH mutation
|
||||
must FAIL the test. Restore.
|
||||
5. ZERO-DIFF UNTOUCHABLES (each must output NOTHING):
|
||||
git diff ${BASE}...HEAD -- cdk/
|
||||
git diff ${BASE}...HEAD -- lambdas/shared/
|
||||
git diff ${BASE}...HEAD -- lambdas/po/email_processor/derived_fields.py
|
||||
git diff ${BASE}...HEAD -- lambdas/po/email_processor/template_parser.py
|
||||
git diff ${BASE}...HEAD -- lambdas/wo/email_processor/template_parser.py
|
||||
plus both validate_ai_fallback gate modules (resolve their filenames first)
|
||||
and lambdas/po/site_extractor/ + both web_ui/.
|
||||
6. SIGNATURES: grep proves handler(event, context) unchanged on both pipelines
|
||||
and the healthcheck early-return + return {"statusCode": 200, ...} contract
|
||||
intact. handler.EXTRACTION_PROMPT still resolves (the re-export line is
|
||||
present in both handlers).
|
||||
7. ORDERING PINS (grep with line numbers):
|
||||
- PO: _emit_parse_method_metric / the ai_fallback emit still PRECEDES the
|
||||
extract_with_claude (Bedrock) invoke in the handler loop.
|
||||
- WO: the emit stays POST-gate and mutually-exclusive (rejected path emits
|
||||
ONLY ai_fallback_rejected then continue); the re.fullmatch(r"[0-9]+", ...)
|
||||
key guard still sits AHEAD of BOTH save_work_order and save_event.
|
||||
8. BOTO3 LAZINESS: grep proves the pure modules (PO enrichment.py, prompts.py,
|
||||
telemetry if print-only; WO equivalents) import NO boto3, and the I/O modules
|
||||
use lazy cached accessors (no module-level eager client that a test cannot
|
||||
patch). No monkeypatch.setattr(handler, "dynamodb"/... ) remains pointing at
|
||||
a now-empty handler attribute.
|
||||
9. git status --porcelain scope check: every modified/added/deleted path under
|
||||
${EXPECTED_SCOPE.join(', ')} (untracked .coverage/.claude/package/ tolerated).
|
||||
passed=true only if all green. YOU MAY NOT edit files.`
|
||||
|
||||
const lenses = [
|
||||
{ key: 'behavior-preservation', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — behavior-preservation lens. The decomposition must not
|
||||
change one observable byte of metric or telemetry behavior. (1) METRIC ORDERING:
|
||||
read the post-split PO handler loop and prove _emit_parse_method_metric fires
|
||||
BEFORE extract_with_claude (so a Bedrock-side throttle still records ai_fallback)
|
||||
and that ai_fallback_rejected is still the additive second datapoint; then the
|
||||
WO loop and prove the emit is POST-gate and MUTUALLY-EXCLUSIVE (a rejected email
|
||||
emits ONLY ai_fallback_rejected, an accepted one emits once after the gate).
|
||||
Construct the emitted EMF envelope from each moved emitter and diff it against
|
||||
${BASE}'s output — namespace, dimension-set list [["ParseMethod"],["ParseMethod",
|
||||
"TemplateId"]], property keys/types identical. (2) SHADOW TELEMETRY: prove
|
||||
DerivedFieldAgreement is still emitted ONLY on the ai_fallback path after
|
||||
enrich_parsed moved to enrichment.py, and that
|
||||
git diff ${BASE}...HEAD -- derived_fields.py is EMPTY (the enrich_parsed move is
|
||||
byte-identical logic). (3) ROUTING: prove email_type routing (cancellation/
|
||||
revision/new_po for PO; the WO save_work_order + save_event pair) still reaches
|
||||
the same saves in the same order. confirmed=true only with a concrete
|
||||
file:line proof or a sample-emission diff.` },
|
||||
{ key: 'boto3-laziness', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — boto3-laziness lens. (1) PURE MODULES: prove the modules
|
||||
constraint 7 calls pure (PO enrichment.py, prompts.py, telemetry if print-only;
|
||||
WO equivalents) import NO boto3 at all — grep + read. A stray 'import boto3' or
|
||||
eager client in a "pure" module is a finding. (2) LAZY ACCESSORS: in the I/O
|
||||
modules (extraction bedrock, persistence dynamodb, handler s3) prove the client
|
||||
is created lazily and cached (module-level None + get_x()), not eagerly at import
|
||||
— an eager module-level client that tests cannot patch is a finding. (3)
|
||||
PATCH-SURFACE COMPLETENESS: enumerate EVERY test that previously did
|
||||
monkeypatch.setattr(handler, "dynamodb"/"bedrock"/"s3", fake) and prove each now
|
||||
patches the correct NEW module accessor — a test that still patches a now-dead
|
||||
handler attribute silently exercises the REAL client (or moto-misses) and is a
|
||||
critical finding. (4) MOTO ORDERING: prove the moto-before-handler import order
|
||||
survived in _po_parser_support.py and _wo_parser_support.py — reorder-and-run to
|
||||
confirm the suites would hit real AWS without it. confirmed=true only with
|
||||
file:line or reproduced-failure evidence.` },
|
||||
{ key: 'save-merge-collapse', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — save-merge-collapse lens. The one _save_merge that replaces
|
||||
save_new_po AND save_revision must be byte-behavior-identical to BOTH. (1) Read
|
||||
_save_merge and BOTH ${BASE} originals; prove line-by-line the field-building,
|
||||
the _merge_update call, and the sticky-cancel path are identical (incl. the
|
||||
ConditionExpression "attribute_not_exists(po_status) OR po_status <>
|
||||
:__cancelled_marker" and the ConditionalCheckFailedException fallback that
|
||||
re-writes WITHOUT po_status/cancelled_at). (2) Prove the router dispatches
|
||||
email_type=="revision" and the new_po else-branch both through _save_merge, and
|
||||
that save_cancellation stayed SEPARATE and unchanged. (3) Construct a scenario
|
||||
where the collapse could diverge: a revision landing on a Cancelled PO, a new_po
|
||||
with po_status=None, a new_po carrying a non-cancelled status onto a Cancelled
|
||||
skeleton — and prove _save_merge behaves exactly as the original would have for
|
||||
each. (4) Confirm the save_* public contract callers rely on is unchanged and
|
||||
the goldens still pass. confirmed=true only with a concrete divergence sketch
|
||||
or a line-by-line equivalence proof.` },
|
||||
]
|
||||
|
||||
let round = 0
|
||||
let checks = null
|
||||
let confirmed = []
|
||||
while (round < 3) {
|
||||
phase('Verify')
|
||||
const results = await parallel([
|
||||
() => agent(mechanicalPrompt, { label: `verify:mechanical-r${round}`, model: 'sonnet', phase: 'Verify', schema: CHECKS }),
|
||||
...lenses.map(l => () =>
|
||||
agent(l.prompt, { label: `verify:${l.key}-r${round}`, phase: 'Verify', schema: FINDINGS })),
|
||||
])
|
||||
checks = results[0]
|
||||
confirmed = results.slice(1).filter(Boolean)
|
||||
.flatMap(r => r.findings || [])
|
||||
.filter(f => f.confirmed && f.severity !== 'low')
|
||||
const green = checks && checks.passed
|
||||
log(`Verify round ${round}: mechanical ${checks && checks.passed ? 'GREEN' : 'RED'}, confirmed findings: ${confirmed.length}`)
|
||||
if (green && confirmed.length === 0) break
|
||||
|
||||
round += 1
|
||||
if (round >= 3) break
|
||||
phase('Fix')
|
||||
await agent(`${PREAMBLE}
|
||||
You are the fix agent — you may edit files under: ${EXPECTED_SCOPE.join(', ')}.
|
||||
Fix EVERY item below minimally; the binding spec and 10 pinned constraints
|
||||
still hold (a finding that conflicts with a constraint is reported, not "fixed"
|
||||
— the constraint wins, esp. constraint 4's derived_fields untouchability +
|
||||
byte-identical enrich move, constraint 5's signature/goldens preservation, and
|
||||
constraint 8's zero cdk/shared diff). Re-run the specific failing gate/test per
|
||||
fix.
|
||||
MECHANICAL:\n${checks ? checks.details : '(agent died — rerun all gates)'}
|
||||
CONFIRMED FINDINGS:\n${JSON.stringify(confirmed, null, 2)}
|
||||
${specBlock}`,
|
||||
{ label: `fix:round-${round}`, model: 'opus', phase: 'Fix', schema: IMPL })
|
||||
}
|
||||
|
||||
const verifyClean = checks && checks.passed && confirmed.length === 0
|
||||
if (!verifyClean) {
|
||||
return {
|
||||
status: 'NEEDS ATTENTION — verify not clean after 3 rounds; branch left uncommitted',
|
||||
branch: BRANCH,
|
||||
mechanical: checks,
|
||||
unresolvedFindings: confirmed,
|
||||
implBlockers,
|
||||
reconBlockers,
|
||||
spec,
|
||||
}
|
||||
}
|
||||
|
||||
// ----------------------------------------------------------------- package
|
||||
|
||||
phase('Package')
|
||||
const commit = await agent(`${PREAMBLE.replace('do NOT commit, ', '')}
|
||||
YOU are the commit agent:
|
||||
1. Read ~/Documents/repositories/seahaven/engineering-handbook/commit-messages.md
|
||||
and follow it exactly.
|
||||
2. git add only paths under: ${EXPECTED_SCOPE.join(', ')} and
|
||||
.claude/workflows/phase-5-handler-decomposition.js. NOT .coverage, NOT
|
||||
package/. Verify the staged set with git status — the new sibling files AND
|
||||
the deletions of the moved-out code from the handlers MUST be staged.
|
||||
3. ONE commit; write the message to /tmp/phase5-commit-msg.txt and use
|
||||
git commit -F /tmp/phase5-commit-msg.txt (backticks in -m get eaten by zsh).
|
||||
Suggested subject:
|
||||
"feat: decompose email-processor handlers into flat siblings + lazy boto3 clients (refactor phase 5)"
|
||||
Body: the PO 5-way split (handler/extraction/enrichment/telemetry/persistence)
|
||||
with the save_new_po/save_revision -> _save_merge collapse one-liner, the WO
|
||||
~5-concern split keeping the gate+key-guard in the loop, prompts.py + the
|
||||
handler.EXTRACTION_PROMPT re-export, the lazy-boto3 + patch-surface move, and
|
||||
the behavior-preservation pins (PO pre-Bedrock emit, WO mutually-exclusive,
|
||||
shadow telemetry ai_fallback-only, derived_fields untouched). NO AI
|
||||
attribution / Co-Authored-By lines.
|
||||
4. Do NOT push. Return commit sha + shortstat in summary.`,
|
||||
{ label: 'package:commit', model: 'sonnet', phase: 'Package', schema: IMPL })
|
||||
|
||||
return {
|
||||
status: 'BUILT — committed locally, NOT pushed',
|
||||
branch: BRANCH,
|
||||
base: BASE,
|
||||
commit: commit ? commit.summary : 'commit agent died — commit manually',
|
||||
spec: { poSplit: spec.poSplit, woSplit: spec.woSplit, saveMergeCollapse: spec.saveMergeCollapse, botoLaziness: spec.botoLaziness, notes: spec.notes },
|
||||
implementation: implOk.map(r => r.summary),
|
||||
filesChanged: implOk.flatMap(r => r.filesChanged),
|
||||
verifyRounds: round + 1,
|
||||
blockers: implBlockers.concat(reconBlockers),
|
||||
outstandingGates: [
|
||||
'/sh-security-review (MANDATORY before push — the untrusted-input parse/extract/validate-gate/auth-routing code is being MOVED across modules; CLAUDE.md gates untrusted-input handling changes and a move still touches the surface. Run on the committed diff, re-run after any post-review fix)',
|
||||
'cross-family cross_review.py NOT required (handler(event, context) event/return signatures unchanged and no IAM change — internal module moves only)',
|
||||
'push + PR + gh pr checks green',
|
||||
'deploy-then-merge: full suite goldens unchanged, smoke green, ONE live email per pipeline (PO + WO) showing the correct ParseMethod, both the fallback + rejected alarm series behaving; the post-merge CI redeploy is a fresh asset (new sibling files) so confirm the smoke gate + AST bundle test caught any missing-module regression BEFORE merge',
|
||||
],
|
||||
}
|
||||
585
.claude/workflows/phase-6-site-extractor.js
Normal file
585
.claude/workflows/phase-6-site-extractor.js
Normal file
|
|
@ -0,0 +1,585 @@
|
|||
export const meta = {
|
||||
name: 'phase-6-site-extractor',
|
||||
description: 'Phase 6 of the procurement-ingest refactor (docs/refactor-evaluation.md): site_extractor reconciliation — end the three-way site_code contradiction. extract_site_code (lambdas/po/site_extractor/handler.py:34) already prefers record["site_code"] but validates it with the digit-requiring, prefix-anchored SITE_CODE_PATTERN (line 23) which rejects all-letter codes like KLAL (permanent pending-review rows) and accepts overlong junk like DLI6X/SNY55. Fix: validate the direct field with the canonical derived_fields shape + skip-list semantics (fullmatch), import derive_site_code for the fallback path, ship derived_fields.py into the site_extractor asset via the Phase 2/3 bundling mechanism (Phase 3 left site_extractor from_asset UNTOUCHED on purpose), delete the dead [A-Z]{4,5} regex ladder (line 62). derived_fields.py itself stays byte-untouched. Characterization tests pin current behavior first, then flip to fixed in the same PR. Gated on the shadow bake concluding. Validated field can be ai_fallback-sourced, so push is gated on /sh-security-review. Committed locally, never pushed.',
|
||||
phases: [
|
||||
{ title: 'Setup', detail: 'HARD-GATE on shadow-bake conclusion (args {bakeConcluded:true}) + Phase 3 on base; branch feature/phase-6-site-extractor', model: 'haiku' },
|
||||
{ title: 'Recon', detail: '3 mappers: site_extractor handler + the digit-pattern defect, derived_fields canonical shape/skip-list/derive_site_code, post-Phase-3 bundling sites + bundle-consistency test + backfill script (read-only)' },
|
||||
{ title: 'Spec', detail: 'serial fable spec: pin the handler fix (canonical fullmatch + skip-list), the site_extractor bundling change, backfill repoint-or-delete, the characterization-first-then-flip test plan, bundle/parity rules' },
|
||||
{ title: 'Implement', detail: 'opus: site_extractor handler + new characterization tests; sonnet: cdk site_extractor from_asset + test_bundle_consistency; opus: backfill_sites.py + README — disjoint files', model: 'opus' },
|
||||
{ title: 'Verify', detail: 'mechanical gates (suite green, ruff, synth, asset CONTAINS derived_fields.py, tests flipped to fixed, zero derived_fields diff) + 3 fable lenses (shape-parity, bundling, regression)' },
|
||||
{ title: 'Fix', detail: 'opus fixer, full re-verify, max 3 rounds', model: 'opus' },
|
||||
{ title: 'Package', detail: 'single commit via -F (no push)', model: 'sonnet' },
|
||||
],
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------- constants
|
||||
|
||||
const REPO = '/Users/adammoussa/Documents/repositories/seahaven/procurement-ingest'
|
||||
const BRANCH = 'feature/phase-6-site-extractor'
|
||||
let _args = args
|
||||
if (typeof _args === 'string') {
|
||||
try { _args = JSON.parse(_args) } catch (e) { _args = null }
|
||||
}
|
||||
const BASE = (_args && _args.base) || 'main'
|
||||
|
||||
const CONSTRAINTS = `
|
||||
PINNED BEHAVIORAL CONSTRAINTS (docs/refactor-evaluation.md Phase 6 + §4 item 6 — violating any is a build failure):
|
||||
1. THE DEFECT is in lambdas/po/site_extractor/handler.py: extract_site_code
|
||||
(line 34) already prefers record["site_code"] (line 36), but validates it
|
||||
with SITE_CODE_PATTERN = re.compile(r"[A-Z]{2,4}\\d{1,2}") (line 23) applied
|
||||
via .match (prefix-anchored, digit-REQUIRING). That pattern REJECTS
|
||||
all-letter codes like KLAL — so a KLAL-class site can NEVER self-register
|
||||
and becomes a permanent pending-review row — and ACCEPTS overlong junk like
|
||||
DLI6X / SNY55 (prefix match, no end anchor). THE FIX: validate the direct
|
||||
record["site_code"] field with the CANONICAL derived_fields shape + skip-list
|
||||
semantics using FULLMATCH (derived_fields.py: _STRICT_CODE_RE at line 50 =
|
||||
re.compile(r"[A-Z][A-Z0-9]{2,4}") + _is_valid_code at line 97 = "not in _SKIP
|
||||
and >=2 alphabetic chars", _SKIP at line 69). Import derive_site_code
|
||||
(derived_fields.py:259) for the FALLBACK path (ship_to / line_items). DELETE
|
||||
the bespoke regex ladder — the line 62 alternation
|
||||
r"^([A-Z]{1,4}[0-9]{1,2}|[A-Z]{4,5})\\b" whose [A-Z]{4,5} arm is dead code
|
||||
(it can never survive the digit-requiring SITE_CODE_PATTERN.match on the very
|
||||
next line) — and every other SITE_CODE_PATTERN reference. NET EXPECTED
|
||||
BEHAVIOR: KLAL is ACCEPTED, DLI6X and SNY55 are REJECTED.
|
||||
2. SHIP derived_fields.py INTO the site_extractor Lambda asset. Add the cp/root
|
||||
bundling change for site_extractor's from_asset in cdk/po_stack.py (currently
|
||||
lines 684-686: Code.from_asset("../lambdas/po/site_extractor",
|
||||
exclude=["**/__pycache__/**"]) — Phase 3 left this UNTOUCHED on purpose).
|
||||
THIS phase makes lambdas/po/email_processor/derived_fields.py reachable there,
|
||||
MIRRORING the Phase 2/3 mechanism the two email processors use (widened
|
||||
asset root + a scoped cp so the module lands FLAT in /asset-output so the
|
||||
bare-name import 'from derived_fields import derive_site_code' resolves).
|
||||
KEEP the __pycache__ / tests excludes intact; do NOT ship tests/ or a stale
|
||||
package/ into the zip. The spec agent pins the exact root + cp form (Docker
|
||||
bundling vs a no-Docker local staging — ONE mechanism, exact code).
|
||||
3. Keep shape/skip validation ON the record["site_code"] field even though it
|
||||
is ai_fallback-SOURCED (the LLM value is authoritative during/after the bake)
|
||||
— this is validated authority, NOT blind trust and NOT a regex bypass. Keep
|
||||
parse_address (line 69) AND the pending-review write flow (write_pending_review
|
||||
line 223 + the handler else-branch lines 283-290) BYTE-UNCHANGED.
|
||||
4. Repoint scripts/backfill_sites.py at derive_site_code (it currently does
|
||||
'from handler import extract_site_code, parse_address, upsert_site' via a
|
||||
sys.path hack) — OR DELETE it entirely (one-time backfill script; deletion is
|
||||
acceptable and PREFERRED if simpler). Pick one and state why.
|
||||
5. CHARACTERIZATION TESTS FIRST. site_extractor is 0% covered today (§2). Write
|
||||
tests that PIN CURRENT behavior first — INCLUDING the KLAL rejection
|
||||
divergence and the overlong-junk (DLI6X / SNY55) acceptance, parse_address
|
||||
variants, and the pending-review fallback — then FLIP the assertions to the
|
||||
FIXED behavior in the SAME PR, so the change is provably intentional. The
|
||||
final committed suite asserts FIXED behavior (KLAL accepted, DLI6X/SNY55
|
||||
rejected); the characterization-of-old-behavior stage is a build step, not a
|
||||
red suite left behind.
|
||||
6. derived_fields.py itself stays UNTOUCHED — import it, do NOT edit it.
|
||||
git diff ${BASE}...HEAD -- lambdas/po/email_processor/derived_fields.py MUST
|
||||
be empty. The shadow-bake authority model must not shift in this phase.
|
||||
7. AWS access is READ-ONLY (get-function, downloading the deployed site_extractor
|
||||
zip via presigned URL to confirm the asset contents). NEVER cdk deploy, never
|
||||
invoke, never mutate. No push, no PR, no cdk deploy in this workflow.
|
||||
`
|
||||
|
||||
const PREAMBLE = `
|
||||
You are one of several agents building refactor Phase 6 in the git repo at
|
||||
${REPO} on branch ${BRANCH} (already checked out — do NOT switch branches,
|
||||
do NOT create branches, do NOT commit, NEVER push, do NOT run cdk deploy or
|
||||
touch AWS resources beyond read-only calls).
|
||||
Authoritative spec: docs/refactor-evaluation.md, section "Phase 6 —
|
||||
site_extractor reconciliation" and section "§4" item 6 (site_extractor
|
||||
characterization). The doc wins on any conflict.
|
||||
Work ONLY in the files you are told you own; other agents are concurrently
|
||||
editing other files in this same working tree.
|
||||
${CONSTRAINTS}
|
||||
Your final message is consumed by an orchestrator script, not a human —
|
||||
return only the structured data requested.
|
||||
`
|
||||
|
||||
// ------------------------------------------------------------------ schemas
|
||||
|
||||
const RECON = {
|
||||
type: 'object',
|
||||
required: ['summary', 'facts'],
|
||||
properties: {
|
||||
summary: { type: 'string' },
|
||||
facts: { type: 'array', items: { type: 'string' } },
|
||||
blockers: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const SPEC = {
|
||||
type: 'object',
|
||||
required: ['handlerFix', 'bundlingEdit', 'backfillDecision', 'characterizationTests', 'parityRules', 'notes'],
|
||||
properties: {
|
||||
handlerFix: { type: 'string', description: 'the exact edit to lambdas/po/site_extractor/handler.py: how the direct record["site_code"] field is validated with the canonical derived_fields fullmatch shape + skip-list, the derive_site_code import + fallback wiring, every line deleted (SITE_CODE_PATTERN def, the line-62 alternation, all SITE_CODE_PATTERN references), and an explicit statement that parse_address + write_pending_review + the pending-review else-branch are byte-unchanged. Prove KLAL accepted, DLI6X/SNY55 rejected under the new logic.' },
|
||||
bundlingEdit: { type: 'string', description: 'the complete replacement from_asset block for site_extractor in cdk/po_stack.py: widened asset root, the scoped cp form staging both the site_extractor *.py AND lambdas/po/email_processor/derived_fields.py flat, the __pycache__/tests/package excludes, and whether it uses Docker bundling or a no-Docker local staging — ONE mechanism, exact code, mirroring the Phase 2/3 email-processor form.' },
|
||||
backfillDecision: { type: 'string', description: 'repoint scripts/backfill_sites.py at derive_site_code OR delete it — which, the exact resulting file (or git rm), and why.' },
|
||||
characterizationTests: { type: 'string', description: 'the new test file(s) under lambdas/po/site_extractor/tests/: how they load the handler (loader idiom), the CURRENT-behavior pins (KLAL rejected, DLI6X/SNY55 accepted, parse_address variants, pending-review fallback) and the FIXED-behavior assertions they flip to, plus any test_bundle_consistency edit if it now pins the site_extractor asset.' },
|
||||
parityRules: { type: 'string', description: 'how Verify judges the change: the staged site_extractor asset must CONTAIN derived_fields.py (+ the handler and its own siblings, flat) and nothing stray (no tests/, no __pycache__, no package/), asset hash deterministic, and the derived_fields.py diff must be empty vs base.' },
|
||||
notes: { type: 'string' },
|
||||
},
|
||||
}
|
||||
|
||||
const IMPL = {
|
||||
type: 'object',
|
||||
required: ['filesChanged', 'summary', 'checksRun'],
|
||||
properties: {
|
||||
filesChanged: { type: 'array', items: { type: 'string' } },
|
||||
summary: { type: 'string' },
|
||||
checksRun: { type: 'string' },
|
||||
blockers: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const CHECKS = {
|
||||
type: 'object',
|
||||
required: ['passed', 'details'],
|
||||
properties: {
|
||||
passed: { type: 'boolean' },
|
||||
details: { type: 'string' },
|
||||
scopeViolations: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const FINDINGS = {
|
||||
type: 'object',
|
||||
required: ['findings'],
|
||||
properties: {
|
||||
findings: {
|
||||
type: 'array',
|
||||
items: {
|
||||
type: 'object',
|
||||
required: ['title', 'severity', 'confirmed', 'evidence', 'fix'],
|
||||
properties: {
|
||||
title: { type: 'string' },
|
||||
severity: { enum: ['critical', 'high', 'medium', 'low'] },
|
||||
confirmed: { type: 'boolean' },
|
||||
evidence: { type: 'string' },
|
||||
fix: { type: 'string' },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------- setup
|
||||
|
||||
phase('Setup')
|
||||
|
||||
// HARD-GATE (a): the shadow bake must have concluded. This workflow cannot
|
||||
// auto-verify the bake ended, so require an explicit opt-in BEFORE any git work.
|
||||
if (!_args || _args.bakeConcluded !== true) {
|
||||
return {
|
||||
aborted: 'Phase 6 gated on shadow-bake conclusion',
|
||||
blockers: [
|
||||
'Phase 6 gated on shadow-bake conclusion — re-run with args {bakeConcluded:true} once the DerivedFieldAgreement bake is signed off and the switchover PR (Python authoritative on ai_fallback) has landed.',
|
||||
],
|
||||
}
|
||||
}
|
||||
|
||||
const setup = await agent(`
|
||||
In ${REPO}:
|
||||
1. SEQUENCING GATE — Phase 3 (lambdas/shared/ extraction with the widened
|
||||
../lambdas asset roots) must be on ${BASE}: derived_fields.py must be
|
||||
shippable into the site_extractor asset via the Phase 2/3 bundling
|
||||
mechanism, and Phase 3 DELIBERATELY left site_extractor's from_asset
|
||||
untouched — THIS phase adds the bundling change for site_extractor.
|
||||
git fetch origin, then pick the base ref: origin/${BASE} if that remote ref
|
||||
exists, otherwise the local branch ${BASE} (a stacked local-only base is
|
||||
expected and fine). Verify on the base ref:
|
||||
(a) Phase 2/3 mechanism present: cdk/po_stack.py on the base ref contains
|
||||
Code.from_asset("../lambdas") for the PO email processor
|
||||
(git show <baseref>:cdk/po_stack.py | grep -n '\\.\\./lambdas');
|
||||
(b) Phase 3 landed: lambdas/shared/ exists on the base ref with a
|
||||
cp shared/*.py in the email-processor bundling command
|
||||
(git show <baseref>:cdk/po_stack.py | grep -n 'shared'), and
|
||||
git show <baseref>:lambdas/shared/ses_auth.py | head -3 succeeds;
|
||||
(c) site_extractor's from_asset is STILL the untouched narrow form on the
|
||||
base ref (git show <baseref>:cdk/po_stack.py | grep -n
|
||||
'../lambdas/po/site_extractor') — this phase is the one that widens it.
|
||||
If (a) or (b) is missing, STOP with a blocker naming the unmet phase and do
|
||||
nothing else. If (c) is already widened, note it (someone beat us to it) but
|
||||
do not treat as a hard blocker.
|
||||
2. Verify clean working tree (untracked .coverage / .claude/ / the local 44 MB
|
||||
lambdas/po/email_processor/package/ dir are fine; any OTHER dirt = blocker,
|
||||
never stash or discard).
|
||||
3. git checkout ${BASE}; then git pull --ff-only ONLY if the branch has an
|
||||
upstream (a local-only base skips the pull — not a blocker); then
|
||||
git checkout -b ${BRANCH}
|
||||
4. gh pr list --state open --json number,title,headRefName (overlap check).
|
||||
Return facts: HEAD sha, per-gate evidence, open PRs, blockers.
|
||||
`, { label: 'setup:branch', model: 'haiku', schema: RECON })
|
||||
|
||||
if (!setup || (setup.blockers && setup.blockers.length)) {
|
||||
return { aborted: 'setup blockers', blockers: setup ? setup.blockers : ['setup agent died'], facts: setup ? setup.facts : [] }
|
||||
}
|
||||
log(`Branch ${BRANCH} ready off ${BASE}. ${setup.summary}`)
|
||||
|
||||
// ------------------------------------------------------------------- recon
|
||||
|
||||
phase('Recon')
|
||||
const recon = await parallel([
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of the site_extractor DEFECT surface
|
||||
(lambdas/po/site_extractor/handler.py):
|
||||
1. Quote SITE_CODE_PATTERN verbatim with file:line and EVERY place it is used
|
||||
(.match / .search). Note that .match is prefix-anchored and the pattern
|
||||
requires 1-2 trailing digits.
|
||||
2. Quote extract_site_code in full with line numbers: the direct-field branch
|
||||
(record["site_code"]), the ship_to name branches, the line_items branch and
|
||||
its r"^([A-Z]{1,4}[0-9]{1,2}|[A-Z]{4,5})\\b" alternation — prove the
|
||||
[A-Z]{4,5} arm is DEAD (it can never survive the very-next-line
|
||||
SITE_CODE_PATTERN.match, which requires a digit).
|
||||
3. Concretely trace KLAL (all letters), DLI6, DLI6X, SNY55 through the CURRENT
|
||||
code — which return, which fall through — to pin the exact current behavior
|
||||
the characterization tests must first reproduce.
|
||||
4. Quote the EXACT boundaries (file:line) of parse_address, write_pending_review
|
||||
and the handler else-branch that calls write_pending_review — these must stay
|
||||
byte-unchanged; note everything that must NOT move.
|
||||
5. Confirm there is NO tests/ dir under lambdas/po/site_extractor today and note
|
||||
how the email-processor test loaders resolve a bare 'import handler' (the
|
||||
idiom the new characterization tests will reuse).
|
||||
20-30 precise facts.`,
|
||||
{ label: 'recon:site-extractor', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of the CANONICAL shape in
|
||||
lambdas/po/email_processor/derived_fields.py that the fix must adopt:
|
||||
1. Quote _STRICT_CODE_RE (line ~50), _CODE_TOKEN_RE, _SKIP (line ~69) and
|
||||
_is_valid_code (line ~97) verbatim with file:line. State exactly what shape
|
||||
counts as a valid site code (3-5 chars, letter-first, all-letters allowed,
|
||||
>=2 alphabetic chars, not skip-listed) using FULLMATCH.
|
||||
2. Quote derive_site_code (line ~259) signature + docstring + return contract
|
||||
(str | None, NEVER raises) and describe what INPUT it takes (the parsed PO
|
||||
dict) and the priority-ordered shapes it tries — so the fallback wiring in
|
||||
the handler passes the right shape of dict.
|
||||
3. Determine precisely: under the canonical fullmatch shape + _is_valid_code,
|
||||
is KLAL valid? is DLI6X valid? is SNY55 valid? Show the reasoning token by
|
||||
token. If the canonical shape does NOT by itself reject DLI6X/SNY55, say so
|
||||
explicitly and identify what additional check (standalone-token lookaround,
|
||||
length, _is_valid_code, or applying derive-style resolution to the field)
|
||||
is required to hit the doc's pinned outcome (KLAL accepted; DLI6X/SNY55
|
||||
rejected) — this is load-bearing for the spec.
|
||||
4. List every import derived_fields.py needs at module load (must be
|
||||
stdlib-only so it can be dropped flat into the site_extractor asset with no
|
||||
new dependency).
|
||||
15-25 facts. Flag as a blocker any way the pinned KLAL/DLI6X/SNY55 outcome
|
||||
cannot be met with derived_fields semantics alone.`,
|
||||
{ label: 'recon:derived-fields-shape', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of the bundling + test + script surface this phase touches:
|
||||
1. cdk/po_stack.py — quote the site_extractor Function block verbatim with
|
||||
file:line (currently ~677-694): function_name, runtime, architecture,
|
||||
handler property, memory/timeout, env, and the from_asset call
|
||||
(root + exclude) that this phase must widen. Also quote the PO
|
||||
email-processor from_asset (root ../lambdas + the cp glob + exclude list)
|
||||
as the Phase 2/3 template to mirror. Confirm no requirements.txt exists for
|
||||
site_extractor. List every function property that must NOT change.
|
||||
2. tests/test_bundle_consistency.py — quote PO_EXPECTED_TOP_LEVEL_MODULES and
|
||||
every test; determine whether ANY assertion currently pins the
|
||||
site_extractor asset (if none does, note that a new site_extractor pin —
|
||||
asserting derived_fields.py now ships and a commented-out cp fails — is the
|
||||
clean way to keep teeth; if one does, quote it).
|
||||
3. scripts/backfill_sites.py — quote the sys.path hack + the
|
||||
'from handler import extract_site_code, parse_address, upsert_site' line and
|
||||
how it uses extract_site_code, so the spec can choose repoint vs delete.
|
||||
4. Read-only AWS (us-east-1): aws lambda get-function for
|
||||
po-ingest-site-extractor; download its Code.Location zip to a scratch dir and
|
||||
produce the COMPLETE unzip -l file list (the baseline the new bundled asset
|
||||
must cover PLUS derived_fields.py); record CodeSha256.
|
||||
15-25 facts.`,
|
||||
{ label: 'recon:bundling-tests-script', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
])
|
||||
|
||||
const reconOk = recon.filter(Boolean)
|
||||
const pack = reconOk.map(r => `## ${r.summary}\n${r.facts.join('\n')}`).join('\n\n')
|
||||
const reconBlockers = reconOk.flatMap(r => r.blockers || [])
|
||||
log(`Recon complete: ${reconOk.length}/3 mappers, ${reconBlockers.length} blockers`)
|
||||
if (reconBlockers.length) {
|
||||
return { aborted: 'recon blockers (likely a shape-parity gap — resolve before implementing)', blockers: reconBlockers, reconPack: pack }
|
||||
}
|
||||
|
||||
// -------------------------------------------------------------------- spec
|
||||
|
||||
phase('Spec')
|
||||
const spec = await agent(`${PREAMBLE}
|
||||
You are the SPEC agent — the single authority that pins every contested
|
||||
decision BEFORE parallel implementation (parallel leaves cannot see each
|
||||
other's choices). Using the recon pack below plus your own reads of the actual
|
||||
files, produce the binding implementation spec:
|
||||
- handlerFix: the exact edit to lambdas/po/site_extractor/handler.py.
|
||||
Validate record["site_code"] with the CANONICAL derived_fields fullmatch
|
||||
shape + skip-list (constraint 1) so KLAL is ACCEPTED and DLI6X/SNY55 are
|
||||
REJECTED — if recon found the bare fullmatch shape does not reject
|
||||
DLI6X/SNY55, pin the exact additional check that does (do NOT reintroduce a
|
||||
digit requirement). Import derive_site_code from derived_fields for the
|
||||
fallback path; wire it with the correct input shape. DELETE the
|
||||
SITE_CODE_PATTERN def, the line-62 alternation, and every SITE_CODE_PATTERN
|
||||
reference. State EXPLICITLY that parse_address, write_pending_review and the
|
||||
pending-review else-branch are byte-unchanged.
|
||||
- bundlingEdit: the complete replacement from_asset block for site_extractor —
|
||||
widened root + scoped cp staging both site_extractor *.py and
|
||||
lambdas/po/email_processor/derived_fields.py FLAT into /asset-output, with
|
||||
the __pycache__/tests/package excludes, mirroring the Phase 2/3
|
||||
email-processor form. Pick ONE mechanism (Docker bundling vs no-Docker local
|
||||
staging) and give exact code. Mind that the module must land flat so
|
||||
'from derived_fields import derive_site_code' resolves at runtime.
|
||||
- backfillDecision: repoint scripts/backfill_sites.py at derive_site_code OR
|
||||
git rm it — pick one, give the exact resulting file or the rm, and say why.
|
||||
- characterizationTests: the new tests under lambdas/po/site_extractor/tests/ —
|
||||
loader idiom, the CURRENT-behavior pins (KLAL rejected, DLI6X/SNY55 accepted,
|
||||
parse_address variants, pending-review fallback) that get FLIPPED to
|
||||
FIXED-behavior assertions in the same change, and any test_bundle_consistency
|
||||
edit that now pins the site_extractor asset (derived_fields ships;
|
||||
commented-out cp fails).
|
||||
- parityRules: exactly how Verify judges the staged asset vs the deployed
|
||||
baseline — staged site_extractor asset CONTAINS derived_fields.py + handler +
|
||||
own siblings (flat), nothing stray, asset hash deterministic, and
|
||||
derived_fields.py diff empty vs ${BASE}.
|
||||
Recon pack:\n${pack}`,
|
||||
{ label: 'spec:pin-site-extractor', phase: 'Spec', schema: SPEC })
|
||||
|
||||
if (!spec) return { aborted: 'spec agent died — rerun workflow', reconBlockers }
|
||||
const specBlock = `BINDING SPEC (from the spec agent — implement EXACTLY this):\n${JSON.stringify(spec, null, 2)}`
|
||||
log('Spec pinned: handler fix, site_extractor bundling, backfill decision, characterization tests, parity rules')
|
||||
|
||||
// --------------------------------------------------------------- implement
|
||||
|
||||
phase('Implement')
|
||||
const impl = await parallel([
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: lambdas/po/site_extractor/ ONLY (the handler AND a new tests/
|
||||
subdir). Do not touch cdk/, scripts/, tests/ at repo root, or README.
|
||||
Task: execute spec.handlerFix + spec.characterizationTests.
|
||||
1. Edit handler.py per spec.handlerFix: validate record["site_code"] with the
|
||||
canonical derived_fields fullmatch shape + skip-list, import
|
||||
derive_site_code for the fallback path, DELETE SITE_CODE_PATTERN and the
|
||||
line-62 [A-Z]{4,5} alternation and every SITE_CODE_PATTERN reference. Keep
|
||||
parse_address, write_pending_review and the pending-review else-branch
|
||||
BYTE-UNCHANGED (constraint 3). Do NOT edit derived_fields.py (constraint 6).
|
||||
2. Write the characterization tests under lambdas/po/site_extractor/tests/:
|
||||
FIRST pin CURRENT behavior (KLAL rejected, DLI6X/SNY55 accepted,
|
||||
parse_address variants, pending-review fallback), THEN flip the assertions
|
||||
to the FIXED behavior (KLAL accepted, DLI6X/SNY55 rejected) in this same
|
||||
change — the COMMITTED suite asserts FIXED behavior (constraint 5). The
|
||||
tests must import derived_fields via the same flat/loader idiom the asset
|
||||
uses so they exercise the real derive_site_code.
|
||||
Run before returning: ruff check lambdas/po/site_extractor && ruff format
|
||||
lambdas/po/site_extractor --check, and pytest -q --no-cov on your new suite
|
||||
(with derived_fields.py resolvable on sys.path the way the asset ships it —
|
||||
stub AWS/boto env as needed). git diff ${BASE}...HEAD --
|
||||
lambdas/po/email_processor/derived_fields.py MUST be empty.
|
||||
${specBlock}`,
|
||||
{ label: 'impl:site-extractor', model: 'opus', phase: 'Implement', schema: IMPL }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: cdk/po_stack.py (the site_extractor from_asset region ONLY — alarms,
|
||||
IAM, tables, env, and the email-processor/web_ui assets are all off-limits) and
|
||||
tests/test_bundle_consistency.py.
|
||||
Task: apply spec.bundlingEdit (widen the site_extractor asset root + scoped cp
|
||||
staging derived_fields.py flat, mirroring the Phase 2/3 email-processor form,
|
||||
keeping the __pycache__/tests/package excludes) and, per
|
||||
spec.characterizationTests / spec.parityRules, add or update the
|
||||
site_extractor pin in test_bundle_consistency.py so a commented-out or narrowed
|
||||
derived_fields cp FAILS the test (keep existing tests green, don't lose teeth).
|
||||
Touch nothing else; every other function property and every other asset stays
|
||||
byte-identical.
|
||||
Run before returning: ruff check cdk tests/test_bundle_consistency.py && cd cdk
|
||||
&& npx cdk synth po-ingest -q -o /tmp/phase6-synth (artifact-id selector, NOT
|
||||
stack_name). Confirm the staged site_extractor asset CONTAINS derived_fields.py
|
||||
flat alongside handler.py and NO tests/__pycache__/package; note the asset hash.
|
||||
If the handler edits have not landed yet the synth still works (asset is just
|
||||
files) — but if the new tests/ dir would be staged, prove the exclude drops it.
|
||||
${specBlock}`,
|
||||
{ label: 'impl:cdk-bundle-test', model: 'sonnet', phase: 'Implement', schema: IMPL }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: scripts/backfill_sites.py and README.md ONLY.
|
||||
Task A: apply spec.backfillDecision — either repoint scripts/backfill_sites.py
|
||||
at derive_site_code (importing from derived_fields, not the handler's deleted
|
||||
extractor) OR git rm it. Do exactly what the spec pinned.
|
||||
Task B: README — update the site_code / site_extractor section to reflect the
|
||||
single reconciled definition (derived_fields canonical shape is now
|
||||
authoritative for site_extractor too; KLAL-class all-letter codes self-register;
|
||||
derived_fields.py ships into the site_extractor asset via the same bundling cp).
|
||||
Fix any stale "three inconsistent site_code definitions" wording (finding X2).
|
||||
Match existing README style.
|
||||
Run before returning: ruff check on any script you kept, and pytest -q --no-cov
|
||||
at repo root (must be green against the OTHER agents' edits — they land in
|
||||
parallel; poll by re-running up to ~10 min before reporting a blocker).
|
||||
${specBlock}`,
|
||||
{ label: 'impl:backfill-readme', model: 'opus', phase: 'Implement', schema: IMPL }),
|
||||
])
|
||||
|
||||
const implOk = impl.filter(Boolean)
|
||||
const implBlockers = implOk.flatMap(r => r.blockers || [])
|
||||
log(`Implement complete: ${implOk.length}/3 agents, blockers: ${implBlockers.length}`)
|
||||
|
||||
// ---------------------------------------------------- verify + fix loop
|
||||
|
||||
const EXPECTED_SCOPE = [
|
||||
'lambdas/po/site_extractor/',
|
||||
'cdk/po_stack.py',
|
||||
'scripts/backfill_sites.py',
|
||||
'tests/test_bundle_consistency.py',
|
||||
'README.md',
|
||||
]
|
||||
|
||||
const mechanicalPrompt = `${PREAMBLE}
|
||||
Independent re-verification — trust nothing self-reported. Run ALL gates,
|
||||
quoting failures verbatim:
|
||||
1. pytest -q --no-cov (repo root, all roots green — including the NEW
|
||||
site_extractor suite). Confirm the new suite actually exists and is
|
||||
collected (it did not exist before this phase).
|
||||
2. ruff check . && ruff format --check .
|
||||
3. cd cdk && npx cdk synth po-ingest -q (artifact-id selector, NOT stack_name).
|
||||
4. ASSET CONTENTS: locate the staged site_extractor asset under the synth -o
|
||||
dir and prove it CONTAINS derived_fields.py flat alongside handler.py and
|
||||
the site_extractor's own siblings, and contains NO tests/, NO __pycache__,
|
||||
NO package/ (constraint 2). List the asset's top-level files.
|
||||
5. CHARACTERIZATION: confirm the committed site_extractor tests now assert the
|
||||
FIXED behavior — KLAL ACCEPTED, DLI6X and SNY55 REJECTED — and that a
|
||||
current-behavior-of-old-code pin was not left red (constraint 5).
|
||||
6. UNTOUCHABLE: git diff ${BASE}...HEAD --
|
||||
lambdas/po/email_processor/derived_fields.py MUST output NOTHING
|
||||
(constraint 6). Also confirm parse_address + write_pending_review + the
|
||||
pending-review else-branch in site_extractor/handler.py are byte-unchanged
|
||||
vs ${BASE} (git diff the file and check only extract_site_code /
|
||||
SITE_CODE_PATTERN / imports changed).
|
||||
7. DELETION: SITE_CODE_PATTERN is gone from site_extractor/handler.py (grep
|
||||
returns nothing) and no path still uses the deleted digit-requiring regex or
|
||||
the line-62 [A-Z]{4,5} alternation.
|
||||
8. git status --porcelain scope check: every modified/added/deleted path under
|
||||
${EXPECTED_SCOPE.join(', ')} (untracked .coverage/.claude/package/
|
||||
tolerated). If backfill_sites.py was deleted, the deletion is staged/tracked.
|
||||
passed=true only if all green. YOU MAY NOT edit files.`
|
||||
|
||||
const lenses = [
|
||||
{ key: 'shape-parity', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — shape-parity lens. Prove extract_site_code now matches
|
||||
derive_site_code's canonical shape + skip-list. (1) Byte-read the fixed
|
||||
extract_site_code and derived_fields' _STRICT_CODE_RE / _is_valid_code / _SKIP;
|
||||
construct the token set {KLAL, DLI6, DLI6X, SNY55, RME (skip-listed), B187
|
||||
(<2 alpha)} and trace each through the fixed direct-field validation AND the
|
||||
derive_site_code fallback — KLAL MUST be accepted, DLI6X and SNY55 MUST be
|
||||
rejected, skip-listed and sub-2-alpha tokens rejected. (2) Prove NO path still
|
||||
uses the deleted digit-requiring SITE_CODE_PATTERN or the [A-Z]{4,5} dead arm
|
||||
(grep the whole handler). (3) Attack the fallback wiring: does derive_site_code
|
||||
receive the dict shape it expects, and does it NEVER raise (a stream record with
|
||||
missing/empty fields must not throw)? confirmed=true only with a concrete
|
||||
token-trace or file:line proof.` },
|
||||
{ key: 'bundling', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — bundling lens. Prove derived_fields.py actually ships in
|
||||
the site_extractor zip and the excludes stay intact. (1) cd cdk && npx cdk
|
||||
synth po-ingest -q -o /tmp/phase6-bundle-a, then again into
|
||||
/tmp/phase6-bundle-b; locate the staged site_extractor asset in each and prove
|
||||
derived_fields.py is present flat next to handler.py, that the runtime import
|
||||
'from derived_fields import derive_site_code' resolves with that dir alone on
|
||||
sys.path (python3 -c with env stubs), and that the two synths produce IDENTICAL
|
||||
asset hashes (determinism). (2) Drop a throwaway __pycache__/junk.pyc and a
|
||||
tests/scratch_test.py under the widened root region (delete them afterwards),
|
||||
re-synth, and confirm the excludes keep the asset hash unchanged and neither
|
||||
file appears. (3) Confirm NO other asset (email processors, web_ui) changed
|
||||
hash as a side effect of the root widening. confirmed=true only with evidence.` },
|
||||
{ key: 'regression', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — regression lens. The fix must be surgical. (1) git diff
|
||||
${BASE}...HEAD -- lambdas/po/site_extractor/handler.py — prove parse_address,
|
||||
write_pending_review, upsert_site, load_address_cache, lookup_by_address,
|
||||
deserialize_image and the handler() event loop / pending-review else-branch are
|
||||
BYTE-UNCHANGED; the ONLY deltas are inside extract_site_code + its imports +
|
||||
the deleted SITE_CODE_PATTERN. (2) Prove derived_fields.py is byte-unchanged
|
||||
vs ${BASE} (constraint 6) — the shadow-bake authority model did not shift.
|
||||
(3) Confirm the ai_fallback-sourced record["site_code"] is still VALIDATED
|
||||
(shape + skip-list), not blindly trusted and not regex-bypassed (constraint 3).
|
||||
(4) If backfill_sites.py was kept, prove it no longer imports the deleted
|
||||
extractor; if deleted, prove nothing else imports it. confirmed=true only with
|
||||
file:line or diff evidence.` },
|
||||
]
|
||||
|
||||
let round = 0
|
||||
let checks = null
|
||||
let confirmed = []
|
||||
while (round < 3) {
|
||||
phase('Verify')
|
||||
const results = await parallel([
|
||||
() => agent(mechanicalPrompt, { label: `verify:mechanical-r${round}`, model: 'sonnet', phase: 'Verify', schema: CHECKS }),
|
||||
...lenses.map(l => () =>
|
||||
agent(l.prompt, { label: `verify:${l.key}-r${round}`, phase: 'Verify', schema: FINDINGS })),
|
||||
])
|
||||
checks = results[0]
|
||||
confirmed = results.slice(1).filter(Boolean)
|
||||
.flatMap(r => r.findings || [])
|
||||
.filter(f => f.confirmed && f.severity !== 'low')
|
||||
const green = checks && checks.passed
|
||||
log(`Verify round ${round}: mechanical ${checks && checks.passed ? 'GREEN' : 'RED'}, confirmed findings: ${confirmed.length}`)
|
||||
if (green && confirmed.length === 0) break
|
||||
|
||||
round += 1
|
||||
if (round >= 3) break
|
||||
phase('Fix')
|
||||
await agent(`${PREAMBLE}
|
||||
You are the fix agent — you may edit files under: ${EXPECTED_SCOPE.join(', ')}.
|
||||
Fix EVERY item below minimally; the binding spec and 7 pinned constraints still
|
||||
hold (a finding that conflicts with a constraint is reported, not "fixed" — the
|
||||
constraint wins, esp. constraint 6's derived_fields untouchability and
|
||||
constraint 3's validated-not-blind-trust rule). Re-run the specific failing
|
||||
gate/test per fix.
|
||||
MECHANICAL:\n${checks ? checks.details : '(agent died — rerun all gates)'}
|
||||
CONFIRMED FINDINGS:\n${JSON.stringify(confirmed, null, 2)}
|
||||
${specBlock}`,
|
||||
{ label: `fix:round-${round}`, model: 'opus', phase: 'Fix', schema: IMPL })
|
||||
}
|
||||
|
||||
const verifyClean = checks && checks.passed && confirmed.length === 0
|
||||
if (!verifyClean) {
|
||||
return {
|
||||
status: 'NEEDS ATTENTION — verify not clean after 3 rounds; branch left uncommitted',
|
||||
branch: BRANCH,
|
||||
mechanical: checks,
|
||||
unresolvedFindings: confirmed,
|
||||
implBlockers,
|
||||
reconBlockers,
|
||||
spec,
|
||||
}
|
||||
}
|
||||
|
||||
// ----------------------------------------------------------------- package
|
||||
|
||||
phase('Package')
|
||||
const commit = await agent(`${PREAMBLE.replace('do NOT commit, ', '')}
|
||||
YOU are the commit agent:
|
||||
1. Read ~/Documents/repositories/seahaven/engineering-handbook/commit-messages.md
|
||||
and follow it exactly.
|
||||
2. git add only paths under: ${EXPECTED_SCOPE.join(', ')} and
|
||||
.claude/workflows/phase-6-site-extractor.js. NOT .coverage, NOT package/.
|
||||
Verify the staged set with git status — if backfill_sites.py was deleted,
|
||||
its deletion MUST be staged too.
|
||||
3. ONE commit; write the message to /tmp/phase6-commit-msg.txt and use
|
||||
git commit -F /tmp/phase6-commit-msg.txt (backticks in -m get eaten by zsh).
|
||||
Suggested subject:
|
||||
"feat: reconcile site_extractor site_code with derived_fields canonical shape (refactor phase 6)"
|
||||
Body: the digit-pattern defect (KLAL never self-registered, DLI6X/SNY55
|
||||
false-accepted), the canonical fullmatch + skip-list fix + derive_site_code
|
||||
fallback, the derived_fields.py bundling cp into the site_extractor asset
|
||||
(Phase 2/3 mechanism), the characterization-first-then-flip test approach,
|
||||
the backfill repoint/delete decision, and that derived_fields.py is
|
||||
byte-unchanged. NO AI attribution / Co-Authored-By lines.
|
||||
4. Do NOT push. Return commit sha + shortstat in summary.`,
|
||||
{ label: 'package:commit', model: 'sonnet', phase: 'Package', schema: IMPL })
|
||||
|
||||
return {
|
||||
status: 'BUILT — committed locally, NOT pushed',
|
||||
branch: BRANCH,
|
||||
base: BASE,
|
||||
commit: commit ? commit.summary : 'commit agent died — commit manually',
|
||||
spec: { handlerFix: spec.handlerFix, bundlingEdit: spec.bundlingEdit, backfillDecision: spec.backfillDecision, notes: spec.notes },
|
||||
implementation: implOk.map(r => r.summary),
|
||||
filesChanged: implOk.flatMap(r => r.filesChanged),
|
||||
verifyRounds: round + 1,
|
||||
blockers: implBlockers.concat(reconBlockers),
|
||||
outstandingGates: [
|
||||
'/sh-security-review RECOMMENDED before push — the validated record["site_code"] field can be ai_fallback-sourced (attacker-influenced via a DKIM-passing injected body), so the new shape/skip validation is untrusted-input handling; run it on the committed diff and flag it.',
|
||||
'cross-family cross_review.py NOT required (no IAM/policy change, no Lambda handler signature/event/return-contract change — internal validation logic + a bundling cp only).',
|
||||
'push + PR + gh pr checks green.',
|
||||
'deploy-then-merge: deploy from branch, smoke green, and confirm the LIVE success signal = the pending-site-review write rate DROPS (KLAL-class all-letter codes now self-register instead of falling to pending review), plus one real DynamoDB-stream event processed clean, THEN merge.',
|
||||
'GOTCHA: npx cdk synth po-ingest uses the ARTIFACT-ID selector (po-ingest), not the stack_name — using the wrong selector silently synths nothing or the wrong stack.',
|
||||
],
|
||||
}
|
||||
|
|
@ -1,661 +0,0 @@
|
|||
export const meta = {
|
||||
name: 'phase-7-ops-recovery',
|
||||
description: 'Phase 7 of the procurement-ingest refactor (docs/refactor-evaluation.md): ops/recovery + dependency hygiene. Generalize scripts/reprocess.py (--pipeline po|wo, --key/--prefix/--since; TARGETED replay primary, full-prefix DEMOTED behind --all with documented caveats) + a synthetic-event-shape contract test pinning the raw-key/no-URL-decode S3 event. New docs/runbook-dlq-recovery.md for the no-redrive async-destination DLQ (receive->key->re-invoke->verify->purge; 14d DLQ / 90d S3 windows; sender-auth + ai_fallback_rejected drops never reach the DLQ), linked from README alarms. Dependency hygiene: drop vendored boto3 from both email-processor requirements (handbook empty-with-comment form; runtime copy suffices per lambda-template.md), simplify bundling to cp-only where the vendored dep is gone, exact-pin moto==, pin-then-add dependabot entries for /tests + po/web_ui + po/site_extractor, reduce wo/web_ui dead manifest to empty-with-comment. Optional local-only rm of the untracked 44 MB package/ dir. Gates on Phase 2 merged (../lambdas asset root). Ops tooling + dep hygiene, no auth/untrusted-input/IAM change. Committed locally, never pushed.',
|
||||
phases: [
|
||||
{ title: 'Setup', detail: 'verify Phase 2 on base (Code.from_asset("../lambdas")), branch feature/phase-7-ops-recovery', model: 'haiku' },
|
||||
{ title: 'Recon', detail: '4 mappers: reprocess.py + event shape, dependency/manifest/dependabot state, post-Phase-2 bundling + package/ dir, DLQ/alarm/S3-lifecycle names (read-only AWS)' },
|
||||
{ title: 'Spec', detail: 'serial fable spec: reprocess CLI + caveats, runbook contents, requirements/moto/dependabot edits, cp-only bundling form, package/ cleanup, contract test, verify rules' },
|
||||
{ title: 'Implement', detail: 'opus: scripts/ + reprocess contract test; sonnet: requirements + dependabot + cdk bundling; opus: runbook + README — disjoint files', model: 'opus' },
|
||||
{ title: 'Verify', detail: 'mechanical gates + 3 fable lenses (bundling-integrity, reprocess-safety, dependency)', model: 'sonnet' },
|
||||
{ title: 'Fix', detail: 'opus fixer, full re-verify, max 3 rounds', model: 'opus' },
|
||||
{ title: 'Package', detail: 'single commit via -F (no push); optional local rm of package/ reported, not committed', model: 'sonnet' },
|
||||
],
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------- constants
|
||||
|
||||
const REPO = '/Users/adammoussa/Documents/repositories/seahaven/procurement-ingest'
|
||||
const BRANCH = 'feature/phase-7-ops-recovery'
|
||||
let _args = args
|
||||
if (typeof _args === 'string') {
|
||||
try { _args = JSON.parse(_args) } catch (e) { _args = null }
|
||||
}
|
||||
const BASE = (_args && _args.base) || 'main'
|
||||
|
||||
const CONSTRAINTS = `
|
||||
PINNED BEHAVIORAL CONSTRAINTS (docs/refactor-evaluation.md Phase 7 — violating any is a build failure):
|
||||
1. GENERALIZE scripts/reprocess.py: add --pipeline po|wo (selects the
|
||||
function name + bucket per pipeline — po-email-processor /
|
||||
po-ingest-emails-<acct>, workorder-email-processor / its bucket), plus
|
||||
--key (single object), --prefix, and --since (time filter on
|
||||
LastModified). TARGETED replay (--key / --prefix / --since) is the
|
||||
PRIMARY, default mode. FULL-PREFIX replay is DEMOTED behind an explicit
|
||||
--all flag. The --all caveats MUST be documented BOTH in --help text and
|
||||
in code comments: Event-type (async) invocation is CONCURRENT so sorting
|
||||
does NOT serialize; switch to RequestResponse if order matters; metrics
|
||||
get double-counted on replay; Bedrock is re-billed; out-of-order replay
|
||||
can REGRESS already-merged fields. Keep the existing dry-run-by-default /
|
||||
--execute safety (targeted replay stays dry-run unless --execute).
|
||||
2. SYNTHETIC-EVENT-SHAPE CONTRACT TEST (§4.7): pin the exact S3 event shape
|
||||
reprocess emits — Records[0].s3.bucket.name + Records[0].s3.object.key —
|
||||
and assert the key is the RAW object key with NO URL-decoding (a real S3
|
||||
notification URL-encodes the key; reprocess builds from the raw
|
||||
list_objects_v2 key, and the handler is what decodes — replaying a
|
||||
pre-decoded key would double-decode). Test lives under scripts' tests or
|
||||
tests/ and runs in the standard pytest collection.
|
||||
3. NEW docs/runbook-dlq-recovery.md: the async on-failure destination DLQ
|
||||
has NO console redrive-to-source. Documented procedure: receive-message
|
||||
-> extract the S3 key from the event body -> targeted re-invoke (via the
|
||||
generalized reprocess.py --key) -> verify the write -> purge the message.
|
||||
State the recovery WINDOWS explicitly: 14-day DLQ breadcrumb retention,
|
||||
90-day raw-email S3 retention (the inbound/ lifecycle rule OVERRIDES the
|
||||
table RETAIN policy — S3 is the real replay floor). Document that
|
||||
sender-auth rejections AND ai_fallback_rejected drops INTENTIONALLY never
|
||||
reach the DLQ (they are fail-closed SKIPS, not errors — no retry, no DLQ
|
||||
message). Link the runbook from the README alarms section.
|
||||
4. DEPENDENCY HYGIENE — DROP vendored boto3 from BOTH email-processor
|
||||
requirements.txt: replace 'boto3>=1.43.47' with the handbook
|
||||
empty-with-comment form (a comment explaining the Lambda runtime provides
|
||||
boto3 per lambda-template.md — only-boto3 functions correctly use the
|
||||
runtime copy; no pinned third-party dep remains). Same empty-with-comment
|
||||
reduction for wo/web_ui/requirements.txt (a dead manifest today).
|
||||
5. SIMPLIFY BUNDLING TO CP-ONLY where the vendored dep is gone: once the
|
||||
email-processor requirements are empty-with-comment, 'pip install -r ... '
|
||||
installs nothing, so the pip step is removable and the command becomes
|
||||
cp-only. This is ONLY safe BECAUSE there are no third-party binary deps
|
||||
left. Do NOT regress: the Phase 2 exclude lists
|
||||
(['**/__pycache__/**','**/tests/**','**/package/**']) STAY; the widened
|
||||
'../lambdas' asset root STAYS; if a Phase 3 'cp shared/*.py' line is
|
||||
present on the base it STAYS. The '--platform manylinux2014_aarch64
|
||||
--only-binary=:all:' pin is only meaningful while a pip install runs — its
|
||||
accidental removal caused the PR #34 outage, so removing the WHOLE pip
|
||||
step (deliberately, because nothing is installed) is the only acceptable
|
||||
way it disappears; you may NOT keep a pip install while dropping the pin.
|
||||
If recon finds ANY third-party dep still required by an email processor,
|
||||
cp-only is a blocker — keep the pinned pip step.
|
||||
6. EXACT-PIN moto: change tests/requirements.txt 'moto>=5.0.0' to
|
||||
'moto==<resolved-version>' (resolve the actually-installed/current 5.x
|
||||
version; floor pins make the dependabot entry a no-op).
|
||||
7. DEPENDABOT: add pip entries for '/tests', '/lambdas/po/web_ui', and
|
||||
'/lambdas/po/site_extractor' — but PIN THOSE MANIFESTS FIRST. po/web_ui
|
||||
and po/site_extractor have NO requirements.txt today, so a dependabot
|
||||
entry pointed at them is a no-op until a PINNED manifest exists; create
|
||||
each manifest (exact-pinned boto3, or empty-with-comment ONLY if the
|
||||
dependabot entry would then be pointless — a dependabot entry needs at
|
||||
least one pinned dep to act on). Match the existing dependabot.yml entry
|
||||
shape (weekly, minor-and-patch group). tests/ gets its entry once moto is
|
||||
exact-pinned (constraint 6).
|
||||
8. DELETE the untracked 44 MB lambdas/po/email_processor/package/ dir as an
|
||||
OPTIONAL local-cleanup step: it is UNTRACKED / local-only, so this is a
|
||||
filesystem 'rm -rf', NOT a 'git rm' (there is nothing tracked to commit).
|
||||
With Phase 2's '**/package/**' exclude already deployed, the deletion is
|
||||
asset-hash-NEUTRAL. The Package agent PERFORMS and REPORTS it; it is NOT
|
||||
part of the commit.
|
||||
9. UNTOUCHABLE: no handler / lambda runtime code change under lambdas/*/
|
||||
email_processor/*.py (this is dep + ops + bundling only). No alarm, IAM,
|
||||
table, env, runtime, memory, timeout, or logical-ID delta on either stack
|
||||
— the ONLY cdk delta permitted is the bundling command string on the two
|
||||
email processors (+ any resulting asset-hash / CDK metadata change). The
|
||||
dropped-vendored-boto3 functions MUST still 'import boto3' at runtime from
|
||||
the Lambda runtime copy.
|
||||
10. AWS access is READ-ONLY (get-function, get-function-event-invoke-config,
|
||||
SQS get-queue-attributes, S3 get-bucket-lifecycle-configuration,
|
||||
describe-alarms). NEVER cdk deploy, never invoke, never mutate, never
|
||||
purge a real queue.
|
||||
`
|
||||
|
||||
const PREAMBLE = `
|
||||
You are one of several agents building refactor Phase 7 in the git repo at
|
||||
${REPO} on branch ${BRANCH} (already checked out — do NOT switch branches,
|
||||
do NOT create branches, do NOT commit, NEVER push, do NOT run cdk deploy or
|
||||
touch AWS resources beyond read-only calls).
|
||||
Authoritative spec: docs/refactor-evaluation.md, section "Phase 7 — Ops/recovery + dependency hygiene".
|
||||
Work ONLY in the files you are told you own; other agents are concurrently
|
||||
editing other files in this same working tree.
|
||||
${CONSTRAINTS}
|
||||
Your final message is consumed by an orchestrator script, not a human —
|
||||
return only the structured data requested.
|
||||
`
|
||||
|
||||
// ------------------------------------------------------------------ schemas
|
||||
|
||||
const RECON = {
|
||||
type: 'object',
|
||||
required: ['summary', 'facts'],
|
||||
properties: {
|
||||
summary: { type: 'string' },
|
||||
facts: { type: 'array', items: { type: 'string' } },
|
||||
blockers: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const SPEC = {
|
||||
type: 'object',
|
||||
required: ['reprocessCli', 'contractTest', 'runbook', 'dependencyEdits', 'bundlingEdits', 'packageCleanup', 'verifyRules', 'notes'],
|
||||
properties: {
|
||||
reprocessCli: { type: 'string', description: 'the complete generalized scripts/reprocess.py design: argparse surface (--pipeline po|wo, --key/--prefix/--since, --all, --execute), per-pipeline function-name/bucket resolution, which modes are dry-run-by-default, and the EXACT --help + code-comment caveat text for --all (concurrency/no-serialize, RequestResponse-if-order-matters, double-count, Bedrock re-bill, out-of-order regression)' },
|
||||
contractTest: { type: 'string', description: 'the synthetic-event-shape contract test: file path, what it asserts about Records[0].s3.bucket.name / object.key, and the exact raw-key / no-URL-decoding assertion (encoded vs raw key example)' },
|
||||
runbook: { type: 'string', description: 'the docs/runbook-dlq-recovery.md outline: the no-redrive procedure steps (receive->key->targeted re-invoke via reprocess --key->verify->purge), the 14d-DLQ / 90d-S3 windows with the lifecycle-overrides-RETAIN note, the intentional sender-auth + ai_fallback_rejected non-DLQ statement, and the exact README alarms-section link edit' },
|
||||
dependencyEdits: { type: 'string', description: 'per requirements.txt: exact new contents (both email-processor empty-with-comment, wo/web_ui empty-with-comment, po/web_ui + po/site_extractor new pinned manifests, tests/ moto==<version>); the resolved moto version; the exact dependabot.yml additions matching the existing entry shape' },
|
||||
bundlingEdits: { type: 'string', description: 'both email-processor bundling command strings BEFORE and AFTER, verbatim: the cp-only result, proof that the pip step is safely removable (no third-party dep remains), and confirmation the exclude lists + widened root + any Phase-3 shared cp line are preserved' },
|
||||
packageCleanup: { type: 'string', description: 'the package/ dir cleanup: the exact rm command, why it is a filesystem rm not git rm (untracked), and why it is asset-hash-neutral given the Phase 2 exclude — this is a REPORTED local step, not a commit' },
|
||||
verifyRules: { type: 'string', description: 'how Verify judges success: which pytest tests must pass (incl. the new contract test), ruff scope now including scripts/, both cdk synth expectations, the dependabot yaml-parse check, requirements resolve/import check, and the runtime import-boto3 proof for the cp-only assets' },
|
||||
notes: { type: 'string' },
|
||||
},
|
||||
}
|
||||
|
||||
const IMPL = {
|
||||
type: 'object',
|
||||
required: ['filesChanged', 'summary', 'checksRun'],
|
||||
properties: {
|
||||
filesChanged: { type: 'array', items: { type: 'string' } },
|
||||
summary: { type: 'string' },
|
||||
checksRun: { type: 'string' },
|
||||
blockers: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const CHECKS = {
|
||||
type: 'object',
|
||||
required: ['passed', 'details'],
|
||||
properties: {
|
||||
passed: { type: 'boolean' },
|
||||
details: { type: 'string' },
|
||||
scopeViolations: { type: 'array', items: { type: 'string' } },
|
||||
},
|
||||
}
|
||||
|
||||
const FINDINGS = {
|
||||
type: 'object',
|
||||
required: ['findings'],
|
||||
properties: {
|
||||
findings: {
|
||||
type: 'array',
|
||||
items: {
|
||||
type: 'object',
|
||||
required: ['title', 'severity', 'confirmed', 'evidence', 'fix'],
|
||||
properties: {
|
||||
title: { type: 'string' },
|
||||
severity: { enum: ['critical', 'high', 'medium', 'low'] },
|
||||
confirmed: { type: 'boolean' },
|
||||
evidence: { type: 'string' },
|
||||
fix: { type: 'string' },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------- setup
|
||||
|
||||
phase('Setup')
|
||||
const setup = await agent(`
|
||||
In ${REPO}:
|
||||
1. SEQUENCING GATE — Phase 2 must be on ${BASE}. Phase 7 "can run parallel
|
||||
to 4-6" (largely independent), BUT the cp-only bundling simplification and
|
||||
the package/ cleanup touch the same cdk bundling that Phases 2/3
|
||||
established, so this phase must NOT race Phase 2. git fetch origin, then
|
||||
pick the base ref: origin/${BASE} if that remote ref exists, otherwise the
|
||||
local branch ${BASE} (a stacked local-only base is expected and fine).
|
||||
Verify on the base ref that BOTH cdk/po_stack.py and cdk/wo_stack.py
|
||||
contain Code.from_asset("../lambdas") for the email processors
|
||||
(git show <baseref>:cdk/po_stack.py | grep -n '\\.\\./lambdas', same for
|
||||
wo_stack.py). If either is missing, STOP with a blocker naming Phase 2 as
|
||||
unmet and do nothing else.
|
||||
NOTE (report, do not block): Phase 7 is otherwise independent of Phases
|
||||
4-6. If Phase 4 (cdk/common.py dedup) lands on ${BASE} FIRST, the
|
||||
stack-touching bundling edits here must be rebased onto the moved bundling
|
||||
code — flag that in your facts so the implement agents know whether the
|
||||
bundling lives inline or in a common helper.
|
||||
2. Verify clean working tree (untracked .coverage / .claude/ / the local
|
||||
44 MB lambdas/po/email_processor/package/ dir are fine; any OTHER dirt =
|
||||
blocker, never stash or discard).
|
||||
3. git checkout ${BASE}; then git pull --ff-only ONLY if the branch has an
|
||||
upstream (a local-only base skips the pull — not a blocker); then
|
||||
git checkout -b ${BRANCH}
|
||||
4. gh pr list --state open --json number,title,headRefName (overlap check —
|
||||
especially any in-flight Phase 2/3/4 stack PR).
|
||||
Return facts: HEAD sha, Phase 2 gate evidence, whether Phase 4 has landed
|
||||
(bundling inline vs helper), open PRs, blockers.
|
||||
`, { label: 'setup:branch', model: 'haiku', schema: RECON })
|
||||
|
||||
if (!setup || (setup.blockers && setup.blockers.length)) {
|
||||
return { aborted: 'setup blockers', blockers: setup ? setup.blockers : ['setup agent died'], facts: setup ? setup.facts : [] }
|
||||
}
|
||||
log(`Branch ${BRANCH} ready off ${BASE}. ${setup.summary}`)
|
||||
|
||||
// ------------------------------------------------------------------- recon
|
||||
|
||||
phase('Recon')
|
||||
const recon = await parallel([
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of scripts/reprocess.py and the event shape it must pin:
|
||||
1. Quote scripts/reprocess.py verbatim with file:line — the argparse surface
|
||||
today (--execute only), FUNCTION_NAME, get_bucket_name (po-only,
|
||||
po-ingest-emails-<acct>), list_inbound_keys (paginator, Prefix='inbound/'),
|
||||
build_s3_event (the exact Records/s3/bucket.name/object.key shape), the
|
||||
Event (async) InvocationType.
|
||||
2. Find the WO analogues so --pipeline wo can resolve: the workorder
|
||||
email-processor function name and its email bucket naming (grep the cdk
|
||||
stacks / function_name / bucket_name). State them exactly.
|
||||
3. Determine how the email-processor handler reads the key from an S3 event:
|
||||
does it URL-decode Records[].s3.object.key (urllib.parse.unquote_plus)?
|
||||
Quote the handler line. This decides the contract test's no-double-decode
|
||||
assertion (reprocess must emit the RAW key so the handler decode path is
|
||||
exercised exactly once — a pre-decoded key double-decodes '+'/'%20').
|
||||
4. Is there ANY existing test that touches scripts/reprocess.py? (grep tests/
|
||||
and scripts/). Where should the new synthetic-event contract test live so
|
||||
it is collected by the standard pytest run (repo-root pytest collects
|
||||
tests/ and both email_processor tests/ roots)? Note whether scripts/ is on
|
||||
sys.path for import.
|
||||
15-25 precise facts.`,
|
||||
{ label: 'recon:reprocess', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of the dependency / manifest / dependabot state:
|
||||
1. Quote every requirements.txt under lambdas/ and tests/ verbatim with path:
|
||||
lambdas/po/email_processor (boto3>=1.43.47), lambdas/wo/email_processor
|
||||
(boto3>=1.43.47), lambdas/wo/web_ui (boto3>=1.43.47 — dead manifest),
|
||||
tests/ (moto>=5.0.0), cdk/. Confirm po/web_ui and po/site_extractor have
|
||||
NO requirements.txt (they must be CREATED + pinned before a dependabot
|
||||
entry is not a no-op).
|
||||
2. Resolve the moto version to exact-pin: what 5.x is actually installed /
|
||||
currently resolves (pip show moto or the lockfile / venv)? State the exact
|
||||
version string to pin.
|
||||
3. Quote .github/dependabot.yml verbatim: the existing pip entries (/cdk,
|
||||
/lambdas/po/email_processor, /lambdas/wo/email_processor, /lambdas/wo/web_ui)
|
||||
and the github-actions entry — the exact shape (weekly interval,
|
||||
minor-and-patch group) the three NEW entries must match.
|
||||
4. Confirm via lambda-template.md (handbook) the exact empty-with-comment
|
||||
form for only-boto3 functions (the Lambda runtime provides boto3) — quote
|
||||
the canonical comment wording so the edits match the handbook.
|
||||
5. Does anything under lambdas/*/email_processor actually import a THIRD-PARTY
|
||||
package other than boto3 (grep imports; anthropic/requests/etc.)? If yes,
|
||||
cp-only is unsafe — that is a blocker for constraint 5.
|
||||
15-25 facts.`,
|
||||
{ label: 'recon:dependencies', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only recon of the post-Phase-2 CDK bundling + the package/ dir:
|
||||
1. Quote BOTH email-processor Code.from_asset blocks verbatim with current
|
||||
file:line (cdk/po_stack.py ~241, cdk/wo_stack.py ~240): asset root, the
|
||||
FULL exclude list, the entire bundling command list — the pip install
|
||||
'--platform manylinux2014_aarch64 --only-binary=:all: -r
|
||||
<pipeline>/email_processor/requirements.txt -t /asset-output' step, the
|
||||
'&&', the 'cp <pipeline>/email_processor/*.py /asset-output/' step, and
|
||||
whether a Phase-3 'cp shared/*.py /asset-output/' line is already present
|
||||
on this branch's base. Note the explanatory NOTE comment in po_stack.
|
||||
2. State the exact cp-only rewrite for each (drop the pip step entirely,
|
||||
keep every cp line + the widened root + the exclude list). Confirm the
|
||||
pip step is the ONLY thing removed.
|
||||
3. The three plain from_asset calls (po/web_ui, po/site_extractor,
|
||||
wo/web_ui) — quote them; they are NOT bundling-simplified here (no pip
|
||||
step), just confirm they are untouched by this phase.
|
||||
4. lambdas/po/email_processor/package/ — du -sh it, confirm it is UNTRACKED
|
||||
(git status / git ls-files must not list it), and confirm the Phase 2
|
||||
'**/package/**' exclude already keeps it out of the asset hash (so its
|
||||
removal is asset-hash-neutral).
|
||||
5. If Phase 4 has landed (bundling moved into a cdk/common helper) note the
|
||||
new location.
|
||||
12-20 facts.`,
|
||||
{ label: 'recon:cdk-bundling', model: 'haiku', phase: 'Recon', schema: RECON }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
Read-only AWS + docs recon for the runbook (region us-east-1, READ-ONLY):
|
||||
1. Both email-processor DLQs: exact SQS queue names/ARNs and the
|
||||
MessageRetentionPeriod (confirm the ~14-day breadcrumb window). Find them
|
||||
via the stacks (dead_letter_queue / make_processor_dlq) and
|
||||
aws sqs get-queue-attributes. Also the async event-invoke config /
|
||||
on-failure destination if present (get-function-event-invoke-config) —
|
||||
confirm it is an async on-failure destination DLQ with NO console
|
||||
redrive-to-source.
|
||||
2. Both raw-email S3 buckets: exact names and the inbound/ prefix lifecycle
|
||||
rule (get-bucket-lifecycle-configuration) — confirm the ~90-day expiry
|
||||
that overrides the table RETAIN policy (S3 is the replay floor).
|
||||
3. The relevant CloudWatch alarm names the runbook references: the
|
||||
sender-auth-rejected alarm(s) and the ai_fallback_rejected alarm(s) per
|
||||
pipeline (describe-alarms / grep the stacks) — so the runbook states that
|
||||
those two drop classes are fail-closed SKIPS that never reach the DLQ.
|
||||
4. Quote the README alarms section (its heading + surrounding lines) so the
|
||||
Implement agent can add the runbook link in the right place, matching
|
||||
style.
|
||||
Return names/ARNs/windows as facts; flag any name you could not resolve so
|
||||
the runbook can be validated against real infra later.`,
|
||||
{ label: 'recon:dlq-alarms', model: 'sonnet', phase: 'Recon', schema: RECON }),
|
||||
])
|
||||
|
||||
const reconOk = recon.filter(Boolean)
|
||||
const pack = reconOk.map(r => `## ${r.summary}\n${r.facts.join('\n')}`).join('\n\n')
|
||||
const reconBlockers = reconOk.flatMap(r => r.blockers || [])
|
||||
.filter(b => b && !/^\s*(none|n\/a)\b/i.test(b))
|
||||
log(`Recon complete: ${reconOk.length}/4 mappers, ${reconBlockers.length} blockers`)
|
||||
if (reconBlockers.length) {
|
||||
return { aborted: 'recon blockers (likely a surviving third-party dep blocking cp-only, or an unresolvable pipeline name)', blockers: reconBlockers, reconPack: pack }
|
||||
}
|
||||
|
||||
// -------------------------------------------------------------------- spec
|
||||
|
||||
phase('Spec')
|
||||
const spec = await agent(`${PREAMBLE}
|
||||
You are the SPEC agent — the single authority that pins every contested
|
||||
decision BEFORE parallel implementation (parallel leaves cannot see each
|
||||
other's choices). Using the recon pack below plus your own reads of the
|
||||
actual files, produce the binding implementation spec:
|
||||
- reprocessCli: the complete generalized scripts/reprocess.py — argparse
|
||||
surface (--pipeline po|wo required; --key / --prefix / --since targeted
|
||||
modes; --all for full-prefix; --execute preserving dry-run-by-default),
|
||||
the per-pipeline function-name + bucket resolution table, and the EXACT
|
||||
--help + in-code caveat text for --all (all five caveats from constraint 1
|
||||
verbatim). TARGETED is the default path; --all is the ONLY way to sweep the
|
||||
whole prefix.
|
||||
- contractTest: the synthetic-event-shape test — file path (collected by the
|
||||
standard pytest run), the assertions on Records[0].s3.bucket.name and
|
||||
object.key, and the raw-key / no-URL-decoding assertion with a concrete
|
||||
encoded-vs-raw example (e.g. a key with a space or '+').
|
||||
- runbook: the full docs/runbook-dlq-recovery.md outline with the real
|
||||
DLQ/queue/alarm/bucket names from recon, the no-redrive procedure steps
|
||||
(receive -> extract S3 key from event body -> targeted re-invoke via
|
||||
reprocess.py --key -> verify -> purge), the 14d-DLQ / 90d-S3 windows +
|
||||
lifecycle-overrides-RETAIN note, the intentional sender-auth +
|
||||
ai_fallback_rejected non-DLQ statement, and the exact README alarms-section
|
||||
link edit.
|
||||
- dependencyEdits: exact new contents of every manifest — both
|
||||
email-processor requirements.txt (handbook empty-with-comment), wo/web_ui
|
||||
(empty-with-comment), po/web_ui + po/site_extractor (NEW; decide pinned dep
|
||||
vs whether the dependabot entry is worthwhile — a dependabot entry needs at
|
||||
least one pinned dep to act on, so pin boto3 exactly if you want the entry
|
||||
live), tests/ (moto==<resolved version> from recon) — plus the exact
|
||||
dependabot.yml additions (three entries) matching the existing shape.
|
||||
- bundlingEdits: both email-processor bundling command strings BEFORE and
|
||||
AFTER, verbatim — the cp-only result, an explicit proof line that no
|
||||
third-party dep remains (so removing the whole pip step is safe, NOT a
|
||||
regression of the manylinux pin), and confirmation the exclude lists +
|
||||
widened '../lambdas' root + any Phase-3 'cp shared/*.py' line survive
|
||||
untouched. If Phase 4 moved bundling into a helper, target that location.
|
||||
- packageCleanup: the exact rm -rf command for
|
||||
lambdas/po/email_processor/package/, the note that it is a filesystem rm
|
||||
(UNTRACKED — never git rm) performed and REPORTED by the Package agent, not
|
||||
committed, and why it is asset-hash-neutral (Phase 2 exclude).
|
||||
- verifyRules: exactly how Verify judges success — the pytest set incl. the
|
||||
new contract test, ruff now INCLUDING scripts/, both cdk synth,
|
||||
dependabot.yml yaml-parse, requirements resolve/import, and the runtime
|
||||
'import boto3' proof for a cp-only staged asset.
|
||||
Recon pack:\n${pack}`,
|
||||
{ label: 'spec:pin-ops-recovery', phase: 'Spec', schema: SPEC })
|
||||
|
||||
if (!spec) return { aborted: 'spec agent died — rerun workflow', reconBlockers }
|
||||
const specBlock = `BINDING SPEC (from the spec agent — implement EXACTLY this):\n${JSON.stringify(spec, null, 2)}`
|
||||
log('Spec pinned: reprocess CLI + caveats, contract test, runbook, dependency edits, cp-only bundling, package cleanup')
|
||||
|
||||
// --------------------------------------------------------------- implement
|
||||
|
||||
phase('Implement')
|
||||
const impl = await parallel([
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: scripts/reprocess.py and the new synthetic-event contract test file
|
||||
ONLY (per spec.contractTest's path — do not touch any other test). Do not
|
||||
touch cdk/, requirements, dependabot, docs, or README.
|
||||
Task: rewrite scripts/reprocess.py per spec.reprocessCli — add --pipeline
|
||||
po|wo, --key/--prefix/--since (TARGETED, the default), --all (DEMOTED
|
||||
full-prefix, with all five caveats in BOTH --help and code comments),
|
||||
preserving dry-run-by-default / --execute. Keep build_s3_event emitting the
|
||||
RAW key (no URL-decoding). Then add the contract test per spec.contractTest
|
||||
pinning the event shape + the raw-key / no-double-decode assertion.
|
||||
Run before returning: ruff check scripts && ruff format scripts --check,
|
||||
python3 scripts/reprocess.py --help (must render the caveats), and
|
||||
pytest -q --no-cov -k <the contract test> (tests land in parallel — if
|
||||
collection of other roots is red from another agent's in-flight edit, run
|
||||
your test file directly; poll up to ~10 min before reporting a blocker).
|
||||
${specBlock}`,
|
||||
{ label: 'impl:reprocess', model: 'opus', phase: 'Implement', schema: IMPL }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: every requirements.txt (lambdas/po/email_processor,
|
||||
lambdas/wo/email_processor, lambdas/wo/web_ui, tests/, and the two NEW
|
||||
manifests lambdas/po/web_ui/requirements.txt +
|
||||
lambdas/po/site_extractor/requirements.txt), .github/dependabot.yml, and the
|
||||
bundling regions of cdk/po_stack.py + cdk/wo_stack.py ONLY (only the
|
||||
email-processor from_asset bundling command — alarms, IAM, tables, env,
|
||||
memory, timeout, the three plain from_asset calls are all off-limits).
|
||||
Task: apply spec.dependencyEdits (drop vendored boto3 -> empty-with-comment
|
||||
in both email-processor + wo/web_ui; create the two pinned po manifests;
|
||||
exact-pin moto==) + the three dependabot entries + spec.bundlingEdits
|
||||
(cp-only: remove ONLY the pip step from both email-processor commands,
|
||||
preserving the exclude lists, widened root, and any Phase-3 shared cp line).
|
||||
Do NOT delete package/ (that is the Package agent's reported step).
|
||||
Run before returning: ruff check cdk, python3 -c 'import yaml,pathlib;
|
||||
yaml.safe_load(pathlib.Path(".github/dependabot.yml").read_text())' (parses),
|
||||
cd cdk && npx cdk synth po-ingest -q -o /tmp/phase7-synth &&
|
||||
npx cdk synth workorder-ingest -q -o /tmp/phase7-synth (artifact-id
|
||||
selectors). Docker bundling runs — confirm each staged email-processor asset
|
||||
still contains handler.py + its siblings (and shared/*.py if Phase 3 landed)
|
||||
and that 'import boto3' resolves at runtime from the Lambda runtime copy (the
|
||||
staged asset need not vendor it). Note asset hashes. If the other agents'
|
||||
edits have not landed the synth is unaffected (bundling is yours) — but poll
|
||||
~10 min if Docker is slow before a blocker.
|
||||
${specBlock}`,
|
||||
{ label: 'impl:deps-bundling', model: 'sonnet', phase: 'Implement', schema: IMPL }),
|
||||
|
||||
() => agent(`${PREAMBLE}
|
||||
YOU OWN: docs/runbook-dlq-recovery.md (NEW) and README.md ONLY.
|
||||
Task A: write docs/runbook-dlq-recovery.md per spec.runbook — the no-redrive
|
||||
async-destination DLQ procedure (receive-message -> extract the S3 key from
|
||||
the event body -> targeted re-invoke via 'python scripts/reprocess.py
|
||||
--pipeline <po|wo> --key <key> --execute' -> verify the write -> purge the
|
||||
message), the real queue/bucket/alarm names from the spec, the recovery
|
||||
windows (14-day DLQ breadcrumb, 90-day raw-email S3 with the
|
||||
lifecycle-overrides-RETAIN note), and the explicit statement that sender-auth
|
||||
rejections AND ai_fallback_rejected drops are fail-closed SKIPS that never
|
||||
reach the DLQ (no retry, no DLQ message).
|
||||
Task B: README — link the new runbook from the alarms section per
|
||||
spec.runbook's exact edit, and note reprocess.py is now pipeline-general
|
||||
(--pipeline / --key / --prefix / --since targeted; --all demoted). Match
|
||||
existing README style.
|
||||
Run before returning: confirm the runbook links resolve and the README edit
|
||||
is in the alarms section. (No pytest owned by you; if you want a doc-lint,
|
||||
ruff does not lint .md.)
|
||||
${specBlock}`,
|
||||
{ label: 'impl:runbook-readme', model: 'opus', phase: 'Implement', schema: IMPL }),
|
||||
])
|
||||
|
||||
const implOk = impl.filter(Boolean)
|
||||
const implBlockers = implOk.flatMap(r => r.blockers || [])
|
||||
log(`Implement complete: ${implOk.length}/3 agents, blockers: ${implBlockers.length}`)
|
||||
|
||||
// ---------------------------------------------------- verify + fix loop
|
||||
|
||||
const EXPECTED_SCOPE = [
|
||||
'scripts/reprocess.py',
|
||||
'tests/',
|
||||
'docs/runbook-dlq-recovery.md',
|
||||
'lambdas/po/email_processor/requirements.txt',
|
||||
'lambdas/wo/email_processor/requirements.txt',
|
||||
'lambdas/wo/web_ui/requirements.txt',
|
||||
'lambdas/po/web_ui/requirements.txt',
|
||||
'lambdas/po/site_extractor/requirements.txt',
|
||||
'.github/dependabot.yml',
|
||||
'cdk/po_stack.py',
|
||||
'cdk/wo_stack.py',
|
||||
'README.md',
|
||||
]
|
||||
|
||||
const mechanicalPrompt = `${PREAMBLE}
|
||||
Independent re-verification — trust nothing self-reported. Run ALL gates,
|
||||
quoting failures verbatim:
|
||||
1. pytest -q --no-cov (repo root, all roots green) — INCLUDING the new
|
||||
synthetic-event contract test (name it and quote its pass line).
|
||||
2. ruff check . && ruff format --check . — scripts/ is now IN scope (it was
|
||||
previously omitted); confirm scripts/reprocess.py lints and formats clean.
|
||||
3. cd cdk && npx cdk synth po-ingest -q && npx cdk synth workorder-ingest -q
|
||||
(Docker bundling runs; both must succeed).
|
||||
4. cd cdk && npx cdk diff po-ingest ; npx cdk diff workorder-ingest —
|
||||
constraint 9: the ONLY resource delta allowed is the two email
|
||||
processors' Code/S3Key (asset) + CDK metadata. Any alarm/IAM/env/runtime/
|
||||
memory/timeout/handler-prop/logical-ID delta = FAIL. Paste the diff
|
||||
summaries.
|
||||
5. DEPENDABOT: python3 -c 'import yaml,pathlib; d=yaml.safe_load(pathlib.Path(".github/dependabot.yml").read_text()); print([u["directory"] for u in d["updates"]])'
|
||||
— the three new dirs (/tests, /lambdas/po/web_ui, /lambdas/po/site_extractor)
|
||||
present, shape matches existing entries.
|
||||
6. MANIFESTS: every email-processor + wo/web_ui requirements.txt is the
|
||||
empty-with-comment form (no pinned third-party dep); tests/requirements.txt
|
||||
is moto==<exact>; po/web_ui + po/site_extractor manifests EXIST and are
|
||||
PINNED (a dependabot entry pointed at a floor/absent manifest is a no-op —
|
||||
FAIL if unpinned). pip install --dry-run (or pip-compile check) resolves
|
||||
each without error.
|
||||
7. RUNTIME IMPORT: no lambda handler .py under lambdas/*/email_processor
|
||||
changed (git diff ${BASE}...HEAD -- must be empty for those); 'import boto3'
|
||||
still resolves — prove the Lambda runtime copy suffices (the cp-only staged
|
||||
asset need not vendor boto3).
|
||||
8. RUNBOOK: docs/runbook-dlq-recovery.md exists, states the 14d/90d windows,
|
||||
the no-redrive procedure, and the sender-auth + ai_fallback_rejected
|
||||
non-DLQ note; README alarms section links it.
|
||||
9. git status --porcelain scope check: every modified/added path under
|
||||
${EXPECTED_SCOPE.join(', ')} (untracked .coverage/.claude/package/
|
||||
tolerated; package/ must NOT be staged).
|
||||
passed=true only if all green. YOU MAY NOT edit files.`
|
||||
|
||||
const lenses = [
|
||||
{ key: 'bundling-integrity', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — bundling-integrity lens. The bundling was simplified to
|
||||
cp-only and vendored boto3 was dropped; try to prove a runtime ImportError
|
||||
was introduced (the PR #34 / PR #105 failure class). (1) cd cdk && synth both
|
||||
stacks; inside each staged email-processor asset dir list the files and run
|
||||
python3 -c "import handler" with that dir alone on sys.path (env-var stubs as
|
||||
needed) — does every runtime-imported module still ship (handler siblings +
|
||||
shared/*.py if Phase 3 landed)? (2) Does 'import boto3' succeed against the
|
||||
Lambda runtime copy — i.e. is boto3 genuinely NOT needed in the zip, or does
|
||||
some code path need a newer boto3 than the runtime ships? (3) Are the Phase
|
||||
2/3 excludes (['**/__pycache__/**','**/tests/**','**/package/**']) STILL
|
||||
present and is the widened '../lambdas' root intact? (4) Was the manylinux
|
||||
pin removed ONLY as part of removing the whole pip step (because nothing is
|
||||
installed), NOT while keeping a pip install? A cp-only command that still
|
||||
tries to pip-install without the pin, or a surviving third-party dep, is a
|
||||
critical finding. (5) DETERMINISM: synth po-ingest twice into fresh -o dirs —
|
||||
identical asset hashes. confirmed=true only with a concrete ImportError
|
||||
sketch or file:line proof.` },
|
||||
{ key: 'reprocess-safety', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — reprocess-safety lens. Attack the generalized
|
||||
reprocess.py. (1) Is the DEFAULT behavior TARGETED (—key/—prefix/—since), and
|
||||
is it IMPOSSIBLE to sweep the whole inbound/ prefix without the explicit
|
||||
--all flag? Trace the arg parsing — can a missing/empty --prefix silently
|
||||
fall through to a full-prefix replay? That would be a critical finding
|
||||
(accidental mass re-invoke = mass Bedrock re-bill + merged-field regression).
|
||||
(2) Are ALL FIVE --all caveats present in BOTH --help and code comments
|
||||
(concurrency/no-serialize, RequestResponse-if-order-matters, double-count,
|
||||
Bedrock re-bill, out-of-order regression)? (3) Does build_s3_event emit the
|
||||
RAW key with NO URL-decoding, and does the contract test actually FAIL if
|
||||
someone adds an unquote_plus (mutate it on a scratch copy and confirm red)?
|
||||
A key with a space/'+' must round-trip raw so the handler decodes exactly
|
||||
once. (4) --pipeline wo resolves the correct function name + bucket (not the
|
||||
PO defaults)? confirmed=true only with file:line or reproduced-failure
|
||||
evidence.` },
|
||||
{ key: 'dependency', prompt: `${PREAMBLE}
|
||||
ADVERSARIAL REVIEW — dependency lens. (1) moto: is tests/requirements.txt
|
||||
EXACT-pinned (moto==<version>), not a floor (>=)? A floor makes the tests/
|
||||
dependabot entry a no-op. (2) The three NEW dependabot dirs: do
|
||||
/lambdas/po/web_ui and /lambdas/po/site_extractor now have PINNED manifests
|
||||
that actually exist? A dependabot entry pointed at an absent or floor-pinned
|
||||
manifest does nothing — that is a finding. Cross-check dependabot.yml
|
||||
directory strings against the real file paths (a typo'd directory silently
|
||||
no-ops). (3) The email-processor + wo/web_ui requirements are the handbook
|
||||
empty-with-comment form — confirm no pinned third-party dep is left that
|
||||
would then require the pip step back (which would contradict the cp-only
|
||||
bundling). (4) Does the empty-with-comment wording match lambda-template.md
|
||||
(runtime provides boto3)? confirmed=true only with file:line evidence.` },
|
||||
]
|
||||
|
||||
let round = 0
|
||||
let checks = null
|
||||
let confirmed = []
|
||||
while (round < 3) {
|
||||
phase('Verify')
|
||||
const results = await parallel([
|
||||
() => agent(mechanicalPrompt, { label: `verify:mechanical-r${round}`, model: 'sonnet', phase: 'Verify', schema: CHECKS }),
|
||||
...lenses.map(l => () =>
|
||||
agent(l.prompt, { label: `verify:${l.key}-r${round}`, phase: 'Verify', schema: FINDINGS })),
|
||||
])
|
||||
checks = results[0]
|
||||
confirmed = results.slice(1).filter(Boolean)
|
||||
.flatMap(r => r.findings || [])
|
||||
.filter(f => f.confirmed && f.severity !== 'low')
|
||||
const green = checks && checks.passed
|
||||
log(`Verify round ${round}: mechanical ${checks && checks.passed ? 'GREEN' : 'RED'}, confirmed findings: ${confirmed.length}`)
|
||||
if (green && confirmed.length === 0) break
|
||||
|
||||
round += 1
|
||||
if (round >= 3) break
|
||||
phase('Fix')
|
||||
await agent(`${PREAMBLE}
|
||||
You are the fix agent — you may edit files under: ${EXPECTED_SCOPE.join(', ')}.
|
||||
Fix EVERY item below minimally; the binding spec and 10 pinned constraints
|
||||
still hold (a finding that conflicts with a constraint is reported, not
|
||||
"fixed" — the constraint wins, esp. constraint 5's cp-only-only-if-no-dep
|
||||
rule, constraint 8's do-NOT-git-rm-package, and constraint 9's no-handler /
|
||||
no-alarm change). Re-run the specific failing gate/test per fix.
|
||||
MECHANICAL:\n${checks ? checks.details : '(agent died — rerun all gates)'}
|
||||
CONFIRMED FINDINGS:\n${JSON.stringify(confirmed, null, 2)}
|
||||
${specBlock}`,
|
||||
{ label: `fix:round-${round}`, model: 'opus', phase: 'Fix', schema: IMPL })
|
||||
}
|
||||
|
||||
const verifyClean = checks && checks.passed && confirmed.length === 0
|
||||
if (!verifyClean) {
|
||||
return {
|
||||
status: 'NEEDS ATTENTION — verify not clean after 3 rounds; branch left uncommitted',
|
||||
branch: BRANCH,
|
||||
mechanical: checks,
|
||||
unresolvedFindings: confirmed,
|
||||
implBlockers,
|
||||
reconBlockers,
|
||||
spec,
|
||||
}
|
||||
}
|
||||
|
||||
// ----------------------------------------------------------------- package
|
||||
|
||||
phase('Package')
|
||||
const commit = await agent(`${PREAMBLE.replace('do NOT commit, ', '')}
|
||||
YOU are the commit agent:
|
||||
1. Read ~/Documents/repositories/seahaven/engineering-handbook/commit-messages.md
|
||||
and follow it exactly.
|
||||
2. OPTIONAL LOCAL CLEANUP (constraint 8): rm -rf
|
||||
lambdas/po/email_processor/package/ — it is UNTRACKED, so this is a
|
||||
filesystem rm, NOT git rm; there is NOTHING to stage from it and it is
|
||||
asset-hash-neutral (Phase 2 exclude). PERFORM it and REPORT the reclaimed
|
||||
~44 MB in your summary. It is NOT part of the commit.
|
||||
3. git add only paths under: ${EXPECTED_SCOPE.join(', ')} and
|
||||
.claude/workflows/phase-7-ops-recovery.js. NOT .coverage, NOT package/
|
||||
(it is gone / untracked either way). Verify the staged set with
|
||||
git status — the two NEW manifests and the new runbook MUST be staged.
|
||||
4. ONE commit; write the message to /tmp/phase7-commit-msg.txt and use
|
||||
git commit -F /tmp/phase7-commit-msg.txt (backticks in -m get eaten by
|
||||
zsh). Suggested subject:
|
||||
"feat: ops/recovery tooling + dependency hygiene — generalized reprocess, DLQ runbook, cp-only bundling (refactor phase 7)"
|
||||
Body: the reprocess generalization (targeted-primary, --all demoted with
|
||||
caveats) + contract test, the DLQ runbook + windows, the dropped vendored
|
||||
boto3 / cp-only bundling, the moto exact-pin + three dependabot entries
|
||||
with pinned manifests, and the reported (not committed) package/ cleanup.
|
||||
NO AI attribution / Co-Authored-By lines.
|
||||
5. Do NOT push. Return commit sha + shortstat + the package/ cleanup result
|
||||
in summary.`,
|
||||
{ label: 'package:commit', model: 'sonnet', phase: 'Package', schema: IMPL })
|
||||
|
||||
return {
|
||||
status: 'BUILT — committed locally, NOT pushed',
|
||||
branch: BRANCH,
|
||||
base: BASE,
|
||||
commit: commit ? commit.summary : 'commit agent died — commit manually',
|
||||
spec: { reprocessCli: spec.reprocessCli, runbook: spec.runbook, dependencyEdits: spec.dependencyEdits, bundlingEdits: spec.bundlingEdits, packageCleanup: spec.packageCleanup },
|
||||
implementation: implOk.map(r => r.summary),
|
||||
filesChanged: implOk.flatMap(r => r.filesChanged),
|
||||
verifyRounds: round + 1,
|
||||
blockers: implBlockers.concat(reconBlockers),
|
||||
outstandingGates: [
|
||||
'/sh-security-review NOT required (ops tooling + dependency hygiene only — no untrusted-input parsing, no auth code, no IAM/policy change). The pre-push deterministic scanners still run as the unattended backstop.',
|
||||
'cross-family cross_review.py NOT required (no IAM/policy change; no Lambda handler signature / event-shape / return-contract change — reprocess.py emits the SAME S3 event shape it always did, pinned by the new contract test).',
|
||||
'push + PR + gh pr checks green',
|
||||
'deploy-then-merge for the bundling/dep changes: deploy from branch, smoke green, one real email per pipeline (the dropped-vendored-boto3 email processors MUST still import boto3 at runtime from the Lambda runtime copy), expect ONE benign asset-hash redeploy from the package/ cleanup + cp-only change, THEN merge.',
|
||||
'reprocess.py + docs/runbook-dlq-recovery.md are ops/docs (no deploy risk), but the runbook should be VALIDATED against the real DLQ / alarm / bucket names before it is relied on in an incident.',
|
||||
'Confluence "AWS Architecture Map" — Phase 7 adds the DLQ-recovery runbook to the inventory; note the new runbook when the resource inventory is next refreshed.',
|
||||
],
|
||||
}
|
||||
4
.coveragerc
Normal file
4
.coveragerc
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
[run]
|
||||
omit =
|
||||
*/tests/*
|
||||
*/cdk.out/*
|
||||
5
.github/workflows/ci.yaml
vendored
5
.github/workflows/ci.yaml
vendored
|
|
@ -3,11 +3,14 @@ on:
|
|||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
ci:
|
||||
uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@fd60e4c9041784f666ac0fdefb9bec3c7fbf5143 # main
|
||||
with:
|
||||
source-dirs: "lambdas cdk tests"
|
||||
source-dirs: "lambdas cdk tests scripts"
|
||||
run-tests: true
|
||||
run-cdk-synth: true
|
||||
run-sam-validate: false
|
||||
|
|
|
|||
4
.github/workflows/dependency-review.yml
vendored
4
.github/workflows/dependency-review.yml
vendored
|
|
@ -1,6 +1,10 @@
|
|||
name: Dependency Review
|
||||
on:
|
||||
pull_request:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
review:
|
||||
uses: Sea-Haven-Industries/.github/.github/workflows/callable-dependency-review.yaml@fd60e4c9041784f666ac0fdefb9bec3c7fbf5143 # main
|
||||
|
|
|
|||
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -19,3 +19,4 @@ cdk.out/
|
|||
lambdas/*/*/package/
|
||||
.idea/
|
||||
# JetBrains user settings directory
|
||||
.coverage
|
||||
|
|
|
|||
100
README.md
100
README.md
|
|
@ -28,7 +28,7 @@ Coupa PO emails are received at `amazon_po@int.seahaven.com`, parsed **determini
|
|||
|
||||
**Deterministic template parser.** `template_parser.try_deterministic_parse()` classifies by exact subject regex, extracts the nested contract (`supplier{}`, `ship_to{}` — 8 keys, `line_items[]` — 10 keys per item), and returns a parsed result **only if** it passes a fail-closed validation gate: recursive exact key-set at every nesting level; `email_type` emitted **only** on the exact new-PO subject *and* a confirmed-safe `Status` (never defaulted — a cancellation misrouted as `new_po` would defeat the sticky-`Cancelled` guard); `po_number` shape + byte-equality with the subject, the body `PO ID`, the `Amazon Purchase Order #` heading, and the `orders/<id>` URL; duplicate-label anchor integrity (`Supplier`/`Shipping`/`Total` each appear twice, the first `Shipping` must be the literal `None` placeholder); money fidelity (every `Decimal` re-serializes byte-identically to its source token with a digit/comma border check — the thousands-separator-truncation kill switch — plus `sum(line amounts) == total`, proven against **both** `Total` blocks); bullet-metadata label discipline (closed label set, assigned by leading label, never ordinal — immune to the optional `Part Number` segment); USPS address shape on the raw pre-enrichment value; and rejection of any unparseable sentinel or residual `\r`/`\xa0` artifact. Multi-line-item (0.18%) and non-USD (0 observed) new-POs, comment emails, and anything else falls back to the AI extractor. The AI path is gated too: the untrusted email reaches Bedrock inside a neutralized `<email>` data block (forged tag lookalikes in the body are defanged) with `temperature=0`, and the raw model output must pass the fail-closed `validate_ai_fallback()` gate — the PO-specific nested contract (exact key-set at every level, with missing keys normalized rather than rejected), a `po_number` shape check hardened against fullwidth-digit and trailing-artifact injection (the same regex family protecting the DynamoDB partition key the handler builds from it), an `email_type` allow-list enforced *before* dispatch so a miss can never fall into the `new_po` default branch, and `Decimal`/`int`/`None` money typing (PO decodes with `parse_float=Decimal`) — before any DynamoDB write. **The template path is gate-enforced end-to-end; the AI-fallback path is validated and fail-closed — output that fails the gate is skipped, never written (see `ai_fallback_rejected` below), so a malformed or injected email raises the fallback rate rather than corrupting a record.** Every record emits one CloudWatch EMF metric (see below).
|
||||
|
||||
**Derived fields (`site_code`, `trade`, `fiscal_year`).** These three are **classified**, not verbatim-extracted, so neither parse path emits them directly — instead a deterministic Python classifier (`derived_fields.derive_all()`) computes them inside the shared `enrich_parsed()` post-stage, which runs identically on both paths. `trade` is a closed label set (the same one the AI prompt enumerates): `Plumbing - PM`, `Plumbing - Reactive`, `Electrical`, `HVAC`, `Dock Doors`, `Doors`, `Signage`, `Carpentry`, `Fencing/Gates`, `Conveyance/MHE`, `Painting`, `Flooring`, `Janitorial`, `Fire/Life Safety`, `Landscaping/Yard`, `Roofing`, `Security/Locksmith`, `Snow Removal`, `PO Uplift`, `General Building - Emergency`, `General Building - Handyman`, `General Building - Project`, `General Building`. Authority differs by path:
|
||||
**Derived fields (`site_code`, `trade`, `fiscal_year`).** These three are **classified**, not verbatim-extracted, so neither parse path emits them directly — instead a deterministic Python classifier (`derived_fields.derive_all()`) computes them inside the shared `enrich_parsed()` post-stage, which runs identically on both paths. `derived_fields.py` is byte-frozen this phase (shadow-bake freeze, per the constraint-9 module-diff gate); note for accuracy that its in-file docstring's "FAITHFUL v1 port" self-description is aspirational, not descriptive — the module is a deliberate **spec-superset** of the original `EXTRACTION_PROMPT` rule text (its own inline backtest-tuning comments diverge from those three prompt sections), with the LLM staying runtime-authoritative on the AI-fallback path during the bake regardless. The docstring reword is deferred to the first post-bake PR, since even a text-only edit is barred by this phase's machine-checked empty-diff gate on the file. `trade` is a closed label set (the same one the AI prompt enumerates): `Plumbing - PM`, `Plumbing - Reactive`, `Electrical`, `HVAC`, `Dock Doors`, `Doors`, `Signage`, `Carpentry`, `Fencing/Gates`, `Conveyance/MHE`, `Painting`, `Flooring`, `Janitorial`, `Fire/Life Safety`, `Landscaping/Yard`, `Roofing`, `Security/Locksmith`, `Snow Removal`, `PO Uplift`, `General Building - Emergency`, `General Building - Handyman`, `General Building - Project`, `General Building`. Authority differs by path:
|
||||
|
||||
- **Template path** — the parser leaves all three `null`, so Python is authoritative: it fills them.
|
||||
- **AI-fallback path** — the LLM value stays **authoritative during the bake** (Python fills only a gap the LLM left `null`, never overwrites), and Python additionally runs in **shadow mode**: `enrich_parsed()` emits one `DerivedFieldAgreement` EMF record per field comparing the two.
|
||||
|
|
@ -54,7 +54,7 @@ Or aggregate overall agreement per field: `| filter ispresent(DerivedFieldAgreem
|
|||
|---|---|---|
|
||||
| `po-email-processor` | S3 ObjectCreated | Claude extraction + DynamoDB write |
|
||||
| `po-ingest-site-extractor` | DynamoDB Streams | Site code/address extraction -> `verified-sites` |
|
||||
| `po-web-ui` | Manual invoke | HTML dashboard (public Function URL removed 2026-06-08, INFRA-74) |
|
||||
| `po-web-ui` | Manual invoke (authenticated — see Setup §6) | HTML dashboard (public Function URL removed 2026-06-08, INFRA-74) |
|
||||
|
||||
**Tables:**
|
||||
- `purchase-orders` (PK: `po_number`, Streams: NEW_IMAGE) — shared with seahaven-slack-bot (read-only; see Shared Resources)
|
||||
|
|
@ -80,7 +80,7 @@ Amazon APM work order emails (from Hexagon EAM / HxGN SmartCloud) are received a
|
|||
| Function | Trigger | Purpose |
|
||||
|---|---|---|
|
||||
| `workorder-email-processor` | S3 ObjectCreated | Claude extraction + DynamoDB write |
|
||||
| `workorder-web-ui` | Manual invoke | HTML dashboard (public Function URL removed 2026-06-08, INFRA-74) |
|
||||
| `workorder-web-ui` | Manual invoke (authenticated — see Setup §6) | HTML dashboard (public Function URL removed 2026-06-08, INFRA-74) |
|
||||
|
||||
**Tables:**
|
||||
- `WorkOrders` (PK: `work_order_id`) — `site-code-index` and `status-index` GSIs removed 2026-06-03 (audit M-20)
|
||||
|
|
@ -154,7 +154,9 @@ The `<fn>-duration` and `<fn>-throttles` alarms for `po-email-processor` and `wo
|
|||
|
||||
**Parse-outcome metric + fallback-rate alarm (workorder-ingest):** the WO processor writes one CloudWatch **EMF** line per email to namespace `Seahaven/WorkorderIngest`, metric `ParseOutcome` (Unit Count, value 1), dimensioned by `ParseMethod` (`template` | `ai_fallback` | `ai_fallback_rejected`) and `TemplateId` (`update_plaintext` | `assign_html` | `unknown`). `ai_fallback_rejected` counts AI-fallback output that failed the fail-closed `validate_ai_fallback()` gate (schema/enum/date contract on raw Bedrock output — prompt-injection defence) and was dropped without a DynamoDB write. Non-dimension EMF properties `ReasonCode` and `work_order_id` are queryable in Logs Insights but not promoted to metrics (kept low-cardinality). EMF is used instead of `PutMetricData` so there is no extra sync call / latency / IAM grant on the async hot path (the role already has `logs:PutLogEvents`). The alarm `workorder-email-processor-template-fallback-rate` fires when the AI-fallback share of parses — rejected fallback parses included, so a drift outage whose AI output also fails the gate cannot lower the observed rate while dropping mail — exceeds **15%** sustained (a `MathExpression` with `FILL(...,0)` and a ≥10-sample volume floor over 15-minute periods, eval 3 / datapoints 2) — catching Hexagon template-drift coverage collapse while the volume floor + `FILL` prevent low-volume false pages / `INSUFFICIENT_DATA`. ALARM-only `SnsAction` to `site-alerts`, no OK action, `NOT_BREACHING`. The 15-minute period is a deliberate deviation from the 5-minute house style to accumulate a stable denominator at the low ~760/day volume. A second alarm, `workorder-email-processor-ai-fallback-rejected`, pages on the rejected series itself (≥1 rejection per 5-min period, 2 of the last 6 periods — the sender-auth-rejected sparse-arrival idiom) because a gate rejection drops mail without error/retry/DLQ and would otherwise be silent.
|
||||
|
||||
**Parse-outcome metric + fallback-rate alarm (po-ingest):** the PO processor emits the same EMF shape to namespace `Seahaven/PoIngest`, metric `ParseOutcome`, dimensioned by `ParseMethod` (`template` | `ai_fallback` | `ai_fallback_rejected`) and `TemplateId` (`coupa_new_po` | `coupa_cancellation` | `unknown`), with `ReasonCode` (the fail-closed gate reason) and `po_number` as Logs-Insights ride-alongs. `ai_fallback_rejected` counts AI-fallback output that failed the fail-closed `validate_ai_fallback()` gate (nested key-set contract, `po_number` shape, `email_type` allow-list, `Decimal` money typing) and was dropped without a DynamoDB write.
|
||||
**WO Bedrock transport-error metric (Phase 8).** A Bedrock-side transport error (throttling, malformed response, non-JSON model text) during the AI-fallback attempt previously emitted **zero** `ParseOutcome` datapoints — the only emit sites were post-gate. `handler.py` now wraps the `extract_with_bedrock` call in a try/except that emits exactly one `ParseMethod=ai_fallback` / `ReasonCode=bedrock_error` datapoint and then re-raises (the exception still propagates into the errors alarm / DLQ path unchanged). This is an except-and-reraise, not a reorder: a gate-rejected email (Bedrock *returns* successfully, `validate_ai_fallback()` then rejects it) still emits only the single `ai_fallback_rejected` datapoint and nothing else — the except branch never fires because Bedrock did not raise — so the `workorder-email-processor-ai-fallback-rejected` "a rejected email emits nothing else" alarm contract holds with no double-count.
|
||||
|
||||
**Parse-outcome metric + fallback-rate alarm (po-ingest):** the PO processor emits the same EMF shape to namespace `Seahaven/PoIngest`, metric `ParseOutcome`, dimensioned by `ParseMethod` (`template` | `ai_fallback` | `ai_fallback_rejected`) and `TemplateId` (`coupa_new_po` | `coupa_cancellation` | `unknown`), with `ReasonCode` (the fail-closed gate reason) and `po_number` as Logs-Insights ride-alongs. `ai_fallback_rejected` counts AI-fallback output that failed the fail-closed `validate_ai_fallback()` gate (nested key-set contract, `po_number` shape, `email_type` allow-list, `Decimal` money typing) and was dropped without a DynamoDB write. The `ai_fallback_rejected` emission's `po_number` ride-along is clamped to 64 chars (`handler.py:118`, pinned by the PO-DC-02 regression test) — `telemetry.py`'s `DerivedFieldAgreement` `PythonValue`/`LlmValue` properties clamp the same way.
|
||||
|
||||
**Deliberate double-count:** unlike WO, PO emits `ParseMethod=ai_fallback` *before* the Bedrock call (so a Bedrock-side error still records the outcome) — a rejected email therefore always emits **both** an `ai_fallback` datapoint (pre-call) and an `ai_fallback_rejected` datapoint (post-gate), never just the latter. This is intentional and load-bearing, not a bug; the fallback-rate math below treats `fb` as already inclusive of every rejection.
|
||||
|
||||
|
|
@ -284,6 +286,8 @@ Both currently use default DynamoDB encryption — they are **not** yet on the s
|
|||
|
||||
**Consumer (read-only) — data contract:** `seahaven-slack-bot` imports both tables via `Table.fromTableName(...)` (`grantReadData`) and reads them from two Lambdas: `workorder-sync` (daily full-table scan into the Bedrock knowledge base) and `wo-po-lookup` (the Bedrock agent's direct WO lookup action group). The bot depends on the PK/SK schema above and these attributes: on `WorkOrders` — `description`, `wo_status`, `customer`, `site_code`, `building`, `address`, `severity`, `priority`, `assigned_to`, `date_reported`, `scheduled_start`, `due_date`, `updated_at`; on `WorkOrderComments` — `created_at` (used to sort comments), `commenter`, `text`. Any change to table name, key schema, these attribute names, or the encryption configuration (e.g. the INFRA-6 CMK migration) must be coordinated with `seahaven-slack-bot` before it ships, or the Bedrock agent breaks at runtime (not at deploy — the tables are imported by name, so there is no compile-time link).
|
||||
|
||||
**Stream field contract (`site_code`).** Three definitions of "is this a valid site code" have existed in this repo at once. The canonical shape is `derived_fields._STRICT_CODE_RE` (`[A-Z][A-Z0-9]{2,4}`, `fullmatch`) plus its skip-list semantics (a code-shaped token is only a real site code if it is *not* skip-listed, e.g. `LLC`/`INC`/`CORP`/`LTD`/`ATTN`), used by `derive_site_code()` (the `enrich_parsed()` classifier, see the **Derived fields** note in the Purchase Orders flow above). Honestly noted, not papered over: `lambdas/po/site_extractor/handler.py`'s own `SITE_CODE_PATTERN` (`[A-Z]{2,4}\d{1,2}`, prefix-anchored `.match`, digit-requiring) still diverges from the canonical shape as of this phase — it rejects valid all-letter codes like `KLAL` (which surface as permanent `pending-site-review` rows) and accepts overlong junk like `DLI6X`/`SNY55` that the canonical `fullmatch` would not. Reconciling `po-ingest-site-extractor`'s direct-field validation onto the canonical `derived_fields` shape is Phase 6 scope, tracked separately — this paragraph will be updated when it lands.
|
||||
|
||||
### `verified-sites` table (owned here)
|
||||
|
||||
Owned by this repo's `po-ingest` stack (`cdk/po_stack.py`). PK `siteCode` (S); default DynamoDB encryption (NOT the shared CMK).
|
||||
|
|
@ -328,24 +332,34 @@ Branch protection on `main` — all changes through PR.
|
|||
aws secretsmanager delete-secret --secret-id po-ingest/anthropic-api-key --force-delete-without-recovery
|
||||
aws secretsmanager delete-secret --secret-id workorder-ingest/anthropic-api-key --force-delete-without-recovery
|
||||
```
|
||||
6. Dashboards: `po-web-ui` and `workorder-web-ui` have no public endpoint (the Function URLs were removed 2026-06-08, INFRA-74). Invoke them through an authenticated path that forwards the `X-Auth-Token` header, e.g. `aws lambda invoke --function-name po-web-ui /tmp/out.json`.
|
||||
6. Dashboards: `po-web-ui` and `workorder-web-ui` have no public endpoint (the Function URLs were removed 2026-06-08, INFRA-74). A bare `aws lambda invoke --function-name po-web-ui /tmp/out.json` with no headers in the event is guaranteed a `401` — the handler fails closed (see [Web UI auth](#security)). Fetch the token and forward it in the event's `headers`:
|
||||
```bash
|
||||
TOKEN=$(aws secretsmanager get-secret-value --secret-id procurement-ingest/web-ui-auth-token --query SecretString --output text)
|
||||
aws lambda invoke --function-name po-web-ui --payload "{\"headers\":{\"x-auth-token\":\"$TOKEN\"}}" /tmp/out.json
|
||||
```
|
||||
|
||||
## Tests
|
||||
|
||||
Offline unit tests (no AWS, no network) run via pytest from the repo root:
|
||||
|
||||
```bash
|
||||
pip install pytest
|
||||
pip install -r tests/requirements.txt
|
||||
pytest
|
||||
```
|
||||
|
||||
**Test-root consolidation (Phase 8).** Both test roots are kept (`tests/` for genuinely cross-pipeline suites, plus each pipeline's own `lambdas/*/email_processor/tests/`), but loading is now single-sourced. A new repo-root `conftest.py` — not `tests/conftest.py`, which is never an ancestor of the pipeline test roots and so cannot load for a standalone `pytest lambdas/po/email_processor/tests` run — sets the dummy AWS env, imports `moto` before any handler import (registers moto's botocore stubber hook so boto3 sessions created afterwards are stubbable), and exposes the one `load_lambda_module(pipeline, name)` loader (implemented in `tests/support/loader.py`) that every handler exec in the suite goes through, including its `sys.modules` save/restore dance for the per-pipeline duplicated bare names (`template_parser`, `persistence`, etc. — `derived_fields`/`prompts`/`telemetry`/`extraction`/`enrichment` too). `tests/support/` is a small shared package (`FakeTable`, `FakeDynamoResource`, `FakeS3`, `load_email`, `load_golden`) used by both pipelines' `_po_parser_support.py`/`_wo_parser_support.py` shims — `load_golden` decodes JSON money with `parse_float=Decimal` unconditionally (load-bearing for PO's exact-money goldens; proven safe for WO, whose 55 golden fixtures contain zero float-typed JSON numbers). `test_local.py` (a root-level manual script that imported a handler at collection time, bypassing the loader gate, and globbed a nonexistent `samples/` dir) is deleted — the golden suites cover its role.
|
||||
|
||||
Coverage:
|
||||
- `tests/` — shared handler + cross-pipeline tests: `parse_raw_email` and `pad_zip`, the PO merge-write semantics (`test_po_merge.py`, #97, moto-backed), the fail-closed sender-authentication parser (`test_ses_auth.py`, INFRA-107), and the Phase 0 CDK-bundling/handler-import AST consistency check (`test_bundle_consistency.py` — see [Deploy-Pipeline Guards](#deploy-pipeline-guards-phase-0)).
|
||||
- `lambdas/wo/email_processor/tests/` — the deterministic WO parser suite: golden-file tests over 55 real scrubbed `.eml` fixtures (`test_parser.py`), fail-closed validation-gate rules and adversarial/injection cases (`test_validation_gate.py`), the issue #23 `comment_id` idempotency invariants (`test_comment_id.py`), the Bedrock-fallback dispatch/EMF-metric behavior with a mocked `invoke_model` (`test_bedrock_fallback.py`, which also carries the Phase 5 behavior pins — WO's mutually-exclusive emit and the `[0-9]+` key guard ahead of both saves), and the Phase 0 direct-invoke healthcheck contract (`test_healthcheck.py`). Golden JSON lives under `tests/fixtures/expected/`. After Phase 5 the suite patches accessors on the owning siblings (`extraction.bedrock`, `persistence.dynamodb`, `persistence.datetime`, `persistence.save_*`) rather than on `handler`.
|
||||
- `lambdas/po/email_processor/tests/` — the deterministic PO parser suite: golden-file tests over real scrubbed `.eml` fixtures (17 single-line new-PO + 8 cancellations, exact `Decimal`-aware golden comparison via `parse_float=Decimal`), fail-closed validation-gate coverage for **every** gate reason code (fixture-driven for body-level triggers under `fixtures/adversarial/`, direct `validate()` unit tests for candidate-level mutations), real multi-line and comment/non-Coupa fallback fixtures under `fixtures/ai-fallback/`, dual line-ending (CRLF/LF) parse-identity, two-path `enrich_parsed`/`save_new_po` parity (the site-extractor stream-contract guard), fixture hygiene (`ses_auth` pass + scrub-marker leak sweep), the Bedrock-fallback dispatch/EMF-metric behavior plus the Phase 5 behavior pins (`test_po_bedrock_fallback.py` — the pre-Bedrock `ai_fallback` emit and the additive rejected double-count), the `_save_merge` collapse parity to both `save_new_po`/`save_revision` (`test_po_save_merge_parity.py`), the `ai_fallback`-only shadow telemetry after the `enrich_parsed` move (`test_po_derived_wiring.py`), and the Phase 0 direct-invoke healthcheck contract (`test_po_healthcheck.py`). After Phase 5 the suite patches accessors/constants on the owning siblings (`po_extraction.bedrock`/`.BEDROCK_MODEL_ID`/`._EMAIL_TAG_RE`, `po_persistence.dynamodb`/`.PO_TABLE`, `po_enrichment.derive_all`/`.pad_zip`, `po_telemetry.DERIVED_METRIC_NAME`) rather than on `po_handler`; re-exported names it calls (`save_*`, `extract_with_claude`, `enrich_parsed`, `_emit_parse_method_metric`, `EXTRACTION_PROMPT`) stay on `po_handler`.
|
||||
- `tests/` — shared handler + cross-pipeline tests: `parse_raw_email` (`test_parse_raw_email.py`), the fail-closed sender-authentication parser (`test_ses_auth.py`, INFRA-107), the Phase 0 CDK-bundling/handler-import AST consistency check (`test_bundle_consistency.py` — see [Deploy-Pipeline Guards](#deploy-pipeline-guards-phase-0)), the `scripts/reprocess.py` synthetic S3-event-shape contract (`test_reprocess_contract.py`, Phase 7), and, new in Phase 8: the handler-level SES-auth reject seam per pipeline (`test_handler_auth_seam.py` — no auth monkeypatch + an empty `ALLOWED_DKIM_DOMAINS` must yield zero Bedrock calls, zero writes, no raise), and both web_ui functions' first coverage — fail-closed auth (`test_web_ui_auth.py`) and the handlers themselves, including a 401-without-a-table-scan assertion and a hostile-field escaping regression lock (`test_web_ui_handlers.py`).
|
||||
- `lambdas/wo/email_processor/tests/` — the deterministic WO parser suite: golden-file tests over 55 real scrubbed `.eml` fixtures (`test_parser.py`), fail-closed validation-gate rules and adversarial/injection cases (`test_validation_gate.py`), the issue #23 `comment_id` idempotency invariants (`test_comment_id.py`), the Bedrock-fallback dispatch/EMF-metric behavior with a mocked `invoke_model` (`test_bedrock_fallback.py`, which also carries the Phase 5 behavior pins — WO's mutually-exclusive emit and the `[0-9]+` key guard ahead of both saves), and the Phase 0 direct-invoke healthcheck contract (`test_healthcheck.py`). Golden JSON lives under `tests/fixtures/expected/`. New in Phase 8: `test_wo_bedrock_transport.py` (transport errors — throttle, missing `content`, empty content, non-JSON model text — plus the hand-computed no-double-count pin for the `handler.py` except-and-reraise metric wrap, and the multi-record failure-isolation pin) and `test_wo_merge.py` (a moto-backed mirror of `test_po_merge.py` against the `WorkOrders` table — null-status never clobbers `wo_status`, `created_at` immutable, `status`→`wo_status` mapping, `None` fields absent from `SET`, `record_type` only-when-present). After Phase 5 the suite patches accessors on the owning siblings (`extraction.bedrock`, `persistence.dynamodb`, `persistence.datetime`, `persistence.save_*`) rather than on `handler`.
|
||||
- `lambdas/po/email_processor/tests/` — the deterministic PO parser suite: golden-file tests over real scrubbed `.eml` fixtures (17 single-line new-PO + 8 cancellations, exact `Decimal`-aware golden comparison via `parse_float=Decimal`), fail-closed validation-gate coverage for **every** gate reason code (fixture-driven for body-level triggers under `fixtures/adversarial/`, direct `validate()` unit tests for candidate-level mutations), real multi-line and comment/non-Coupa fallback fixtures under `fixtures/ai-fallback/`, dual line-ending (CRLF/LF) parse-identity, two-path `enrich_parsed`/`save_new_po` parity (the site-extractor stream-contract guard), fixture hygiene (`ses_auth` pass + scrub-marker leak sweep), the Bedrock-fallback dispatch/EMF-metric behavior plus the Phase 5 behavior pins (`test_po_bedrock_fallback.py` — the pre-Bedrock `ai_fallback` emit and the additive rejected double-count), the `_save_merge` collapse parity to both `save_new_po`/`save_revision` (`test_po_save_merge_parity.py`), the `ai_fallback`-only shadow telemetry after the `enrich_parsed` move (`test_po_derived_wiring.py`, which gains the PO-DC-02 64-char `po_number` clamp regression pin in Phase 8), and the Phase 0 direct-invoke healthcheck contract (`test_po_healthcheck.py`). New in Phase 8: `test_po_bedrock_transport.py` (the same four transport-error cases as WO, asserting the pre-call `ai_fallback` metric survives and no partial write occurs, plus the multi-record failure-isolation pin) and, moved here from `tests/`: `test_po_merge.py` (#97, moto-backed merge-write semantics) and `test_pad_zip.py` (zip-code padding). After Phase 5 the suite patches accessors/constants on the owning siblings (`po_extraction.bedrock`/`.BEDROCK_MODEL_ID`/`._EMAIL_TAG_RE`, `po_persistence.dynamodb`/`.PO_TABLE`, `po_enrichment.derive_all`/`.pad_zip`, `po_telemetry.DERIVED_METRIC_NAME`) rather than on `po_handler`; re-exported names it calls (`save_*`, `extract_with_claude`, `enrich_parsed`, `_emit_parse_method_metric`, `EXTRACTION_PROMPT`) stay on `po_handler`.
|
||||
|
||||
All three roots are discovered by `pytest.ini` (`testpaths`).
|
||||
|
||||
**Coverage floor (Phase 8).** `pytest.ini`'s `addopts` runs `pytest-cov` with an explicit `--cov` path per first-party package (`lambdas/po/email_processor`, `lambdas/wo/email_processor`, `lambdas/po/web_ui`, `lambdas/wo/web_ui`, `lambdas/po/site_extractor`, `lambdas/shared`) rather than relying on an `__init__.py` package marker — none of these dirs have one, and adding one would perturb the CDK bundling asset-hash fingerprint for zero runtime benefit; `pytest-cov`'s path form measures by source file regardless of package markers. `site_extractor` is deliberately included even though it measures 0% until Phase 6 lands — coverage honesty, not a silent skip. `.coveragerc` omits `*/tests/*` and `*/cdk.out/*` so the pipeline test dirs (which sit inside their own `--cov` path) don't dilute the number. `--cov-fail-under` is the new permanent CI floor (constraint 10 — never ratcheted down).
|
||||
|
||||
**Ruff C901/PLR floor (Phase 8).** `ruff.toml` adds `extend-select = ["C901", "PLR"]` with `max-complexity = 12`, making the tree's pre-existing `# noqa: PLR09xx` suppressions load-bearing instead of inert (no config previously enabled the rules they suppressed). `scripts/` is in the lint scope. Findings that could not be split or were out of this phase's file-ownership were resolved with a per-file `[lint.per-file-ignores]` entry carrying a written justification — most notably `derived_fields.py` (shadow-bake freeze: even an in-file `noqa` comment is a barred edit) and the other Phase 3/5/6/7 frozen modules (`enrichment.py`, WO `template_parser.py`, both `ses_auth.py`/`emf.py`, `site_extractor/handler.py`, `scripts/reprocess.py`). PO's `template_parser.py` — this phase's one in-scope split target — clears the ceiling by decomposing `extract_new_po` and `_validate_new_po_values` into per-rule helpers instead of an ignore.
|
||||
|
||||
## Scripts
|
||||
|
||||
**Reprocess emails** (re-invoke an email-processor with a synthetic S3 event). `reprocess.py` is now **pipeline-general**: `--pipeline po|wo` selects the function + raw-email bucket. **Targeted replay** (`--key` one object, `--prefix`, or `--since` a `LastModified` timestamp) is the default, preferred mode; the full-prefix sweep is demoted behind an explicit `--all`. Every mode is dry-run unless `--execute`. See the [DLQ recovery runbook](docs/runbook-dlq-recovery.md) for the targeted single-key re-invoke flow.
|
||||
|
|
@ -393,34 +407,78 @@ lambdas/ # Phase 2: shared Code.from_asset("../lambdas") bundling
|
|||
telemetry.py # EMF ParseMethod + DerivedFieldAgreement emit wrappers (stdout EMF; no boto3)
|
||||
persistence.py # _write_fields/_merge_update + save_cancellation; save_new_po/save_revision collapsed into one behavior-identical _save_merge (sticky-cancel guard intact); lazy dynamodb accessor
|
||||
prompts.py # EXTRACTION_PROMPT (~181 lines); cross-ref header to derived_fields' rule tables
|
||||
template_parser.py # pure deterministic Coupa parser + fail-closed validation gate
|
||||
derived_fields.py # deterministic site_code/trade/fiscal_year classifier (untouched by Phase 3/5)
|
||||
template_parser.py # pure deterministic Coupa parser + fail-closed validation gate; Phase 8:
|
||||
# extract_new_po/_validate_new_po_values split into C901/PLR-clean per-rule
|
||||
# helpers (behavior byte-identical; see the ruff C901/PLR floor below)
|
||||
derived_fields.py # deterministic site_code/trade/fiscal_year classifier (untouched by Phase 3/5/8 -- shadow-bake freeze; ruff per-file-ignore instead of an in-file noqa)
|
||||
tests/ # golden-file + validation-gate + fallback-dispatch + healthcheck + save-merge-parity + behavior-pin tests + fixtures
|
||||
conftest.py # fake_dynamo fixture, patches persistence.dynamodb
|
||||
_po_parser_support.py # Phase 8: thin shim -- re-exports tests.support fakes/loader; PO module handles (template_parser, prompts, telemetry, extraction, enrichment, persistence)
|
||||
test_po_derived_fields.py # derived_fields.derive_all() unit tests
|
||||
test_po_derived_wiring.py # ai_fallback-only shadow-telemetry wiring; Phase 8 gains the PO-DC-02 64-char po_number clamp regression pin
|
||||
test_po_bedrock_transport.py # Phase 8: Bedrock transport errors (throttle/missing-content/empty-content/non-JSON) + pre-call metric survival + multi-record failure-isolation pin
|
||||
test_po_merge.py # Phase 8: moved from tests/ -- PO merge-write semantics tests (#97), moto-backed
|
||||
test_pad_zip.py # Phase 8: moved from tests/ -- PO zip-code padding tests
|
||||
site_extractor/
|
||||
web_ui/ # handler.py imports `from web_ui_auth import is_authenticated` (shared)
|
||||
wo/ # WO pipeline Lambdas
|
||||
email_processor/ # Phase 5: decomposed into ~5 flat siblings (no enrichment stage);
|
||||
# validate_ai_fallback + the [0-9]+ work_order_id key guard stay in
|
||||
# the handler loop AHEAD of both saves
|
||||
handler.py # event loop + fail-closed SES auth + [0-9]+ work_order_id key guard + {"healthcheck": true} early-return; lazy s3 accessor; re-exports EXTRACTION_PROMPT
|
||||
handler.py # event loop + fail-closed SES auth + [0-9]+ work_order_id key guard + {"healthcheck": true} early-return; lazy s3 accessor; re-exports EXTRACTION_PROMPT; Phase 8: the Bedrock call is wrapped in try/except so a transport error emits one ai_fallback/bedrock_error datapoint then re-raises (a gate rejection still emits only ai_fallback_rejected -- no double-count)
|
||||
extraction.py # extract_with_bedrock + _EMAIL_TAG_RE + EXTRACTION_PROMPT import; lazy bedrock accessor
|
||||
telemetry.py # emit_parse_metric EMF wrapper (stdout EMF; no boto3)
|
||||
persistence.py # save_work_order + _header_date_iso + save_event (#23 comment_id determinism kept WITH persistence); lazy dynamodb accessor
|
||||
prompts.py # EXTRACTION_PROMPT; cross-ref header to template_parser.CONTRACT_KEYS
|
||||
template_parser.py # pure deterministic parser + fail-closed validation gate
|
||||
template_parser.py # pure deterministic parser + fail-closed validation gate; Phase 8: the
|
||||
# template-path bad-status branch now returns "invalid_status" (was a
|
||||
# copy-paste "malformed_site_code") -- matches validate_ai_fallback's code
|
||||
# for the identical condition
|
||||
tests/ # golden-file + validation-gate + comment_id + fallback + healthcheck + behavior-pin tests
|
||||
conftest.py # fake_dynamo fixture, patches persistence.dynamodb (module-top `from _wo_parser_support import wo_persistence`, Phase 8)
|
||||
_wo_parser_support.py # Phase 8: rewritten OFF the bare `import handler` strategy -- re-exports tests.support fakes/loader; WO module handles (template_parser, persistence, extraction, telemetry)
|
||||
test_wo_merge.py # Phase 8: moto-backed WorkOrders save_work_order merge-semantics mirror of test_po_merge (null-status never clobbers wo_status, created_at immutable, status->wo_status mapping, None fields absent, record_type only-when-present)
|
||||
test_wo_bedrock_transport.py # Phase 8: Bedrock transport errors + the hand-computed emitted-series no-double-count pin for the handler.py except-and-reraise wrap + multi-record failure-isolation pin
|
||||
fixtures/
|
||||
ses-stamped/
|
||||
auth-pass-01.eml # Phase 8: the one new fixture allowed this phase -- a synthesized Authentication-Results header block (from WO_SES_HEADER in test_ses_auth.py), not scraped mail
|
||||
web_ui/ # handler.py imports `from web_ui_auth import is_authenticated` (shared)
|
||||
scripts/
|
||||
reprocess.py
|
||||
backfill_sites.py
|
||||
post-deploy-smoke.sh # CD gate: synchronous healthcheck invoke of both processors, checks FunctionError
|
||||
test_local.py # Parse sample emails through Bedrock locally (no AWS mutation)
|
||||
conftest.py # Phase 8: THE repo-root session-invariant conftest. rootdir is pinned by
|
||||
# pytest.ini at repo root, so this loads for every pytest invocation shape --
|
||||
# including a standalone `pytest lambdas/po/email_processor/tests` -- before
|
||||
# any collection import. Sets the dummy AWS env, imports moto BEFORE any
|
||||
# handler import (registers moto's botocore stubber hook so boto3 sessions
|
||||
# created afterwards are stubbable), and re-exports
|
||||
# `tests.support.loader.load_lambda_module`. Owns the session fixtures
|
||||
# (po_handler, wo_handler, email_handler, ses_auth, po_persistence,
|
||||
# po_enrichment, wo_persistence). Supersedes the old tests/conftest.py
|
||||
# (deleted -- it was never an ancestor of the pipeline test roots, so it
|
||||
# could not carry these invariants for a standalone pipeline-root run).
|
||||
tests/
|
||||
requirements.txt # Test-only deps (moto)
|
||||
conftest.py # AWS env stubs + module loader (per-pipeline + Phase 5 flat siblings, dependency-ordered, + shared/ fallback); po_persistence/po_enrichment handles for the root PO tests
|
||||
test_pad_zip.py # PO zip-code padding tests
|
||||
test_parse_raw_email.py # MIME parsing tests (PO + WO handlers)
|
||||
test_po_merge.py # PO merge-write semantics tests (#97)
|
||||
test_ses_auth.py # Sender-authentication parser tests (INFRA-107)
|
||||
test_bundle_consistency.py # AST check: bundling command ships every handler.py sibling import
|
||||
requirements.txt # Test-only deps (moto, pytest-cov)
|
||||
support/ # Phase 8: shared test package (tests/ itself has no __init__.py --
|
||||
# PEP-420 namespace resolution via the root conftest's sys.path insert)
|
||||
__init__.py # load_lambda_module + REPO_ROOT re-export, FIXTURE_DIRS, stems/
|
||||
# load_raw/load_email/load_golden (parse_float=Decimal, pinned safe
|
||||
# for both pipelines), and the superset FakeTable/FakeDynamoResource/FakeS3
|
||||
loader.py # the ONE load_lambda_module + sys.modules save/restore dance
|
||||
# (dependency-topological sibling tuple + web_ui_auth); every
|
||||
# pipeline handler exec in the suite goes through this
|
||||
test_parse_raw_email.py # MIME parsing tests (PO + WO handlers) -- stays at root, cross-pipeline
|
||||
test_ses_auth.py # Sender-authentication parser tests (INFRA-107) -- stays at root, cross-pipeline
|
||||
test_handler_auth_seam.py # Phase 8: handler-level SES-auth reject seam, per pipeline -- no auth
|
||||
# monkeypatch + empty ALLOWED_DKIM_DOMAINS -> zero Bedrock calls, zero
|
||||
# writes, no raise (closes the "delete the gate line, tests still pass" hole)
|
||||
test_web_ui_auth.py # Phase 8: shared/web_ui_auth.py -- fail-closed on unset ARN / Secrets
|
||||
# Manager exception, TTL cache refresh, header-matrix case-insensitivity,
|
||||
# non-ASCII-token documenting pin
|
||||
test_web_ui_handlers.py # Phase 8: both web_ui handlers (0% coverage before this phase) -- 401
|
||||
# without a table scan, authenticated render path, hostile-field escaping
|
||||
# regression lock
|
||||
test_bundle_consistency.py # AST check: bundling command ships every handler.py sibling import
|
||||
test_reprocess_contract.py # reprocess.py synthetic S3-event-shape contract (Phase 7)
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,2 +1,2 @@
|
|||
aws-cdk-lib==2.261.0
|
||||
constructs==10.6.0
|
||||
constructs==10.7.1
|
||||
|
|
|
|||
112
conftest.py
Normal file
112
conftest.py
Normal file
|
|
@ -0,0 +1,112 @@
|
|||
"""Repo-root pytest configuration -- the ONE loader of session invariants.
|
||||
|
||||
pytest's rootdir is pinned by pytest.ini at the repo root, so THIS conftest
|
||||
loads for EVERY invocation, including a standalone
|
||||
``pytest lambdas/po/email_processor/tests`` run: rootdir conftests load at
|
||||
session start, before any collection import. ``tests/conftest.py`` is NOT an
|
||||
ancestor of the pipeline test roots, which is exactly why it cannot carry the
|
||||
session invariants below.
|
||||
|
||||
The Lambda handlers create boto3 clients lazily on first use, but the moto
|
||||
stubber hook must still be registered before any client is ever constructed, so
|
||||
this conftest sets the dummy AWS env and imports moto BEFORE anything loads a
|
||||
handler.
|
||||
"""
|
||||
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parent
|
||||
|
||||
# The handlers build boto3 clients on first call; give boto3 a region and dummy
|
||||
# credentials so client construction works offline / under CI regardless of the
|
||||
# ambient environment.
|
||||
import os # noqa: E402
|
||||
|
||||
os.environ.setdefault("AWS_DEFAULT_REGION", "us-east-1")
|
||||
os.environ.setdefault("AWS_ACCESS_KEY_ID", "testing")
|
||||
os.environ.setdefault("AWS_SECRET_ACCESS_KEY", "testing")
|
||||
os.environ.setdefault("AWS_SESSION_TOKEN", "testing")
|
||||
|
||||
# Imported for its side effect and DELIBERATELY BEFORE the handler modules are
|
||||
# loaded below: moto registers its botocore stubber hook into botocore's
|
||||
# BUILTIN_HANDLERS at import time, and boto3 sessions only pick the hook up if
|
||||
# they are created AFTER that registration. This conftest chain is imported at
|
||||
# pytest session start -- before tests/test_po_merge.py gets a chance to import
|
||||
# moto -- so without this import the handler's module-level boto3 clients would
|
||||
# be created un-stubbable and the moto-backed suites would hit real AWS.
|
||||
import moto # noqa: F401,E402
|
||||
|
||||
# Put the repo root on sys.path so ``tests.support`` resolves as a PEP-420
|
||||
# namespace package from every invocation directory.
|
||||
if str(REPO_ROOT) not in sys.path:
|
||||
sys.path.insert(0, str(REPO_ROOT))
|
||||
|
||||
# The single loader lives in tests/support/loader.py; the root conftest exposes
|
||||
# it (constraint 1). Re-exported rather than reimplemented -- `from conftest
|
||||
# import ...` is unsafe with three conftest.py files across the roots.
|
||||
from tests.support.loader import load_lambda_module # noqa: E402,F401
|
||||
|
||||
|
||||
@pytest.fixture(scope="session")
|
||||
def po_handler():
|
||||
"""The PO email processor handler module."""
|
||||
return load_lambda_module("po", "email_processor/handler")
|
||||
|
||||
|
||||
@pytest.fixture(scope="session")
|
||||
def wo_handler():
|
||||
"""The WO email processor handler module."""
|
||||
return load_lambda_module("wo", "email_processor/handler")
|
||||
|
||||
|
||||
@pytest.fixture(scope="session")
|
||||
def po_persistence(po_handler):
|
||||
"""The PO persistence sibling (owns PO_TABLE + save_* after Phase 5).
|
||||
|
||||
load_lambda_module registers each sibling under ``<handler>__<sibling>`` in
|
||||
sys.modules (only the bare-name binding is restored afterwards), so the
|
||||
persistence module stays reachable here by its unique name. test_po_merge.py
|
||||
keys its moto table on ``po_persistence.PO_TABLE`` rather than a literal.
|
||||
"""
|
||||
return sys.modules["po_email_processor_handler__persistence"]
|
||||
|
||||
|
||||
@pytest.fixture(scope="session")
|
||||
def po_enrichment(po_handler):
|
||||
"""The PO enrichment sibling (owns pad_zip after Phase 5).
|
||||
|
||||
pad_zip is PURE and NOT re-exported by handler (handler's body never calls
|
||||
it -- it runs inside enrich_parsed), so test_pad_zip.py dereferences it on
|
||||
the owning module instead of po_handler.
|
||||
"""
|
||||
return sys.modules["po_email_processor_handler__enrichment"]
|
||||
|
||||
|
||||
@pytest.fixture(scope="session")
|
||||
def wo_persistence(wo_handler):
|
||||
"""The WO persistence sibling (owns save_work_order / save_event).
|
||||
|
||||
Reachable by its unique sys.modules name for test_wo_merge symmetry with
|
||||
po_persistence.
|
||||
"""
|
||||
return sys.modules["wo_email_processor_handler__persistence"]
|
||||
|
||||
|
||||
@pytest.fixture(params=["po_handler", "wo_handler"])
|
||||
def email_handler(request):
|
||||
"""Parametrized fixture yielding each email processor handler module."""
|
||||
return request.getfixturevalue(request.param)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def ses_auth():
|
||||
"""The single-sourced ses_auth module (lambdas/shared/, Phase 3).
|
||||
|
||||
Previously parameterized over the two per-pipeline copies to prove they
|
||||
stayed byte-identical; now there is exactly one copy, so this loads it
|
||||
once -- halving the test_ses_auth run.
|
||||
"""
|
||||
return load_lambda_module("shared", "ses_auth")
|
||||
|
|
@ -256,7 +256,7 @@ Plus `missing_required_field` for the required labeled fields (per-item metadata
|
|||
- **`ship_to.street`/`ship_to.address` join convention:** multi-line segments joined with `'\n'`; `address` = the lines from `ship_to.name` through `United States` inclusive (this is what `enrich_parsed` promotes to `ship_to_raw` on the site-extractor stream).
|
||||
- **`quantity`/`unit`/`price` source:** the Items-summary `<qty> <UNIT> x <price>` line (e.g. `1.0 EACH x 55,206.00`); the Lines-block `<qty> EA` line is gate evidence only (V13 numeric cross-check). Emails without a summary line (e.g. new-po-14) leave all three `null` — nullable by contract.
|
||||
- **V10 URL-id sweep outcome:** all 20 harvested new_po emails satisfy `orders/<id> == po_number` digit suffix — the strict V10 check stays live (no demotion needed); a corpus-sweep test locks it.
|
||||
- **Canonical `quantity`/`price` type = Decimal (DynamoDB Number), converged in the shared `enrich_parsed`:** `EXTRACTION_PROMPT` declares both fields as JSON strings, so a prompt-obedient Bedrock response arrives as `str` where the template path emits `Decimal`. The shared post-stage coerces numeric strings (thousands-separator-safe) to `Decimal` so both paths write the same attribute type to the purchase-orders table stream; non-numeric strings are left verbatim. Prompt rewording itself stays PR #2 scope. The two-path parity test feeds a prompt-shaped payload (string quantity/price, LLM-filled `site_code`) — never the parser-derived golden verbatim — so it cannot be circular.
|
||||
- **Canonical `quantity`/`price` type = Decimal (DynamoDB Number), converged in the shared `enrich_parsed`:** `EXTRACTION_PROMPT` declares both fields as JSON `"number or null"` (see the PR #2 prompt tweak above — `prompts.py:67-69`), not JSON strings; `parse_float=Decimal` already handles a conforming numeric response the same as the template path's `Decimal`. The shared post-stage's numeric-string-to-`Decimal` coercion (thousands-separator-safe) remains as a defensive net for a non-conforming model response that arrives as `str` anyway; non-numeric strings are left verbatim. `prompts.py` itself is frozen this phase — this is a doc-only correction. The two-path parity test feeds a prompt-shaped payload (string quantity/price, LLM-filled `site_code`) — never the parser-derived golden verbatim — so it cannot be circular.
|
||||
- **Second-pass header scrub (post-review):** the first-pass harvest scrub left the real SES `Feedback-ID` sender-identity hash on every Coupa fixture and, on the two non-Coupa fixtures, an embedded second SES block's `X-Ses-Receipt`, the Exchange cross-tenant UPN ciphertext, Gmail ARC `fh=` / `X-Gm-*` tokens, and related opaque routing blobs. All replaced with same-shape `ScrubbedFixture` placeholders (byte-safe, CRLF preserved); the fixture-hygiene test now asserts these token classes are scrubbed in every header block so regressions are caught.
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -45,6 +45,7 @@ template_id, reason_code).
|
|||
"""
|
||||
|
||||
import re
|
||||
from dataclasses import dataclass
|
||||
from decimal import Decimal, InvalidOperation
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
|
|
@ -274,7 +275,7 @@ def _clean(value):
|
|||
if value is None:
|
||||
return None
|
||||
v = value.replace("\r", "").replace(" ", " ").strip()
|
||||
if v == "" or v == "None":
|
||||
if v in ("", "None"):
|
||||
return None
|
||||
return v
|
||||
|
||||
|
|
@ -419,30 +420,10 @@ def _assign_bullet_metadata(item, raw_line):
|
|||
item[field] = _clean(value)
|
||||
|
||||
|
||||
def extract_new_po(email_data):
|
||||
"""Extract the new_po contract from the text/plain body.
|
||||
|
||||
Permissive capture, section-windowed: each anchor line is located by exact
|
||||
_clean-ed full-line equality, STRICTLY AFTER the previous anchor. Missing
|
||||
anchors leave fields None -- the gate then fails closed. Representation-
|
||||
agnostic: matches only on _clean-ed lines, never on '\\r'-suffixed literals
|
||||
(body line endings are decode-path dependent).
|
||||
|
||||
Duplicate labels: 'Supplier', 'Shipping', 'Total' each appear TWICE (summary
|
||||
placeholder + detail block; the first 'Shipping' value is literally 'None').
|
||||
supplier.name anchors on the FIRST 'Supplier'; ship_to on the SECOND
|
||||
'Shipping'; total on the SECOND 'Total'.
|
||||
|
||||
DERIVED_KEYS (site_code, trade, fiscal_year) stay None -- filled later by
|
||||
the shared post-stage identically on both paths.
|
||||
"""
|
||||
candidate = _empty_candidate()
|
||||
candidate["email_type"] = "new_po"
|
||||
candidate["po_number"] = _subject_po_id(email_data)
|
||||
|
||||
lines = _plain_lines(email_data["body"])
|
||||
|
||||
# --- Summary section (start .. 'More Detail') ---
|
||||
def _extract_summary_section(candidate, lines):
|
||||
"""Summary block (start .. 'More Detail'): submitted_by, on_behalf_of, the
|
||||
FIRST 'Supplier' name, the unique view_order_url, and the Items-summary
|
||||
quantity lines. Returns (more_detail_index_or_None, summary_item_matches)."""
|
||||
more_detail = _find_after(lines, "More Detail", 0)
|
||||
summary_end = more_detail if more_detail is not None else len(lines)
|
||||
for label, field in (
|
||||
|
|
@ -473,8 +454,15 @@ def extract_new_po(email_data):
|
|||
for i in range(summary_end)
|
||||
if (m := _SUMMARY_ITEM_RE.fullmatch(_clean(lines[i]) or ""))
|
||||
]
|
||||
return more_detail, summary_items
|
||||
|
||||
# --- More Detail block ('More Detail' .. second 'Supplier') ---
|
||||
|
||||
def _extract_more_detail_block(candidate, lines, more_detail):
|
||||
"""More Detail block ('More Detail' .. second 'Supplier'): the labeled
|
||||
header fields. Returns the second 'Supplier' index (or None).
|
||||
|
||||
The FIRST 'Shipping' lives in this block; its value must be the literal
|
||||
'None' placeholder (gate rule V4 tripwire) and is never used for ship_to."""
|
||||
sup2 = None
|
||||
if more_detail is not None:
|
||||
sup2 = _find_after(lines, "Supplier", more_detail + 1)
|
||||
|
|
@ -485,53 +473,102 @@ def extract_new_po(email_data):
|
|||
j = _next_visible(lines, idx, md_end)
|
||||
if j is not None:
|
||||
candidate[field] = _clean(lines[j])
|
||||
# The FIRST 'Shipping' lives in this block; its value must be the literal
|
||||
# 'None' placeholder (gate rule V4 tripwire) and is never used for ship_to.
|
||||
return sup2
|
||||
|
||||
# --- ship_to (second 'Shipping' .. 'Lines'), sentinel-anchored ---
|
||||
|
||||
def _fill_location_attn(ship_to, lines, start, end):
|
||||
"""Location Code + Attn lines after the 'United States' sentinel; the first
|
||||
of each wins (mirrors the extractor's None-guarded assignment)."""
|
||||
for j in range(start, end):
|
||||
cl = _clean(lines[j]) or ""
|
||||
lc = _LOCATION_CODE_RE.fullmatch(cl)
|
||||
if lc and ship_to["location_code"] is None:
|
||||
ship_to["location_code"] = lc.group("lc")
|
||||
attn = _ATTN_RE.fullmatch(cl)
|
||||
if attn and ship_to["attn"] is None:
|
||||
ship_to["attn"] = _clean(attn.group("attn"))
|
||||
|
||||
|
||||
def _fill_ship_to_address(ship_to, lines, ship2, st_end):
|
||||
"""Populate ship_to from the second 'Shipping' block, sentinel-anchored on
|
||||
the 'United States' line that terminates the address."""
|
||||
name_idx = _next_visible(lines, ship2, st_end)
|
||||
if name_idx is None:
|
||||
return
|
||||
ship_to["name"] = _clean(lines[name_idx])
|
||||
us_idx = _find_after(lines, _US_SENTINEL, name_idx + 1)
|
||||
if us_idx is None or us_idx >= st_end:
|
||||
return
|
||||
city_idx = us_idx - 1
|
||||
m = None
|
||||
if city_idx > name_idx:
|
||||
m = _CITY_STATE_ZIP_RE.fullmatch(_clean(lines[city_idx]) or "")
|
||||
if m:
|
||||
ship_to["city"] = m.group("city")
|
||||
ship_to["state"] = m.group("state")
|
||||
ship_to["zip"] = m.group("zip")
|
||||
street = [
|
||||
_clean(lines[j])
|
||||
for j in range(name_idx + 1, city_idx)
|
||||
if _visible(lines[j])
|
||||
]
|
||||
if street:
|
||||
ship_to["street"] = "\n".join(street)
|
||||
ship_to["address"] = "\n".join(
|
||||
_clean(lines[j]) for j in range(name_idx, us_idx + 1) if _visible(lines[j])
|
||||
)
|
||||
_fill_location_attn(ship_to, lines, us_idx + 1, st_end)
|
||||
|
||||
|
||||
def _extract_ship_to(candidate, lines, sup2):
|
||||
"""ship_to block (second 'Shipping' .. 'Lines'). Returns the 'Lines' anchor
|
||||
index (or None)."""
|
||||
ship2 = _find_after(lines, "Shipping", sup2 + 1) if sup2 is not None else None
|
||||
lines_anchor = _find_after(lines, "Lines", ship2 + 1) if ship2 is not None else None
|
||||
st_end = lines_anchor if lines_anchor is not None else len(lines)
|
||||
ship_to = candidate["ship_to"]
|
||||
if ship2 is not None:
|
||||
name_idx = _next_visible(lines, ship2, st_end)
|
||||
if name_idx is not None:
|
||||
ship_to["name"] = _clean(lines[name_idx])
|
||||
us_idx = _find_after(lines, _US_SENTINEL, name_idx + 1)
|
||||
if us_idx is not None and us_idx < st_end:
|
||||
city_idx = us_idx - 1
|
||||
m = None
|
||||
if city_idx > name_idx:
|
||||
m = _CITY_STATE_ZIP_RE.fullmatch(_clean(lines[city_idx]) or "")
|
||||
if m:
|
||||
ship_to["city"] = m.group("city")
|
||||
ship_to["state"] = m.group("state")
|
||||
ship_to["zip"] = m.group("zip")
|
||||
street = [
|
||||
_clean(lines[j])
|
||||
for j in range(name_idx + 1, city_idx)
|
||||
if _visible(lines[j])
|
||||
]
|
||||
if street:
|
||||
ship_to["street"] = "\n".join(street)
|
||||
ship_to["address"] = "\n".join(
|
||||
_clean(lines[j])
|
||||
for j in range(name_idx, us_idx + 1)
|
||||
if _visible(lines[j])
|
||||
)
|
||||
for j in range(us_idx + 1, st_end):
|
||||
cl = _clean(lines[j]) or ""
|
||||
lc = _LOCATION_CODE_RE.fullmatch(cl)
|
||||
if lc and ship_to["location_code"] is None:
|
||||
ship_to["location_code"] = lc.group("lc")
|
||||
attn = _ATTN_RE.fullmatch(cl)
|
||||
if attn and ship_to["attn"] is None:
|
||||
ship_to["attn"] = _clean(attn.group("attn"))
|
||||
_fill_ship_to_address(candidate["ship_to"], lines, ship2, st_end)
|
||||
return lines_anchor
|
||||
|
||||
# --- Lines section ('Lines' .. second 'Total') ---
|
||||
# Item blocks are delimited by the lone U+00A0 line(s). EVERY block is
|
||||
# extracted, even when >1, so gate rule 7 fires with honest
|
||||
# multiline_unsupported data (never silently keep item 0).
|
||||
|
||||
def _parse_line_blocks(lines, start, end):
|
||||
"""Split the Lines section into U+00A0-delimited blocks and build one line
|
||||
item per non-empty block. EVERY block is extracted, even when >1, so gate
|
||||
rule 7 fires with honest multiline_unsupported data (never silently keep
|
||||
item 0)."""
|
||||
blocks, block = [], []
|
||||
for j in range(start, end):
|
||||
if lines[j].replace("\r", "") == "\xa0":
|
||||
blocks.append(block)
|
||||
block = []
|
||||
else:
|
||||
block.append(lines[j])
|
||||
blocks.append(block)
|
||||
items = []
|
||||
for block in blocks:
|
||||
visible = [ln for ln in block if _visible(ln)]
|
||||
if not visible:
|
||||
continue
|
||||
item = _empty_line_item()
|
||||
for raw in visible:
|
||||
dm = _LINE_DESC_AMT_RE.fullmatch(_clean(raw) or "")
|
||||
if dm and item["description"] is None:
|
||||
item["description"] = _clean(dm.group("desc"))
|
||||
item["amount"] = _to_decimal(dm.group("amt"))
|
||||
item["currency"] = dm.group("cur")
|
||||
elif _BULLET in raw:
|
||||
_assign_bullet_metadata(item, raw)
|
||||
# The optional '<qty> EA' evidence line is not stored: quantity/
|
||||
# unit/price come from the Items summary; gate rule V13 cross-checks
|
||||
# the EA line against it from the body.
|
||||
items.append(item)
|
||||
return items
|
||||
|
||||
|
||||
def _extract_line_items(candidate, lines, lines_anchor, summary_items):
|
||||
"""Lines section ('Lines' .. second 'Total'). Populates line_items,
|
||||
coupa_category, and (single-line only) quantity/unit/price from the Items
|
||||
summary. Returns the second 'Total' index (or None)."""
|
||||
total2 = (
|
||||
_find_after(lines, "Total", lines_anchor + 1)
|
||||
if lines_anchor is not None
|
||||
|
|
@ -540,31 +577,7 @@ def extract_new_po(email_data):
|
|||
items = []
|
||||
if lines_anchor is not None:
|
||||
end = total2 if total2 is not None else len(lines)
|
||||
blocks, block = [], []
|
||||
for j in range(lines_anchor + 1, end):
|
||||
if lines[j].replace("\r", "") == "\xa0":
|
||||
blocks.append(block)
|
||||
block = []
|
||||
else:
|
||||
block.append(lines[j])
|
||||
blocks.append(block)
|
||||
for block in blocks:
|
||||
visible = [ln for ln in block if _visible(ln)]
|
||||
if not visible:
|
||||
continue
|
||||
item = _empty_line_item()
|
||||
for raw in visible:
|
||||
dm = _LINE_DESC_AMT_RE.fullmatch(_clean(raw) or "")
|
||||
if dm and item["description"] is None:
|
||||
item["description"] = _clean(dm.group("desc"))
|
||||
item["amount"] = _to_decimal(dm.group("amt"))
|
||||
item["currency"] = dm.group("cur")
|
||||
elif _BULLET in raw:
|
||||
_assign_bullet_metadata(item, raw)
|
||||
# The optional '<qty> EA' evidence line is not stored: quantity/
|
||||
# unit/price come from the Items summary; gate rule V13
|
||||
# cross-checks the EA line against it from the body.
|
||||
items.append(item)
|
||||
items = _parse_line_blocks(lines, lines_anchor + 1, end)
|
||||
if items:
|
||||
candidate["line_items"] = items
|
||||
# coupa_category is a VERBATIM copy of item 0's Category bullet value.
|
||||
|
|
@ -574,19 +587,56 @@ def extract_new_po(email_data):
|
|||
items[0]["quantity"] = _to_decimal(m.group("qty"))
|
||||
items[0]["unit"] = m.group("unit")
|
||||
items[0]["price"] = _to_decimal(m.group("price"))
|
||||
return total2
|
||||
|
||||
# --- Total block (second 'Total' .. end) ---
|
||||
if total2 is not None:
|
||||
amt_idx = _next_visible(lines, total2)
|
||||
if amt_idx is not None:
|
||||
token = _clean(lines[amt_idx]) or ""
|
||||
if _MONEY_RE.fullmatch(token):
|
||||
candidate["total_amount"] = _to_decimal(token)
|
||||
cur_idx = _next_visible(lines, amt_idx)
|
||||
if cur_idx is not None:
|
||||
cur_token = _clean(lines[cur_idx]) or ""
|
||||
if _CURRENCY_RE.fullmatch(cur_token):
|
||||
candidate["currency"] = cur_token
|
||||
|
||||
def _extract_total_block(candidate, lines, total2):
|
||||
"""Total block (second 'Total' .. end): total_amount + currency."""
|
||||
if total2 is None:
|
||||
return
|
||||
amt_idx = _next_visible(lines, total2)
|
||||
if amt_idx is None:
|
||||
return
|
||||
token = _clean(lines[amt_idx]) or ""
|
||||
if _MONEY_RE.fullmatch(token):
|
||||
candidate["total_amount"] = _to_decimal(token)
|
||||
cur_idx = _next_visible(lines, amt_idx)
|
||||
if cur_idx is not None:
|
||||
cur_token = _clean(lines[cur_idx]) or ""
|
||||
if _CURRENCY_RE.fullmatch(cur_token):
|
||||
candidate["currency"] = cur_token
|
||||
|
||||
|
||||
def extract_new_po(email_data):
|
||||
"""Extract the new_po contract from the text/plain body.
|
||||
|
||||
Permissive capture, section-windowed: each anchor line is located by exact
|
||||
_clean-ed full-line equality, STRICTLY AFTER the previous anchor. Missing
|
||||
anchors leave fields None -- the gate then fails closed. Representation-
|
||||
agnostic: matches only on _clean-ed lines, never on '\\r'-suffixed literals
|
||||
(body line endings are decode-path dependent).
|
||||
|
||||
Duplicate labels: 'Supplier', 'Shipping', 'Total' each appear TWICE (summary
|
||||
placeholder + detail block; the first 'Shipping' value is literally 'None').
|
||||
supplier.name anchors on the FIRST 'Supplier'; ship_to on the SECOND
|
||||
'Shipping'; total on the SECOND 'Total'.
|
||||
|
||||
Delegated section by section to the _extract_* helpers, threading the
|
||||
anchor indices each stage discovers into the next; DERIVED_KEYS (site_code,
|
||||
trade, fiscal_year) stay None -- filled later by the shared post-stage
|
||||
identically on both paths.
|
||||
"""
|
||||
candidate = _empty_candidate()
|
||||
candidate["email_type"] = "new_po"
|
||||
candidate["po_number"] = _subject_po_id(email_data)
|
||||
|
||||
lines = _plain_lines(email_data["body"])
|
||||
|
||||
more_detail, summary_items = _extract_summary_section(candidate, lines)
|
||||
sup2 = _extract_more_detail_block(candidate, lines, more_detail)
|
||||
lines_anchor = _extract_ship_to(candidate, lines, sup2)
|
||||
total2 = _extract_line_items(candidate, lines, lines_anchor, summary_items)
|
||||
_extract_total_block(candidate, lines, total2)
|
||||
|
||||
# DERIVED_KEYS intentionally left None (shared post-stage fills them).
|
||||
return _normalize(candidate)
|
||||
|
|
@ -608,9 +658,14 @@ def _structural_keys_ok(candidate):
|
|||
return all(set((it or {}).keys()) == set(LINE_ITEM_KEYS) for it in items)
|
||||
|
||||
|
||||
def validate(candidate, template_id, email_data):
|
||||
def validate(candidate, template_id, email_data): # noqa: C901, PLR0911, PLR0912
|
||||
"""Return (True, 'ok') only if provably conformant; else (False, reason).
|
||||
Every rule must hold. See failClosedGateRules in the investigation report."""
|
||||
Every rule must hold. See failClosedGateRules in the investigation report.
|
||||
|
||||
A linear fail-closed rule ladder with one return per reason code -- the
|
||||
branch count is the rule count. Splitting it further adds indirection, not
|
||||
clarity, so the complexity/return/branch ceilings are suppressed here (the
|
||||
value-level rules V1-V13 ARE decomposed, in _validate_new_po_values)."""
|
||||
# (1) known template
|
||||
if template_id not in _TEMPLATE_EMAIL_TYPE:
|
||||
return False, "subject_no_match"
|
||||
|
|
@ -689,218 +744,320 @@ def _money_border_ok(line_text, serialized):
|
|||
return False
|
||||
|
||||
|
||||
def _validate_new_po_values(candidate, email_data): # noqa: PLR0911, PLR0912, PLR0915
|
||||
"""Value-level gate rules V1-V13 for coupa_new_po. FAIL CLOSED.
|
||||
@dataclass
|
||||
class _NewPoAnchorFrame:
|
||||
"""Anchor frame for the coupa_new_po value gate.
|
||||
|
||||
Anchor integrity (V4) runs first because every later byte proof needs the
|
||||
anchor frame; the remaining rules run in spec order. Each rule re-derives
|
||||
its evidence from email_data["body"] -- duplicated regex work, negligible
|
||||
at ~57 emails/day, in exchange for extractor-bug independence."""
|
||||
lines = _plain_lines(email_data["body"])
|
||||
items = candidate.get("line_items") or []
|
||||
ship_to = candidate.get("ship_to") or {}
|
||||
supplier_name = (candidate.get("supplier") or {}).get("name")
|
||||
V4 (_build_anchor_frame) proves the duplicate-label anchor layout ONCE and
|
||||
carries the shared byte evidence every later rule re-derives from the body:
|
||||
the section indices, plus the Items-summary matches and the captured line
|
||||
price -- so V13 (_check_qty_unit_price) can re-consume exactly what V1
|
||||
(_check_money_fidelity) proved, without either rule trusting extractor-
|
||||
carried state it cannot re-derive from email_data["body"]."""
|
||||
|
||||
# --- V4 anchor integrity -> anchor_violation ---
|
||||
more_detail_idxs = _indices(lines, "More Detail")
|
||||
supplier_idxs = _indices(lines, "Supplier")
|
||||
shipping_idxs = _indices(lines, "Shipping")
|
||||
total_idxs = _indices(lines, "Total")
|
||||
if len(more_detail_idxs) != 1:
|
||||
return False, "anchor_violation"
|
||||
if len(supplier_idxs) != 2 or len(shipping_idxs) != 2 or len(total_idxs) != 2:
|
||||
return False, "anchor_violation"
|
||||
more_detail = more_detail_idxs[0]
|
||||
# The FIRST Shipping value must be the literal 'None' placeholder -- the
|
||||
# dup-label-swap tripwire (a real address under the first label means the
|
||||
# layout drifted; ship_to would have been read from the wrong block).
|
||||
first_ship_val = ""
|
||||
if shipping_idxs[0] + 1 < len(lines):
|
||||
first_ship_val = (
|
||||
lines[shipping_idxs[0] + 1].replace("\r", "").replace("\xa0", "").strip()
|
||||
)
|
||||
if first_ship_val != "None":
|
||||
return False, "anchor_violation"
|
||||
lines_anchor = _find_after(lines, "Lines", shipping_idxs[1] + 1)
|
||||
if lines_anchor is None:
|
||||
return False, "anchor_violation"
|
||||
# Section ordering: summary Supplier < More Detail < detail Supplier <
|
||||
# second Shipping < Lines < second Total; summary Total before More Detail.
|
||||
if not (
|
||||
lines: list
|
||||
more_detail: int
|
||||
supplier_idxs: list
|
||||
shipping_idxs: list
|
||||
total_idxs: list
|
||||
lines_anchor: int
|
||||
lines_end: int
|
||||
summary_matches: list
|
||||
price: object
|
||||
|
||||
|
||||
def _anchor_order_ok(
|
||||
more_detail, supplier_idxs, shipping_idxs, total_idxs, lines_anchor
|
||||
):
|
||||
"""Section ordering: summary Supplier < More Detail < detail Supplier <
|
||||
second Shipping < Lines < second Total; summary Total before More Detail."""
|
||||
return (
|
||||
supplier_idxs[0]
|
||||
< more_detail
|
||||
< supplier_idxs[1]
|
||||
< shipping_idxs[1]
|
||||
< lines_anchor
|
||||
< total_idxs[1]
|
||||
):
|
||||
return False, "anchor_violation"
|
||||
if not (total_idxs[0] < more_detail < shipping_idxs[0] < supplier_idxs[1]):
|
||||
return False, "anchor_violation"
|
||||
lines_end = total_idxs[1]
|
||||
) and (total_idxs[0] < more_detail < shipping_idxs[0] < supplier_idxs[1])
|
||||
|
||||
# --- V1 money fidelity -> amount_mismatch ---
|
||||
# Every captured money value must re-locate its raw source token in the
|
||||
# body: token fullmatches the grouped money shape, format(value, ',.2f')
|
||||
# byte-equals it, and the character before it is not a digit/comma.
|
||||
for_matches = []
|
||||
for j in range(lines_anchor + 1, lines_end):
|
||||
m = _LINE_DESC_AMT_RE.fullmatch(_clean(lines[j]) or "")
|
||||
if m:
|
||||
for_matches.append(m)
|
||||
if len(for_matches) != len(items):
|
||||
return False, "amount_mismatch"
|
||||
for item, m in zip(items, for_matches):
|
||||
amount = item.get("amount")
|
||||
if not isinstance(amount, Decimal):
|
||||
return False, "amount_mismatch"
|
||||
serialized = format(amount, ",.2f")
|
||||
if serialized != m.group("amt"):
|
||||
return False, "amount_mismatch"
|
||||
if not _money_border_ok(m.string, serialized):
|
||||
return False, "amount_mismatch"
|
||||
# Line-level currency pin (rule 8 companion): rule 8 already proved the
|
||||
# top-level currency is exactly 'USD', but that only covers the Total
|
||||
# block. Every line item's captured currency AND its re-derived body
|
||||
# token must byte-equal it too -- a single non-USD line item fails
|
||||
# closed even when the Total block reads USD (the non-USD path is
|
||||
# entirely unexercised at every level, not just the total).
|
||||
if item.get("currency") != candidate.get("currency"):
|
||||
return False, "non_usd"
|
||||
if m.group("cur") != candidate.get("currency"):
|
||||
return False, "non_usd"
|
||||
|
||||
def _first_shipping_value(lines, first_shipping_idx):
|
||||
"""Value line under the FIRST 'Shipping' (the dup-label-swap tripwire: a
|
||||
real address here means the layout drifted and ship_to was read from the
|
||||
wrong block; the genuine layout carries the literal 'None')."""
|
||||
if first_shipping_idx + 1 >= len(lines):
|
||||
return ""
|
||||
return lines[first_shipping_idx + 1].replace("\r", "").replace("\xa0", "").strip()
|
||||
|
||||
|
||||
def _build_anchor_frame(lines, items):
|
||||
"""V4 anchor integrity. Returns (frame, None) when the duplicate-label
|
||||
layout is proven, else (None, 'anchor_violation'). Also precomputes the
|
||||
Items-summary matches and the captured line price onto the frame."""
|
||||
more_detail_idxs = _indices(lines, "More Detail")
|
||||
supplier_idxs = _indices(lines, "Supplier")
|
||||
shipping_idxs = _indices(lines, "Shipping")
|
||||
total_idxs = _indices(lines, "Total")
|
||||
# The Coupa layout repeats each of Supplier/Shipping/Total exactly twice
|
||||
# (summary placeholder + detail block) -- 2 is a structural constant of the
|
||||
# template, not a tunable magic number.
|
||||
if (
|
||||
len(more_detail_idxs) != 1
|
||||
or len(supplier_idxs) != 2 # noqa: PLR2004
|
||||
or len(shipping_idxs) != 2 # noqa: PLR2004
|
||||
or len(total_idxs) != 2 # noqa: PLR2004
|
||||
):
|
||||
return None, "anchor_violation"
|
||||
more_detail = more_detail_idxs[0]
|
||||
lines_anchor = _find_after(lines, "Lines", shipping_idxs[1] + 1)
|
||||
# lines_anchor is proven non-None before _anchor_order_ok consumes it (the
|
||||
# `or` short-circuits); every index below is safe once the counts hold.
|
||||
if (
|
||||
lines_anchor is None
|
||||
or _first_shipping_value(lines, shipping_idxs[0]) != "None"
|
||||
or not _anchor_order_ok(
|
||||
more_detail, supplier_idxs, shipping_idxs, total_idxs, lines_anchor
|
||||
)
|
||||
):
|
||||
return None, "anchor_violation"
|
||||
summary_matches = [
|
||||
m
|
||||
for i in range(more_detail)
|
||||
if (m := _SUMMARY_ITEM_RE.fullmatch(_clean(lines[i]) or ""))
|
||||
]
|
||||
price = items[0].get("price") if items else None
|
||||
if price is not None:
|
||||
if not isinstance(price, Decimal) or len(summary_matches) != 1:
|
||||
return False, "amount_mismatch"
|
||||
serialized = format(price, ",.2f")
|
||||
if serialized != summary_matches[0].group("price"):
|
||||
return False, "amount_mismatch"
|
||||
if not _money_border_ok(summary_matches[0].string, serialized):
|
||||
return False, "amount_mismatch"
|
||||
total = candidate.get("total_amount")
|
||||
if not isinstance(total, Decimal):
|
||||
return False, "amount_mismatch"
|
||||
frame = _NewPoAnchorFrame(
|
||||
lines=lines,
|
||||
more_detail=more_detail,
|
||||
supplier_idxs=supplier_idxs,
|
||||
shipping_idxs=shipping_idxs,
|
||||
total_idxs=total_idxs,
|
||||
lines_anchor=lines_anchor,
|
||||
lines_end=total_idxs[1],
|
||||
summary_matches=summary_matches,
|
||||
price=items[0].get("price") if items else None,
|
||||
)
|
||||
return frame, None
|
||||
|
||||
# --- V3 dual-Total proof -> amount_mismatch (V2 needs its token, so it
|
||||
# derives here; sum proof follows immediately) ---
|
||||
|
||||
def _check_line_item_money(candidate, frame):
|
||||
"""V1 line-level money fidelity -> amount_mismatch / non_usd.
|
||||
|
||||
Every captured line amount must re-locate its raw source token in the body:
|
||||
the token fullmatches the grouped money shape, format(value, ',.2f') byte-
|
||||
equals it, and the character before it is not a digit/comma. Line-level
|
||||
currency is pinned too -- a single non-USD line item fails closed even when
|
||||
the Total block reads USD (the non-USD path is entirely unexercised)."""
|
||||
lines = frame.lines
|
||||
items = candidate.get("line_items") or []
|
||||
for_matches = []
|
||||
for j in range(frame.lines_anchor + 1, frame.lines_end):
|
||||
m = _LINE_DESC_AMT_RE.fullmatch(_clean(lines[j]) or "")
|
||||
if m:
|
||||
for_matches.append(m)
|
||||
if len(for_matches) != len(items):
|
||||
return "amount_mismatch"
|
||||
for item, m in zip(items, for_matches):
|
||||
amount = item.get("amount")
|
||||
if not isinstance(amount, Decimal):
|
||||
return "amount_mismatch"
|
||||
serialized = format(amount, ",.2f")
|
||||
if serialized != m.group("amt") or not _money_border_ok(m.string, serialized):
|
||||
return "amount_mismatch"
|
||||
currency = candidate.get("currency")
|
||||
if item.get("currency") != currency or m.group("cur") != currency:
|
||||
return "non_usd"
|
||||
return None
|
||||
|
||||
|
||||
def _check_summary_price(frame):
|
||||
"""V1 summary-price fidelity -> amount_mismatch. The captured Items-summary
|
||||
price must re-locate its raw token exactly as the line amounts do."""
|
||||
price = frame.price
|
||||
if price is None:
|
||||
return None
|
||||
if not isinstance(price, Decimal) or len(frame.summary_matches) != 1:
|
||||
return "amount_mismatch"
|
||||
serialized = format(price, ",.2f")
|
||||
if serialized != frame.summary_matches[0].group("price"):
|
||||
return "amount_mismatch"
|
||||
if not _money_border_ok(frame.summary_matches[0].string, serialized):
|
||||
return "amount_mismatch"
|
||||
return None
|
||||
|
||||
|
||||
def _check_money_fidelity(candidate, frame):
|
||||
"""V1 money fidelity: line-item amounts then the Items-summary price."""
|
||||
return _check_line_item_money(candidate, frame) or _check_summary_price(frame)
|
||||
|
||||
|
||||
def _read_total_tokens(lines, total_idxs):
|
||||
"""Read the (amount, currency) token pair under each 'Total' anchor.
|
||||
Returns (tokens, True) or (None, False) on any missing/malformed token."""
|
||||
total_tokens = []
|
||||
for t_idx in total_idxs:
|
||||
a_idx = _next_visible(lines, t_idx)
|
||||
if a_idx is None:
|
||||
return False, "amount_mismatch"
|
||||
return None, False
|
||||
token = _clean(lines[a_idx]) or ""
|
||||
if not _MONEY_RE.fullmatch(token):
|
||||
return False, "amount_mismatch"
|
||||
return None, False
|
||||
c_idx = _next_visible(lines, a_idx)
|
||||
cur_token = (_clean(lines[c_idx]) or "") if c_idx is not None else ""
|
||||
if not _CURRENCY_RE.fullmatch(cur_token):
|
||||
return False, "amount_mismatch"
|
||||
return None, False
|
||||
total_tokens.append((token, cur_token))
|
||||
if total_tokens[0] != total_tokens[1]:
|
||||
return False, "amount_mismatch"
|
||||
serialized = format(total, ",.2f")
|
||||
if serialized != total_tokens[1][0]:
|
||||
return False, "amount_mismatch"
|
||||
if candidate.get("currency") != total_tokens[1][1]:
|
||||
return False, "amount_mismatch"
|
||||
return total_tokens, True
|
||||
|
||||
# --- V2 sum proof -> amount_mismatch (exact Decimal equality; deliberately
|
||||
# NO qty*price==amount rule -- corpus shows partial quantities) ---
|
||||
if sum(item["amount"] for item in items) != total:
|
||||
return False, "amount_mismatch"
|
||||
|
||||
# --- V5 supplier proof -> anchor_violation ---
|
||||
def _check_total_proof(candidate, frame):
|
||||
"""V3 dual-Total proof + V2 sum proof -> amount_mismatch. Both Total blocks
|
||||
must carry byte-identical tokens that byte-equal the captured total, and the
|
||||
line amounts must sum to it exactly (no qty*price rule -- partial qtys)."""
|
||||
items = candidate.get("line_items") or []
|
||||
total = candidate.get("total_amount")
|
||||
if not isinstance(total, Decimal):
|
||||
return "amount_mismatch"
|
||||
total_tokens, ok = _read_total_tokens(frame.lines, frame.total_idxs)
|
||||
if (
|
||||
not ok
|
||||
or total_tokens[0] != total_tokens[1]
|
||||
or format(total, ",.2f") != total_tokens[1][0]
|
||||
or candidate.get("currency") != total_tokens[1][1]
|
||||
or sum(item["amount"] for item in items) != total
|
||||
):
|
||||
return "amount_mismatch"
|
||||
return None
|
||||
|
||||
|
||||
def _check_supplier_proof(candidate, frame):
|
||||
"""V5 supplier proof -> anchor_violation. The supplier name must carry the
|
||||
SEA HAVEN marker and byte-equal its restatements in both the summary and
|
||||
the detail block, and must not collide with the ship_to name."""
|
||||
lines = frame.lines
|
||||
ship_to = candidate.get("ship_to") or {}
|
||||
supplier_name = (candidate.get("supplier") or {}).get("name")
|
||||
if not supplier_name or _SUPPLIER_MARKER not in supplier_name:
|
||||
return False, "anchor_violation"
|
||||
det_idx = _next_visible(lines, supplier_idxs[1], shipping_idxs[1])
|
||||
return "anchor_violation"
|
||||
det_idx = _next_visible(lines, frame.supplier_idxs[1], frame.shipping_idxs[1])
|
||||
if det_idx is None or _clean(lines[det_idx]) != supplier_name:
|
||||
return False, "anchor_violation"
|
||||
sum_idx = _next_visible(lines, supplier_idxs[0], more_detail)
|
||||
return "anchor_violation"
|
||||
sum_idx = _next_visible(lines, frame.supplier_idxs[0], frame.more_detail)
|
||||
if sum_idx is None or _clean(lines[sum_idx]) != supplier_name:
|
||||
return False, "anchor_violation"
|
||||
return "anchor_violation"
|
||||
if ship_to.get("name") == supplier_name:
|
||||
return False, "anchor_violation"
|
||||
return "anchor_violation"
|
||||
return None
|
||||
|
||||
# --- V8 bullet discipline -> bullet_label_unrecognized (V5's per-item
|
||||
# Supplier-segment proof rides the same walk) ---
|
||||
|
||||
def _check_bullet_line(raw, supplier_name):
|
||||
"""One Lines-section bullet metadata line: closed label set, no dupes, the
|
||||
required labels present, and the per-item Supplier segment (V5) byte-equal
|
||||
to supplier_name."""
|
||||
seen = {}
|
||||
for segment in _split_bullet_segments(raw):
|
||||
label, value = _match_bullet_label(segment)
|
||||
if label is None or label in seen:
|
||||
return "bullet_label_unrecognized"
|
||||
seen[label] = value
|
||||
if set(seen) - {
|
||||
"Supplier",
|
||||
"Need By",
|
||||
"Category",
|
||||
"Account",
|
||||
"Period",
|
||||
"Part Number",
|
||||
}:
|
||||
return "bullet_label_unrecognized"
|
||||
if not {"Supplier", "Need By", "Category", "Account", "Period"} <= set(seen):
|
||||
return "bullet_label_unrecognized"
|
||||
if _clean(seen["Supplier"]) != supplier_name:
|
||||
return "anchor_violation"
|
||||
return None
|
||||
|
||||
|
||||
def _check_bullet_discipline(candidate, frame):
|
||||
"""V8 bullet discipline -> bullet_label_unrecognized (V5's per-item
|
||||
Supplier-segment proof rides the same walk)."""
|
||||
lines = frame.lines
|
||||
items = candidate.get("line_items") or []
|
||||
supplier_name = (candidate.get("supplier") or {}).get("name")
|
||||
bullet_lines = [
|
||||
lines[j] for j in range(lines_anchor + 1, lines_end) if _BULLET in lines[j]
|
||||
lines[j]
|
||||
for j in range(frame.lines_anchor + 1, frame.lines_end)
|
||||
if _BULLET in lines[j]
|
||||
]
|
||||
if len(bullet_lines) != len(items):
|
||||
return False, "bullet_label_unrecognized"
|
||||
return "bullet_label_unrecognized"
|
||||
for raw in bullet_lines:
|
||||
seen = {}
|
||||
for segment in _split_bullet_segments(raw):
|
||||
label, value = _match_bullet_label(segment)
|
||||
if label is None or label in seen:
|
||||
return False, "bullet_label_unrecognized"
|
||||
seen[label] = value
|
||||
if set(seen) - {
|
||||
"Supplier",
|
||||
"Need By",
|
||||
"Category",
|
||||
"Account",
|
||||
"Period",
|
||||
"Part Number",
|
||||
}:
|
||||
return False, "bullet_label_unrecognized"
|
||||
if not {"Supplier", "Need By", "Category", "Account", "Period"} <= set(seen):
|
||||
return False, "bullet_label_unrecognized"
|
||||
if _clean(seen["Supplier"]) != supplier_name:
|
||||
return False, "anchor_violation"
|
||||
reason = _check_bullet_line(raw, supplier_name)
|
||||
if reason:
|
||||
return reason
|
||||
return None
|
||||
|
||||
# --- V6 ship_to required -> missing_required_field ---
|
||||
|
||||
def _check_ship_to_required(candidate, frame):
|
||||
"""V6 ship_to required fields -> missing_required_field. Required fields
|
||||
present, numeric location_code that re-derives from the body, and attn (if
|
||||
present) matching a body Attn line."""
|
||||
lines = frame.lines
|
||||
ship_to = candidate.get("ship_to") or {}
|
||||
for field in ("name", "street", "city", "state", "zip", "location_code"):
|
||||
if not ship_to.get(field):
|
||||
return False, "missing_required_field"
|
||||
return "missing_required_field"
|
||||
if not re.fullmatch(r"\d+", ship_to["location_code"]):
|
||||
return False, "missing_required_field"
|
||||
return "missing_required_field"
|
||||
lc_values = [
|
||||
m.group("lc")
|
||||
for j in range(shipping_idxs[1] + 1, lines_anchor)
|
||||
for j in range(frame.shipping_idxs[1] + 1, frame.lines_anchor)
|
||||
if (m := _LOCATION_CODE_RE.fullmatch(_clean(lines[j]) or ""))
|
||||
]
|
||||
if ship_to["location_code"] not in lc_values:
|
||||
return False, "missing_required_field"
|
||||
return "missing_required_field"
|
||||
attn_values = [
|
||||
_clean(m.group("attn"))
|
||||
for j in range(shipping_idxs[1] + 1, lines_anchor)
|
||||
for j in range(frame.shipping_idxs[1] + 1, frame.lines_anchor)
|
||||
if (m := _ATTN_RE.fullmatch(_clean(lines[j]) or ""))
|
||||
]
|
||||
if attn_values:
|
||||
if ship_to.get("attn") not in attn_values:
|
||||
return False, "missing_required_field"
|
||||
return "missing_required_field"
|
||||
elif ship_to.get("attn") is not None:
|
||||
return False, "missing_required_field"
|
||||
return "missing_required_field"
|
||||
return None
|
||||
|
||||
# --- V7 address shape -> address_shape_invalid (gated on the RAW
|
||||
# pre-enrichment zip: validate() runs BEFORE enrich_parsed, so a short zip
|
||||
# like '2149' fails closed to the LLM path where pad_zip repairs it --
|
||||
# both paths then get identical pad_zip treatment downstream) ---
|
||||
us_idx = _find_after(lines, _US_SENTINEL, shipping_idxs[1] + 1)
|
||||
if us_idx is None or us_idx >= lines_anchor:
|
||||
return False, "address_shape_invalid"
|
||||
|
||||
def _check_address_shape(candidate, frame):
|
||||
"""V7 address shape -> address_shape_invalid. Gated on the RAW pre-
|
||||
enrichment zip: validate() runs BEFORE enrich_parsed, so a short zip fails
|
||||
closed to the LLM path where pad_zip repairs it (both paths then get
|
||||
identical pad_zip treatment downstream)."""
|
||||
lines = frame.lines
|
||||
ship_to = candidate.get("ship_to") or {}
|
||||
us_idx = _find_after(lines, _US_SENTINEL, frame.shipping_idxs[1] + 1)
|
||||
if us_idx is None or us_idx >= frame.lines_anchor:
|
||||
return "address_shape_invalid"
|
||||
m = _CITY_STATE_ZIP_RE.fullmatch(_clean(lines[us_idx - 1]) or "")
|
||||
if not m:
|
||||
return False, "address_shape_invalid"
|
||||
return "address_shape_invalid"
|
||||
if (
|
||||
m.group("city") != ship_to["city"]
|
||||
or m.group("state") != ship_to["state"]
|
||||
or m.group("zip") != ship_to["zip"]
|
||||
):
|
||||
return False, "address_shape_invalid"
|
||||
return "address_shape_invalid"
|
||||
if ship_to["state"] not in _USPS_STATES:
|
||||
return False, "address_shape_invalid"
|
||||
return "address_shape_invalid"
|
||||
if not re.fullmatch(r"\d{5}(-\d{4})?", ship_to["zip"]):
|
||||
return False, "address_shape_invalid"
|
||||
return "address_shape_invalid"
|
||||
return None
|
||||
|
||||
# --- V9 required labeled fields -> missing_required_field ---
|
||||
|
||||
def _check_required_fields(candidate, frame):
|
||||
"""V9 required labeled fields -> missing_required_field. Nullable by design:
|
||||
on_behalf_of, department, last_opened, acknowledged_at, revision_date, attn,
|
||||
quantity, unit, price."""
|
||||
lines = frame.lines
|
||||
items = candidate.get("line_items") or []
|
||||
for field in (
|
||||
"po_status",
|
||||
"order_date",
|
||||
|
|
@ -910,7 +1067,7 @@ def _validate_new_po_values(candidate, email_data): # noqa: PLR0911, PLR0912, P
|
|||
"view_order_url",
|
||||
):
|
||||
if candidate.get(field) is None:
|
||||
return False, "missing_required_field"
|
||||
return "missing_required_field"
|
||||
for item in items:
|
||||
for field in (
|
||||
"description",
|
||||
|
|
@ -922,66 +1079,138 @@ def _validate_new_po_values(candidate, email_data): # noqa: PLR0911, PLR0912, P
|
|||
"period",
|
||||
):
|
||||
if item.get(field) is None:
|
||||
return False, "missing_required_field"
|
||||
return "missing_required_field"
|
||||
for label in _MORE_DETAIL_LABELS:
|
||||
if len(_indices(lines, label)) != 1:
|
||||
return False, "missing_required_field"
|
||||
return "missing_required_field"
|
||||
if candidate.get("coupa_category") != items[0].get("category"):
|
||||
return False, "missing_required_field"
|
||||
# Nullable by design: on_behalf_of, department, last_opened, acknowledged_at,
|
||||
# revision_date, attn, quantity, unit, price.
|
||||
return "missing_required_field"
|
||||
return None
|
||||
|
||||
# --- V10 PO identity proofs -> po_id_mismatch ---
|
||||
|
||||
def _check_po_identity(candidate, frame):
|
||||
"""V10 PO identity proofs -> po_id_mismatch. The PO id must restate under
|
||||
'PO ID', in an 'Amazon Purchase Order #<po>' line, and as the numeric tail
|
||||
of the view_order_url."""
|
||||
lines = frame.lines
|
||||
po = candidate["po_number"]
|
||||
po_id_idx = _indices(lines, "PO ID")[0]
|
||||
v_idx = _next_visible(lines, po_id_idx)
|
||||
if v_idx is None or _clean(lines[v_idx]) != po:
|
||||
return False, "po_id_mismatch"
|
||||
return "po_id_mismatch"
|
||||
if not _indices(lines, f"Amazon Purchase Order #{po}"):
|
||||
return False, "po_id_mismatch"
|
||||
return "po_id_mismatch"
|
||||
um = _ORDER_URL_ID_RE.match(candidate.get("view_order_url") or "")
|
||||
if not um or um.group(1) != po.split("-", 1)[1]:
|
||||
return False, "po_id_mismatch"
|
||||
return "po_id_mismatch"
|
||||
return None
|
||||
|
||||
# --- V11 sentinel discipline -> unparseable_value ---
|
||||
|
||||
def _check_sentinels(candidate, frame):
|
||||
"""V11 sentinel discipline -> unparseable_value. A present-but-unparseable
|
||||
value (the _UNPARSEABLE sentinel) must fail closed."""
|
||||
for leaf in _walk_leaves(candidate):
|
||||
if isinstance(leaf, str) and leaf == _UNPARSEABLE:
|
||||
return False, "unparseable_value"
|
||||
return "unparseable_value"
|
||||
return None
|
||||
|
||||
# --- V12 hygiene -> residual_artifact ---
|
||||
|
||||
def _check_hygiene(candidate, frame):
|
||||
"""V12 hygiene -> residual_artifact. No captured value may retain a raw CR
|
||||
or nbsp artifact."""
|
||||
for leaf in _walk_leaves(candidate):
|
||||
if isinstance(leaf, str) and ("\r" in leaf or "\xa0" in leaf):
|
||||
return False, "residual_artifact"
|
||||
return "residual_artifact"
|
||||
return None
|
||||
|
||||
# --- V13 quantity/unit/price coherence -> amount_mismatch ---
|
||||
|
||||
def _check_qty_unit_shape(quantity, unit, price):
|
||||
"""V13 scalar shape: a positive Decimal quantity, an all-caps unit, and a
|
||||
Decimal price."""
|
||||
if (
|
||||
not isinstance(quantity, Decimal)
|
||||
or quantity <= 0
|
||||
or not unit
|
||||
or not re.fullmatch(r"[A-Z]+", unit)
|
||||
or not isinstance(price, Decimal)
|
||||
):
|
||||
return "amount_mismatch"
|
||||
return None
|
||||
|
||||
|
||||
def _check_ea_line_evidence(lines, frame, quantity):
|
||||
"""The Lines-block '<qty> EA' evidence line (when present) must numeric-
|
||||
equal the summary quantity."""
|
||||
ea_matches = [
|
||||
m
|
||||
for j in range(frame.lines_anchor + 1, frame.lines_end)
|
||||
if (m := _LINE_QTY_RE.fullmatch(_clean(lines[j]) or ""))
|
||||
]
|
||||
if not ea_matches:
|
||||
return None
|
||||
if len(ea_matches) != 1:
|
||||
return "amount_mismatch"
|
||||
if _to_decimal(ea_matches[0].group("qty")) != quantity:
|
||||
return "amount_mismatch"
|
||||
return None
|
||||
|
||||
|
||||
def _check_qty_unit_price(candidate, frame):
|
||||
"""V13 quantity/unit/price coherence -> amount_mismatch. Skipped entirely
|
||||
when all three are absent; otherwise every piece must cohere with the
|
||||
Items-summary line and the Lines-block EA evidence."""
|
||||
items = candidate.get("line_items") or []
|
||||
quantity = items[0].get("quantity")
|
||||
unit = items[0].get("unit")
|
||||
if quantity is not None or unit is not None or price is not None:
|
||||
if not isinstance(quantity, Decimal) or quantity <= 0:
|
||||
return False, "amount_mismatch"
|
||||
if not unit or not re.fullmatch(r"[A-Z]+", unit):
|
||||
return False, "amount_mismatch"
|
||||
if not isinstance(price, Decimal):
|
||||
return False, "amount_mismatch"
|
||||
if len(summary_matches) != 1:
|
||||
return False, "amount_mismatch"
|
||||
if _to_decimal(summary_matches[0].group("qty")) != quantity:
|
||||
return False, "amount_mismatch"
|
||||
if summary_matches[0].group("unit") != unit:
|
||||
return False, "amount_mismatch"
|
||||
# The Lines-block '<qty> EA' evidence line must numeric-equal the
|
||||
# summary quantity when present.
|
||||
ea_matches = [
|
||||
m
|
||||
for j in range(lines_anchor + 1, lines_end)
|
||||
if (m := _LINE_QTY_RE.fullmatch(_clean(lines[j]) or ""))
|
||||
]
|
||||
if ea_matches:
|
||||
if len(ea_matches) != 1:
|
||||
return False, "amount_mismatch"
|
||||
if _to_decimal(ea_matches[0].group("qty")) != quantity:
|
||||
return False, "amount_mismatch"
|
||||
price = frame.price
|
||||
if quantity is None and unit is None and price is None:
|
||||
return None
|
||||
reason = _check_qty_unit_shape(quantity, unit, price)
|
||||
if reason:
|
||||
return reason
|
||||
if (
|
||||
len(frame.summary_matches) != 1
|
||||
or _to_decimal(frame.summary_matches[0].group("qty")) != quantity
|
||||
or frame.summary_matches[0].group("unit") != unit
|
||||
):
|
||||
return "amount_mismatch"
|
||||
return _check_ea_line_evidence(frame.lines, frame, quantity)
|
||||
|
||||
|
||||
# Value-level rules in spec order, each returning a reason code or None. V4
|
||||
# builds the shared anchor frame first (below); these consume it.
|
||||
_NEW_PO_VALUE_CHECKS = (
|
||||
_check_money_fidelity, # V1
|
||||
_check_total_proof, # V3 + V2
|
||||
_check_supplier_proof, # V5
|
||||
_check_bullet_discipline, # V8
|
||||
_check_ship_to_required, # V6
|
||||
_check_address_shape, # V7
|
||||
_check_required_fields, # V9
|
||||
_check_po_identity, # V10
|
||||
_check_sentinels, # V11
|
||||
_check_hygiene, # V12
|
||||
_check_qty_unit_price, # V13
|
||||
)
|
||||
|
||||
|
||||
def _validate_new_po_values(candidate, email_data):
|
||||
"""Value-level gate rules V1-V13 for coupa_new_po. FAIL CLOSED.
|
||||
|
||||
V4 anchor integrity builds the shared anchor frame first (every later byte
|
||||
proof needs it); the remaining rules then run in spec order via the per-rule
|
||||
_check_* helpers, each re-deriving its evidence from email_data["body"] so
|
||||
an extractor bug cannot vouch for itself. The first helper to return a
|
||||
reason code short-circuits to (False, reason)."""
|
||||
lines = _plain_lines(email_data["body"])
|
||||
items = candidate.get("line_items") or []
|
||||
frame, reason = _build_anchor_frame(lines, items)
|
||||
if reason:
|
||||
return False, reason
|
||||
for check in _NEW_PO_VALUE_CHECKS:
|
||||
reason = check(candidate, frame)
|
||||
if reason:
|
||||
return False, reason
|
||||
return True, "ok"
|
||||
|
||||
|
||||
|
|
@ -1105,7 +1334,7 @@ def _normalize_nested_dict(value, keys):
|
|||
return {k: value.get(k) for k in keys}, True
|
||||
|
||||
|
||||
def validate_ai_fallback(candidate): # noqa: PLR0911, PLR0912
|
||||
def validate_ai_fallback(candidate): # noqa: C901, PLR0911, PLR0912
|
||||
"""Fail-closed schema/type validation for the AI-fallback parse path.
|
||||
|
||||
Returns (ok, reason, normalized_candidate_or_None). On success the handler
|
||||
|
|
|
|||
|
|
@ -1,194 +1,83 @@
|
|||
"""Offline test helpers for the purchase-order email processor.
|
||||
|
||||
Uniquely named (not ``conftest``) so ``from _po_parser_support import ...``
|
||||
never collides with the repo's top-level ``tests/conftest.py`` when multiple
|
||||
test roots are collected in one pytest run.
|
||||
never collides with the repo's top-level ``tests/`` suite when multiple test
|
||||
roots are collected in one pytest run.
|
||||
|
||||
MODULE-COLLISION GUARD: the WO suite (lambdas/wo/email_processor/tests) puts
|
||||
its own module dir on ``sys.path`` and bare-imports ``handler`` /
|
||||
``template_parser``, which ``sys.modules`` then caches session-wide. This
|
||||
module therefore NEVER bare-imports the PO modules: it loads them by file path
|
||||
via importlib under unique module names, and binds the PO handler's own bare
|
||||
sibling imports (``from template_parser import ...`` / ``from ses_auth import
|
||||
...``) to the PO modules only for the duration of the handler exec, restoring
|
||||
any previous binding afterwards. The unique names match the ones
|
||||
``tests/conftest.py`` uses, so whichever loader runs first, the whole session
|
||||
shares a single PO module instance per file.
|
||||
Phase 8: this is now a THIN SHIM over ``tests.support``. The single Lambda-module
|
||||
loader (and its one copy of the sys.modules save/restore dance) lives in
|
||||
``tests/support/loader.py``; the dummy-AWS-env + moto-before-handler ordering
|
||||
lives in the repo-root ``conftest.py``. This module just eager-loads the PO
|
||||
handler + its sibling handles and re-exports the shared fakes / fixture helpers
|
||||
bound to ``pipeline="po"`` so no PO test file needs an import change.
|
||||
"""
|
||||
|
||||
import glob
|
||||
import importlib.util
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
from decimal import Decimal
|
||||
|
||||
# Imported for its side effect and DELIBERATELY BEFORE the handler modules are
|
||||
# loaded below: moto registers its botocore stubber hook into botocore's
|
||||
# BUILTIN_HANDLERS at import time, and boto3 sessions only pick the hook up if
|
||||
# they are created AFTER that registration. This conftest chain is imported at
|
||||
# pytest session start -- before tests/test_po_merge.py gets a chance to import
|
||||
# moto -- so without this import the handler's module-level boto3 clients would
|
||||
# be created un-stubbable and the moto-backed suites would hit real AWS.
|
||||
import moto # noqa: F401
|
||||
from tests.support import (
|
||||
FIXTURE_DIRS,
|
||||
FakeDynamoResource,
|
||||
FakeTable,
|
||||
load_lambda_module,
|
||||
)
|
||||
from tests.support import load_email as _load_email
|
||||
from tests.support import load_golden as _load_golden
|
||||
from tests.support import load_raw as _load_raw
|
||||
from tests.support import stems as _stems
|
||||
|
||||
_HERE = os.path.dirname(__file__)
|
||||
_MODULE_DIR = os.path.abspath(os.path.join(_HERE, ".."))
|
||||
# Phase 3 single-sourced ses_auth/email_parsing/emf under lambdas/shared/.
|
||||
# _HERE = lambdas/po/email_processor/tests -> ../../.. = lambdas.
|
||||
_SHARED_DIR = os.path.abspath(os.path.join(_HERE, "..", "..", "..", "shared"))
|
||||
|
||||
# The handler creates boto3 clients at import time; give it a region and dummy
|
||||
# creds so import works offline/under CI.
|
||||
os.environ.setdefault("AWS_DEFAULT_REGION", "us-east-1")
|
||||
os.environ.setdefault("AWS_ACCESS_KEY_ID", "testing")
|
||||
os.environ.setdefault("AWS_SECRET_ACCESS_KEY", "testing")
|
||||
os.environ.setdefault("AWS_SESSION_TOKEN", "testing")
|
||||
|
||||
FIXTURES = os.path.join(_HERE, "fixtures")
|
||||
__all__ = [
|
||||
"FakeDynamoResource",
|
||||
"FakeTable",
|
||||
"load_lambda_module",
|
||||
"po_handler",
|
||||
"template_parser",
|
||||
"po_prompts",
|
||||
"po_telemetry",
|
||||
"po_extraction",
|
||||
"po_enrichment",
|
||||
"po_persistence",
|
||||
"FIXTURES",
|
||||
"NEW_PO_STEMS",
|
||||
"CANCELLATION_STEMS",
|
||||
"AI_FALLBACK_STEMS",
|
||||
"ADVERSARIAL_STEMS",
|
||||
"load_raw",
|
||||
"load_email",
|
||||
"load_golden",
|
||||
]
|
||||
|
||||
_HANDLER_NAME = "po_email_processor_handler"
|
||||
|
||||
|
||||
def _load_module(filename, module_name):
|
||||
if module_name in sys.modules:
|
||||
return sys.modules[module_name]
|
||||
spec = importlib.util.spec_from_file_location(
|
||||
module_name, os.path.join(_MODULE_DIR, filename)
|
||||
)
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
sys.modules[module_name] = module
|
||||
spec.loader.exec_module(module)
|
||||
return module
|
||||
|
||||
|
||||
def _load_shared_module(filename, module_name):
|
||||
"""Load a Phase 3 shared sibling (ses_auth/email_parsing/emf) from
|
||||
lambdas/shared/. Mirrors ``_load_module`` but resolves against
|
||||
``_SHARED_DIR`` -- the handler ``from email_parsing import ...`` /
|
||||
``from emf import ...`` / ``from ses_auth import ...`` bare imports must be
|
||||
pre-bound in sys.modules because this support module does NOT put shared/
|
||||
on sys.path."""
|
||||
if module_name in sys.modules:
|
||||
return sys.modules[module_name]
|
||||
spec = importlib.util.spec_from_file_location(
|
||||
module_name, os.path.join(_SHARED_DIR, filename)
|
||||
)
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
sys.modules[module_name] = module
|
||||
spec.loader.exec_module(module)
|
||||
return module
|
||||
|
||||
|
||||
def load_template_parser():
|
||||
return _load_module("template_parser.py", f"{_HANDLER_NAME}__template_parser")
|
||||
|
||||
|
||||
# Phase 5 split handler.py into flat siblings. This ordered table binds each
|
||||
# sibling's BARE name in sys.modules right after loading it and BEFORE the next
|
||||
# sibling execs, so a sibling whose body does `from <x> import ...` finds <x>
|
||||
# already bound. The order is dependency-topological: emf < telemetry, prompts <
|
||||
# extraction, derived_fields + telemetry < enrichment. The per-pipeline siblings
|
||||
# load from _MODULE_DIR (_load_module); the Phase 3 single-sourced ones
|
||||
# (ses_auth/email_parsing/emf) load from lambdas/shared/ (_load_shared_module).
|
||||
# The WHOLE load (siblings + handler) is wrapped in ONE save/restore so the bare
|
||||
# bindings never leak past the handler exec.
|
||||
_PO_SIBLINGS = (
|
||||
("prompts", _load_module, "prompts.py"),
|
||||
("emf", _load_shared_module, "emf.py"),
|
||||
("telemetry", _load_module, "telemetry.py"),
|
||||
("derived_fields", _load_module, "derived_fields.py"),
|
||||
("email_parsing", _load_shared_module, "email_parsing.py"),
|
||||
("template_parser", _load_module, "template_parser.py"),
|
||||
("ses_auth", _load_shared_module, "ses_auth.py"),
|
||||
("extraction", _load_module, "extraction.py"),
|
||||
("enrichment", _load_module, "enrichment.py"),
|
||||
("persistence", _load_module, "persistence.py"),
|
||||
)
|
||||
|
||||
|
||||
def load_po_handler():
|
||||
if _HANDLER_NAME in sys.modules:
|
||||
return sys.modules[_HANDLER_NAME]
|
||||
saved = {}
|
||||
try:
|
||||
for name, loader, filename in _PO_SIBLINGS:
|
||||
module = loader(filename, f"{_HANDLER_NAME}__{name}")
|
||||
if name not in saved:
|
||||
saved[name] = sys.modules.get(name)
|
||||
sys.modules[name] = module
|
||||
module = _load_module("handler.py", _HANDLER_NAME)
|
||||
finally:
|
||||
for name, previous in saved.items():
|
||||
if previous is not None:
|
||||
sys.modules[name] = previous
|
||||
else:
|
||||
sys.modules.pop(name, None)
|
||||
return module
|
||||
|
||||
|
||||
template_parser = load_template_parser()
|
||||
po_handler = load_po_handler()
|
||||
|
||||
# Phase 5: expose each flat sibling by its unique module name so tests can patch
|
||||
# accessors / read constants on the OWNING module (a re-exported name patched on
|
||||
# po_handler only affects calls handler itself makes; a function running in the
|
||||
# sibling's namespace reads its own binding -- see spec re-export rule).
|
||||
# Eager-load the PO handler (and, via the loader's save/restore dance, all its
|
||||
# flat siblings under unique ``<handler>__<sibling>`` names). The loader keys
|
||||
# are unchanged by design, so the sibling handles below are byte-identical to
|
||||
# the pre-Phase-8 module names.
|
||||
po_handler = load_lambda_module("po", "email_processor/handler")
|
||||
template_parser = sys.modules[f"{_HANDLER_NAME}__template_parser"]
|
||||
po_prompts = sys.modules[f"{_HANDLER_NAME}__prompts"]
|
||||
po_telemetry = sys.modules[f"{_HANDLER_NAME}__telemetry"]
|
||||
po_extraction = sys.modules[f"{_HANDLER_NAME}__extraction"]
|
||||
po_enrichment = sys.modules[f"{_HANDLER_NAME}__enrichment"]
|
||||
po_persistence = sys.modules[f"{_HANDLER_NAME}__persistence"]
|
||||
|
||||
FIXTURES = str(FIXTURE_DIRS["po"])
|
||||
|
||||
def _stems(subdir):
|
||||
return sorted(
|
||||
os.path.splitext(os.path.basename(p))[0]
|
||||
for p in glob.glob(os.path.join(FIXTURES, subdir, "*.eml"))
|
||||
)
|
||||
|
||||
|
||||
NEW_PO_STEMS = _stems("new-po")
|
||||
CANCELLATION_STEMS = _stems("cancellation")
|
||||
AI_FALLBACK_STEMS = _stems("ai-fallback")
|
||||
ADVERSARIAL_STEMS = _stems("adversarial")
|
||||
NEW_PO_STEMS = _stems("po", "new-po")
|
||||
CANCELLATION_STEMS = _stems("po", "cancellation")
|
||||
AI_FALLBACK_STEMS = _stems("po", "ai-fallback")
|
||||
ADVERSARIAL_STEMS = _stems("po", "adversarial")
|
||||
|
||||
|
||||
def load_raw(subdir, stem):
|
||||
with open(os.path.join(FIXTURES, subdir, f"{stem}.eml"), "rb") as fh:
|
||||
return fh.read()
|
||||
return _load_raw("po", subdir, stem)
|
||||
|
||||
|
||||
def load_email(subdir, stem):
|
||||
"""Parse a fixture .eml into the email_data dict the parser consumes."""
|
||||
return po_handler.parse_raw_email(load_raw(subdir, stem))
|
||||
return _load_email("po", subdir, stem)
|
||||
|
||||
|
||||
def load_golden(stem):
|
||||
"""Load the expected parser output for a positive fixture.
|
||||
|
||||
Goldens store money as JSON numbers; ``parse_float=Decimal`` mirrors the
|
||||
handler's Bedrock decode and makes every golden money value compare
|
||||
exactly equal to the parser's Decimal output (2-dp values at PO magnitudes
|
||||
round-trip float repr losslessly)."""
|
||||
with open(os.path.join(FIXTURES, "expected", f"{stem}.json")) as fh:
|
||||
return json.load(fh, parse_float=Decimal)
|
||||
|
||||
|
||||
class FakeTable:
|
||||
"""Records update_item calls for assertions."""
|
||||
|
||||
def __init__(self, name):
|
||||
self.name = name
|
||||
self.updates = []
|
||||
|
||||
def update_item(self, **kwargs):
|
||||
self.updates.append(kwargs)
|
||||
|
||||
|
||||
class FakeDynamoResource:
|
||||
def __init__(self):
|
||||
self.tables = {}
|
||||
|
||||
def Table(self, name): # noqa: N802 (boto3 method name)
|
||||
return self.tables.setdefault(name, FakeTable(name))
|
||||
"""Load the expected parser output for a positive fixture (money as
|
||||
Decimal via ``parse_float=Decimal``; see tests.support.load_golden)."""
|
||||
return _load_golden("po", stem)
|
||||
|
|
|
|||
|
|
@ -635,12 +635,10 @@ def test_fixture_hygiene_ses_auth_and_scrub_markers():
|
|||
from _po_parser_support import (
|
||||
ADVERSARIAL_STEMS,
|
||||
AI_FALLBACK_STEMS,
|
||||
_load_shared_module,
|
||||
load_lambda_module,
|
||||
)
|
||||
|
||||
ses_auth = _load_shared_module(
|
||||
"ses_auth.py", "po_email_processor_handler__ses_auth"
|
||||
)
|
||||
ses_auth = load_lambda_module("shared", "ses_auth")
|
||||
coupa = (
|
||||
[("new-po", s) for s in NEW_PO_STEMS]
|
||||
+ [("cancellation", s) for s in CANCELLATION_STEMS]
|
||||
|
|
|
|||
149
lambdas/po/email_processor/tests/test_po_bedrock_transport.py
Normal file
149
lambdas/po/email_processor/tests/test_po_bedrock_transport.py
Normal file
|
|
@ -0,0 +1,149 @@
|
|||
"""PO Bedrock transport-error scenarios (constraint 5a) + multi-record
|
||||
failure-isolation pin (constraint 5e).
|
||||
|
||||
Every Bedrock transport failure -- a throttle, a malformed response envelope, or
|
||||
non-JSON model text -- must (1) leave the PRE-CALL ParseMethod=ai_fallback
|
||||
datapoint already emitted (PO emits the metric BEFORE the Bedrock call so a
|
||||
Bedrock-side error still records the attempted fallback), (2) write NOTHING (no
|
||||
partial DynamoDB write), and (3) propagate the exception out of handler() into
|
||||
the async-retry / DLQ path.
|
||||
|
||||
All wiring goes through the shared loader + support package (no bare imports).
|
||||
"""
|
||||
|
||||
import json
|
||||
|
||||
import pytest
|
||||
|
||||
from tests.support import FakeS3
|
||||
from _po_parser_support import (
|
||||
load_raw,
|
||||
po_extraction,
|
||||
po_handler,
|
||||
po_persistence,
|
||||
)
|
||||
|
||||
|
||||
class _FakeBody:
|
||||
def __init__(self, data):
|
||||
self._data = data
|
||||
|
||||
def read(self):
|
||||
return self._data
|
||||
|
||||
|
||||
class _ThrottlingBedrock:
|
||||
"""invoke_model raises a botocore ThrottlingException ClientError."""
|
||||
|
||||
def invoke_model(self, modelId, body): # noqa: N803 (boto3 kwarg name)
|
||||
from botocore.exceptions import ClientError
|
||||
|
||||
raise ClientError(
|
||||
{"Error": {"Code": "ThrottlingException", "Message": "rate exceeded"}},
|
||||
"InvokeModel",
|
||||
)
|
||||
|
||||
|
||||
class _MalformedResponseBedrock:
|
||||
"""invoke_model returns a structurally-broken response body."""
|
||||
|
||||
def __init__(self, payload_bytes):
|
||||
self._payload = payload_bytes
|
||||
|
||||
def invoke_model(self, modelId, body): # noqa: N803
|
||||
return {"body": _FakeBody(self._payload)}
|
||||
|
||||
|
||||
def _event(*keys):
|
||||
return {
|
||||
"Records": [
|
||||
{
|
||||
"s3": {
|
||||
"bucket": {"name": "po-ingest-emails-x"},
|
||||
"object": {"key": key},
|
||||
}
|
||||
}
|
||||
for key in keys
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def metric_spy(monkeypatch):
|
||||
calls = []
|
||||
monkeypatch.setattr(
|
||||
po_handler, "_emit_parse_method_metric", lambda *a: calls.append(a)
|
||||
)
|
||||
return calls
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def _bypass_auth(monkeypatch):
|
||||
# This suite exercises the transport-error seam, not the SES sender-auth gate
|
||||
# (covered by tests/test_ses_auth.py + tests/test_handler_auth_seam.py).
|
||||
monkeypatch.setattr(po_handler, "authenticate_inbound_email", lambda *a: True)
|
||||
|
||||
|
||||
# The four transport-failure modes, each a bedrock double whose invoke_model
|
||||
# fails a different way. All must surface as an exception out of extract_with_claude.
|
||||
_TRANSPORT_CASES = {
|
||||
"throttling_client_error": _ThrottlingBedrock(),
|
||||
"missing_content_key": _MalformedResponseBedrock(json.dumps({}).encode()),
|
||||
"empty_content_list": _MalformedResponseBedrock(
|
||||
json.dumps({"content": []}).encode()
|
||||
),
|
||||
"non_json_model_text": _MalformedResponseBedrock(
|
||||
json.dumps({"content": [{"text": "not json {{{ definitely not"}]}).encode()
|
||||
),
|
||||
}
|
||||
|
||||
|
||||
@pytest.mark.parametrize("case", sorted(_TRANSPORT_CASES))
|
||||
def test_bedrock_transport_error_pins_pre_call_metric_no_write_and_reraises(
|
||||
case, fake_dynamo, metric_spy, monkeypatch, _bypass_auth
|
||||
):
|
||||
monkeypatch.setattr(
|
||||
po_handler, "s3", FakeS3({"inbound/o1": load_raw("ai-fallback", "comment-01")})
|
||||
)
|
||||
monkeypatch.setattr(po_extraction, "bedrock", _TRANSPORT_CASES[case])
|
||||
|
||||
with pytest.raises(Exception): # noqa: B017,PT011 (contract: it must propagate)
|
||||
po_handler.handler(_event("inbound/o1"), None)
|
||||
|
||||
# (1) the PRE-CALL ai_fallback datapoint was emitted BEFORE the raise -- the
|
||||
# only real proof of PO's metric-before-call ordering (handler.py:91-96).
|
||||
assert metric_spy, "expected a pre-call ParseMethod metric before the raise"
|
||||
assert metric_spy[0][0] == "ai_fallback"
|
||||
# No ai_fallback_rejected: the failure was transport, not the gate.
|
||||
assert [c[0] for c in metric_spy] == ["ai_fallback"]
|
||||
|
||||
# (2) no partial write landed.
|
||||
po_table = fake_dynamo.tables.get(po_persistence.PO_TABLE)
|
||||
assert po_table is None or po_table.updates == []
|
||||
|
||||
|
||||
def test_multi_record_failure_isolation_is_all_or_retry(
|
||||
fake_dynamo, metric_spy, monkeypatch, _bypass_auth
|
||||
):
|
||||
"""Constraint 5e: there is NO per-record try/except -- a second record whose
|
||||
Bedrock call dies raises out of the WHOLE invocation (async retry replays the
|
||||
entire batch). This documents the all-or-retry contract: the first record's
|
||||
write DID land before the second record blew up."""
|
||||
monkeypatch.setattr(
|
||||
po_handler,
|
||||
"s3",
|
||||
FakeS3(
|
||||
{
|
||||
"inbound/ok": load_raw("new-po", "new-po-01"), # template -> writes
|
||||
"inbound/boom": load_raw("ai-fallback", "comment-01"), # -> bedrock
|
||||
}
|
||||
),
|
||||
)
|
||||
monkeypatch.setattr(po_extraction, "bedrock", _ThrottlingBedrock())
|
||||
|
||||
with pytest.raises(Exception): # noqa: B017,PT011
|
||||
po_handler.handler(_event("inbound/ok", "inbound/boom"), None)
|
||||
|
||||
# First record's purchase-order upsert landed before the second record raised.
|
||||
po_table = fake_dynamo.tables[po_persistence.PO_TABLE]
|
||||
assert len(po_table.updates) == 1
|
||||
|
|
@ -12,11 +12,15 @@ smoke.
|
|||
|
||||
import json
|
||||
|
||||
from tests.support import FakeS3
|
||||
from _po_parser_support import (
|
||||
NEW_PO_STEMS,
|
||||
load_email,
|
||||
load_raw,
|
||||
po_enrichment,
|
||||
po_extraction,
|
||||
po_handler,
|
||||
po_persistence,
|
||||
po_telemetry,
|
||||
template_parser,
|
||||
)
|
||||
|
|
@ -250,3 +254,61 @@ def test_pin_shadow_agreement_emf_is_ai_fallback_only(monkeypatch, capsys):
|
|||
recs = _emf_lines(capsys)
|
||||
assert set(recs) == {"site_code"}
|
||||
assert recs["site_code"]["Agreement"] == "disagree"
|
||||
|
||||
|
||||
# --- PO-DC-02: 64-char clamp on the ai_fallback_rejected po_number ride-along -
|
||||
|
||||
|
||||
class _FakeBody:
|
||||
def __init__(self, data):
|
||||
self._data = data
|
||||
|
||||
def read(self):
|
||||
return self._data
|
||||
|
||||
|
||||
class _JsonBedrock:
|
||||
def __init__(self, payload):
|
||||
self._payload = payload
|
||||
|
||||
def invoke_model(self, modelId, body): # noqa: N803 (boto3 kwarg name)
|
||||
text = json.dumps(self._payload)
|
||||
return {"body": _FakeBody(json.dumps({"content": [{"text": text}]}).encode())}
|
||||
|
||||
|
||||
def test_ai_fallback_rejected_po_number_is_clamped_to_64_chars(
|
||||
fake_dynamo, monkeypatch
|
||||
):
|
||||
"""PO-DC-02 regression pin (handler.py:118): when the AI-fallback gate rejects
|
||||
a model output whose po_number is longer than 64 chars, the po_number that
|
||||
rides along on the ai_fallback_rejected EMF datapoint is clamped to exactly
|
||||
64 chars (an unbounded hallucinated value must not land in a 2-month log
|
||||
line)."""
|
||||
calls = []
|
||||
monkeypatch.setattr(
|
||||
po_handler, "_emit_parse_method_metric", lambda *a: calls.append(a)
|
||||
)
|
||||
monkeypatch.setattr(po_handler, "authenticate_inbound_email", lambda *a: True)
|
||||
monkeypatch.setattr(
|
||||
po_handler, "s3", FakeS3({"inbound/o1": load_raw("ai-fallback", "comment-01")})
|
||||
)
|
||||
# A dict with an over-long po_number that fails the nested-contract gate.
|
||||
monkeypatch.setattr(
|
||||
po_extraction, "bedrock", _JsonBedrock({"po_number": "P" * 100})
|
||||
)
|
||||
|
||||
event = {
|
||||
"Records": [
|
||||
{"s3": {"bucket": {"name": "po-x"}, "object": {"key": "inbound/o1"}}}
|
||||
]
|
||||
}
|
||||
po_handler.handler(event, None)
|
||||
|
||||
rejected = [c for c in calls if c[0] == "ai_fallback_rejected"]
|
||||
assert len(rejected) == 1
|
||||
po_number_ride_along = rejected[0][3]
|
||||
assert po_number_ride_along == "P" * 64
|
||||
assert len(po_number_ride_along) == 64
|
||||
# Nothing was written (the gate rejected before any save).
|
||||
po_table = fake_dynamo.tables.get(po_persistence.PO_TABLE)
|
||||
assert po_table is None or po_table.updates == []
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
boto3==1.43.31
|
||||
boto3==1.43.51
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
boto3==1.43.31
|
||||
boto3==1.43.51
|
||||
|
|
|
|||
|
|
@ -79,8 +79,22 @@ def handler(event, context):
|
|||
# on a miss or an invalid (fail-closed) result.
|
||||
parsed, method, template_id, reason = try_deterministic_parse(email_data)
|
||||
if parsed is None:
|
||||
parsed = extract_with_bedrock(email_data)
|
||||
method = "ai_fallback"
|
||||
# A Bedrock transport error (throttle, malformed response, etc.)
|
||||
# previously emitted ZERO ParseOutcome datapoints -- the only emit
|
||||
# sites are the post-gate success (below) and the ai_fallback_rejected
|
||||
# branch. Wrap the call so a fallback attempt that dies in Bedrock
|
||||
# records exactly one datapoint (ai_fallback / ReasonCode=bedrock_error)
|
||||
# and then re-raises into the async-retry / DLQ path. The emit is in
|
||||
# the except -- never pre-call -- so a gate-rejected email (Bedrock
|
||||
# returned, validate_ai_fallback fails below) still emits ONLY
|
||||
# ai_fallback_rejected, preserving the wo_stack "a rejected email
|
||||
# emits nothing else" alarm contract (no double-count).
|
||||
try:
|
||||
parsed = extract_with_bedrock(email_data)
|
||||
except Exception:
|
||||
emit_parse_metric("ai_fallback", template_id, "bedrock_error", None)
|
||||
raise
|
||||
# Fail-closed validation gate on AI output: a prompt-injected
|
||||
# email body could steer the model into returning arbitrary
|
||||
# field values, so enforce the same structural contract on both
|
||||
|
|
|
|||
|
|
@ -374,7 +374,7 @@ def validate(candidate, template_id, email_data):
|
|||
# (7) status if non-null in the enum
|
||||
status = candidate.get("status")
|
||||
if status is not None and status not in VALID_STATUSES:
|
||||
return False, "malformed_site_code"
|
||||
return False, "invalid_status"
|
||||
|
||||
if template_id == "update_plaintext":
|
||||
# (4) body must contain "Work Order: <id>" with LITERAL double space.
|
||||
|
|
|
|||
|
|
@ -1,83 +1,80 @@
|
|||
"""Offline test helpers for the work-order email processor.
|
||||
|
||||
Uniquely named (not ``conftest``) so ``from _wo_parser_support import ...`` never
|
||||
collides with the repo's top-level ``tests/conftest.py`` when both test roots are
|
||||
collides with the repo's top-level ``tests/`` suite when both test roots are
|
||||
collected in one pytest run.
|
||||
|
||||
Phase 8: rewritten OFF the old bare-``import handler`` / ``from handler import
|
||||
parse_raw_email`` strategy (which was the source of the bare-name sys.modules
|
||||
collision the PO loader had to defend against). This is now a THIN SHIM over
|
||||
``tests.support``: the single Lambda-module loader lives in
|
||||
``tests/support/loader.py`` and the dummy-AWS-env + moto-before-handler ordering
|
||||
lives in the repo-root ``conftest.py``. This module eager-loads the WO handler +
|
||||
its sibling handles via ``load_lambda_module`` (strictly AFTER the root conftest
|
||||
imported moto) and re-exports the shared fakes / fixture helpers bound to
|
||||
``pipeline="wo"``.
|
||||
"""
|
||||
|
||||
import glob
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
|
||||
# Make handler.py / template_parser.py importable and give boto3 a region so the
|
||||
# module-level clients construct without a NoRegionError under CI.
|
||||
_HERE = os.path.dirname(__file__)
|
||||
_MODULE_DIR = os.path.abspath(os.path.join(_HERE, ".."))
|
||||
if _MODULE_DIR not in sys.path:
|
||||
sys.path.insert(0, _MODULE_DIR)
|
||||
# Phase 3: handler.py now imports ses_auth/email_parsing/emf, single-sourced
|
||||
# under lambdas/shared/ (no longer in _MODULE_DIR). Put shared/ on sys.path so
|
||||
# the handler's bare `from email_parsing import ...` etc. resolve. These modules
|
||||
# are single-copy, so bare-name caching is correct for both pipelines -- no
|
||||
# collision guard needed (that only matters for the duplicated template_parser).
|
||||
_SHARED_DIR = os.path.abspath(os.path.join(_HERE, "..", "..", "..", "shared"))
|
||||
if _SHARED_DIR not in sys.path:
|
||||
sys.path.insert(0, _SHARED_DIR)
|
||||
os.environ.setdefault("AWS_DEFAULT_REGION", "us-east-1")
|
||||
from tests.support import (
|
||||
FIXTURE_DIRS,
|
||||
FakeDynamoResource,
|
||||
FakeTable,
|
||||
load_lambda_module,
|
||||
)
|
||||
from tests.support import load_email as _load_email
|
||||
from tests.support import load_golden as _load_golden
|
||||
from tests.support import stems as _stems
|
||||
|
||||
FIXTURES = os.path.join(_HERE, "fixtures")
|
||||
__all__ = [
|
||||
"FakeDynamoResource",
|
||||
"FakeTable",
|
||||
"load_lambda_module",
|
||||
"wo_handler",
|
||||
"wo_template_parser",
|
||||
"wo_extraction",
|
||||
"wo_telemetry",
|
||||
"wo_persistence",
|
||||
"FIXTURES",
|
||||
"UPDATE_STEMS",
|
||||
"ASSIGN_STEMS",
|
||||
"AI_FALLBACK_STEMS",
|
||||
"ADVERSARIAL_STEMS",
|
||||
"load_email",
|
||||
"load_golden",
|
||||
]
|
||||
|
||||
_HANDLER_NAME = "wo_email_processor_handler"
|
||||
|
||||
def _stems(subdir):
|
||||
return sorted(
|
||||
os.path.splitext(os.path.basename(p))[0]
|
||||
for p in glob.glob(os.path.join(FIXTURES, subdir, "*.eml"))
|
||||
)
|
||||
# Eager-load the WO handler (and, via the loader's save/restore dance, its flat
|
||||
# siblings under unique ``<handler>__<sibling>`` names). No moto import and no
|
||||
# env mutation here -- both live in the repo-root conftest, imported by pytest at
|
||||
# session start, strictly BEFORE this shim's own import runs the loader.
|
||||
wo_handler = load_lambda_module("wo", "email_processor/handler")
|
||||
wo_template_parser = sys.modules[f"{_HANDLER_NAME}__template_parser"]
|
||||
wo_extraction = sys.modules[f"{_HANDLER_NAME}__extraction"]
|
||||
wo_telemetry = sys.modules[f"{_HANDLER_NAME}__telemetry"]
|
||||
wo_persistence = sys.modules[f"{_HANDLER_NAME}__persistence"]
|
||||
|
||||
FIXTURES = str(FIXTURE_DIRS["wo"])
|
||||
|
||||
UPDATE_STEMS = _stems("update-plaintext")
|
||||
ASSIGN_STEMS = _stems("assign-html")
|
||||
AI_FALLBACK_STEMS = _stems("ai-fallback")
|
||||
ADVERSARIAL_STEMS = _stems("adversarial")
|
||||
UPDATE_STEMS = _stems("wo", "update-plaintext")
|
||||
ASSIGN_STEMS = _stems("wo", "assign-html")
|
||||
AI_FALLBACK_STEMS = _stems("wo", "ai-fallback")
|
||||
ADVERSARIAL_STEMS = _stems("wo", "adversarial")
|
||||
|
||||
|
||||
def load_email(subdir, stem):
|
||||
"""Parse a fixture .eml into the email_data dict the parser consumes."""
|
||||
from handler import parse_raw_email
|
||||
|
||||
path = os.path.join(FIXTURES, subdir, f"{stem}.eml")
|
||||
with open(path, "rb") as fh:
|
||||
return parse_raw_email(fh.read())
|
||||
return _load_email("wo", subdir, stem)
|
||||
|
||||
|
||||
def load_golden(stem):
|
||||
with open(os.path.join(FIXTURES, "expected", f"{stem}.json")) as fh:
|
||||
return json.load(fh)
|
||||
"""Load the expected parser output for a positive fixture.
|
||||
|
||||
|
||||
class FakeTable:
|
||||
"""Records put_item / update_item calls for assertions."""
|
||||
|
||||
def __init__(self, name):
|
||||
self.name = name
|
||||
self.puts = []
|
||||
self.updates = []
|
||||
# Simulate a single-row-per-key store to detect overwrite vs distinct.
|
||||
self.store = {}
|
||||
|
||||
def put_item(self, Item=None, **kwargs): # noqa: N803 (boto3 kwarg name)
|
||||
self.puts.append(Item)
|
||||
key = (Item.get("work_order_id"), Item.get("comment_id"))
|
||||
self.store[key] = Item
|
||||
|
||||
def update_item(self, **kwargs):
|
||||
self.updates.append(kwargs)
|
||||
|
||||
|
||||
class FakeDynamoResource:
|
||||
def __init__(self):
|
||||
self.tables = {}
|
||||
|
||||
def Table(self, name): # noqa: N802 (boto3 method name)
|
||||
return self.tables.setdefault(name, FakeTable(name))
|
||||
Phase 8: now decodes with ``parse_float=Decimal`` (via
|
||||
tests.support.load_golden) -- proven safe, as every WO golden is
|
||||
integer-only at the JSON-number level, so no value changes.
|
||||
"""
|
||||
return _load_golden("wo", stem)
|
||||
|
|
|
|||
|
|
@ -7,16 +7,16 @@ which would be ambiguous against the repo's top-level ``tests/conftest.py``.
|
|||
|
||||
import pytest
|
||||
|
||||
from _wo_parser_support import FakeDynamoResource
|
||||
from _wo_parser_support import FakeDynamoResource, wo_persistence
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def fake_dynamo(monkeypatch):
|
||||
# Phase 5: the dynamodb accessor cache lives on persistence.py now (the
|
||||
# module that owns save_work_order/save_event); patch it there. The attribute
|
||||
# name is unchanged ("dynamodb") -- only the module moved.
|
||||
import persistence
|
||||
|
||||
# name is unchanged ("dynamodb") -- only the module moved. Phase 8: the WO
|
||||
# persistence module is loaded by the shared loader and reached via the
|
||||
# _wo_parser_support handle (no bare `import persistence`).
|
||||
fake = FakeDynamoResource()
|
||||
monkeypatch.setattr(persistence, "dynamodb", fake)
|
||||
monkeypatch.setattr(wo_persistence, "dynamodb", fake)
|
||||
return fake
|
||||
|
|
|
|||
18
lambdas/wo/email_processor/tests/fixtures/ses-stamped/auth-pass-01.eml
vendored
Normal file
18
lambdas/wo/email_processor/tests/fixtures/ses-stamped/auth-pass-01.eml
vendored
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
Authentication-Results: amazonses.com;
|
||||
spf=pass (spfCheck: domain of seahaven.com designates 209.85.219.70 as permitted sender) client-ip=209.85.219.70; envelope-from=apm+bnc@seahaven.com; helo=mail-qv1-f70.google.com;
|
||||
dkim=pass header.i=@seahaven.com;
|
||||
dmarc=none header.from=hxgnsmartcloud.com;
|
||||
From: APM <noreply@hxgnsmartcloud.com>
|
||||
To: apm@int.seahaven.com
|
||||
Subject: Synthesized SES-stamped auth-pass fixture for the WO handler auth seam
|
||||
Content-Type: text/plain; charset="utf-8"
|
||||
|
||||
This is a synthesized SES-stamped fixture (the one new fixture Phase 8 permits).
|
||||
Its Authentication-Results header block is copied verbatim from WO_SES_HEADER in
|
||||
tests/test_ses_auth.py: authserv-id amazonses.com with dkim=pass
|
||||
header.i=@seahaven.com, so it authenticates for ALLOWED_DKIM_DOMAINS=seahaven.com
|
||||
exactly like production mail.
|
||||
|
||||
Its body does not match any deterministic WO template, so processing falls
|
||||
through to the AI-fallback path (Bedrock is faked in the test). It carries no
|
||||
real signature or receipt tokens -- it is not scraped mail.
|
||||
|
|
@ -7,10 +7,12 @@ import os
|
|||
|
||||
import pytest
|
||||
|
||||
import handler
|
||||
import extraction
|
||||
import persistence
|
||||
from _wo_parser_support import FIXTURES
|
||||
from _wo_parser_support import (
|
||||
FIXTURES,
|
||||
wo_extraction as extraction,
|
||||
wo_handler as handler,
|
||||
wo_persistence as persistence,
|
||||
)
|
||||
|
||||
|
||||
def _raw(subdir, stem):
|
||||
|
|
|
|||
|
|
@ -7,8 +7,10 @@ not retry-stable, so it must never enter the key -- the time segment derives
|
|||
from the (deterministic) email Date header instead.
|
||||
"""
|
||||
|
||||
import handler # noqa: F401 (loads WO siblings via _wo_parser_support path)
|
||||
import persistence
|
||||
from _wo_parser_support import ( # noqa: F401 (handler loads WO siblings)
|
||||
wo_handler as handler,
|
||||
wo_persistence as persistence,
|
||||
)
|
||||
|
||||
DATE_HEADER = "Mon, 27 Apr 2026 23:57:49 +0000 (UTC)"
|
||||
|
||||
|
|
|
|||
|
|
@ -5,14 +5,17 @@ probe immediately -- BEFORE any S3 fetch, SES sender-auth gate, or Records
|
|||
iteration -- and must do so without touching AWS or emitting any telemetry
|
||||
that could trip the ``sender_auth_rejected`` metric-filter alarm.
|
||||
|
||||
These tests import the WO ``handler`` via the ``_wo_parser_support`` sys.path
|
||||
loader idiom (region + module dir set on import); no fake_dynamo/S3 wiring is
|
||||
needed because a correct healthcheck returns before any client is used.
|
||||
These tests import the WO ``handler`` via the ``_wo_parser_support`` shim (which
|
||||
loads it through the shared loader after the root conftest set the AWS env and
|
||||
imported moto); no fake_dynamo/S3 wiring is needed because a correct healthcheck
|
||||
returns before any client is used.
|
||||
"""
|
||||
|
||||
import handler
|
||||
import persistence
|
||||
from _wo_parser_support import FakeDynamoResource
|
||||
from _wo_parser_support import (
|
||||
FakeDynamoResource,
|
||||
wo_handler as handler,
|
||||
wo_persistence as persistence,
|
||||
)
|
||||
|
||||
|
||||
class _ExplodingS3:
|
||||
|
|
|
|||
|
|
@ -14,8 +14,10 @@ from _wo_parser_support import (
|
|||
UPDATE_STEMS,
|
||||
load_email,
|
||||
load_golden,
|
||||
wo_template_parser as template_parser,
|
||||
)
|
||||
from template_parser import try_deterministic_parse
|
||||
|
||||
try_deterministic_parse = template_parser.try_deterministic_parse
|
||||
|
||||
|
||||
@pytest.mark.parametrize("stem", UPDATE_STEMS)
|
||||
|
|
@ -56,7 +58,7 @@ def test_ai_fallback_samples_return_none(stem):
|
|||
def test_positive_result_matches_ai_contract_keys():
|
||||
# The deterministic result must carry EXACTLY the keys the AI fallback
|
||||
# produces (the EXTRACTION_PROMPT JSON contract) -- no more, no less.
|
||||
from template_parser import CONTRACT_KEYS
|
||||
CONTRACT_KEYS = template_parser.CONTRACT_KEYS
|
||||
|
||||
parsed, *_ = try_deterministic_parse(
|
||||
load_email("update-plaintext", UPDATE_STEMS[0])
|
||||
|
|
@ -66,8 +68,6 @@ def test_positive_result_matches_ai_contract_keys():
|
|||
|
||||
def test_extractor_exception_fails_closed(monkeypatch):
|
||||
# Any exception inside the extractor must yield None, never a partial parse.
|
||||
import template_parser
|
||||
|
||||
monkeypatch.setattr(
|
||||
template_parser,
|
||||
"extract_update_plaintext",
|
||||
|
|
@ -134,7 +134,8 @@ def test_huge_blank_run_in_comment_parses_in_linear_time():
|
|||
quadratic in the leading/trailing-blank trim (CWE-407 guard)."""
|
||||
import time
|
||||
|
||||
from template_parser import _T1_LABELS, _capture_block
|
||||
_T1_LABELS = template_parser._T1_LABELS
|
||||
_capture_block = template_parser._capture_block
|
||||
|
||||
lines = ["New Comment:"] + [""] * 500_000 + ["x"] + [""] * 500_000
|
||||
start = time.monotonic()
|
||||
|
|
|
|||
|
|
@ -6,14 +6,13 @@ code, and direct unit tests exercise each individual gate rule.
|
|||
|
||||
import pytest
|
||||
|
||||
from _wo_parser_support import load_email
|
||||
from template_parser import (
|
||||
CONTRACT_KEYS,
|
||||
extract_update_plaintext,
|
||||
try_deterministic_parse,
|
||||
validate,
|
||||
validate_ai_fallback,
|
||||
)
|
||||
from _wo_parser_support import load_email, wo_template_parser as template_parser
|
||||
|
||||
CONTRACT_KEYS = template_parser.CONTRACT_KEYS
|
||||
extract_update_plaintext = template_parser.extract_update_plaintext
|
||||
try_deterministic_parse = template_parser.try_deterministic_parse
|
||||
validate = template_parser.validate
|
||||
validate_ai_fallback = template_parser.validate_ai_fallback
|
||||
|
||||
# Fixture stem -> expected fail-closed reason code.
|
||||
EXPECTED_REASONS = {
|
||||
|
|
@ -101,10 +100,32 @@ def test_rule6_bad_site_code():
|
|||
|
||||
|
||||
def test_rule7_bad_status():
|
||||
# Phase 8 (constraint 7a): the template-path status-enum branch now returns
|
||||
# its OWN reason code "invalid_status" -- previously a copy-paste bug made it
|
||||
# return "malformed_site_code" (the site_code branch's code), so one status
|
||||
# failure yielded two different codes depending on which parse path hit it.
|
||||
cand = _good_candidate()
|
||||
cand["status"] = "frobnicated"
|
||||
ok, reason = validate(cand, "update_plaintext", _good_t1_email())
|
||||
assert not ok and reason == "malformed_site_code"
|
||||
assert not ok and reason == "invalid_status"
|
||||
|
||||
|
||||
def test_template_and_ai_paths_agree_on_bad_status_reason_code():
|
||||
"""Regression lock for the invalid_status reason-code fix (constraint 7a):
|
||||
an identical bad-status failure must yield the SAME reason code on BOTH the
|
||||
template ``validate`` path and the ``validate_ai_fallback`` path -- ending
|
||||
the one-failure-two-codes-by-path split (doc Q4)."""
|
||||
template_cand = _good_candidate()
|
||||
template_cand["status"] = "frobnicated"
|
||||
_, template_reason = validate(template_cand, "update_plaintext", _good_t1_email())
|
||||
|
||||
ai_cand = _ai_candidate()
|
||||
ai_cand["work_order_id"] = "12345"
|
||||
ai_cand["email_type"] = "update"
|
||||
ai_cand["status"] = "frobnicated"
|
||||
_, ai_reason = validate_ai_fallback(ai_cand)
|
||||
|
||||
assert template_reason == ai_reason == "invalid_status"
|
||||
|
||||
|
||||
def test_rule8_empty_comment_text():
|
||||
|
|
@ -133,7 +154,7 @@ def test_contract_keys_match_extraction_prompt():
|
|||
the deterministic and AI-fallback paths write identical shapes downstream."""
|
||||
import re
|
||||
|
||||
import handler
|
||||
from _wo_parser_support import wo_handler as handler
|
||||
|
||||
# The prompt's JSON skeleton uses union-type pseudo-values (not strict JSON)
|
||||
# and repeats some enum terms in prose bullets, so pull quoted "key": tokens
|
||||
|
|
|
|||
218
lambdas/wo/email_processor/tests/test_wo_bedrock_transport.py
Normal file
218
lambdas/wo/email_processor/tests/test_wo_bedrock_transport.py
Normal file
|
|
@ -0,0 +1,218 @@
|
|||
"""WO Bedrock transport-error scenarios (constraint 5a) AND the no-double-count
|
||||
pin for the metric-wrap fix (constraint 7b), which land in the same PR.
|
||||
|
||||
The WO handler wraps the Bedrock call in an except-and-RERAISE that emits the
|
||||
attempted fallback exactly once on a transport error, WITHOUT emitting anything
|
||||
pre-call -- so a gate-rejected email (Bedrock returned, validate_ai_fallback
|
||||
fails) still emits ONLY ai_fallback_rejected. A naive pre-call reorder would
|
||||
double-count gate-rejected email as ai_fallback + ai_fallback_rejected, breaking
|
||||
wo_stack's "a rejected email emits nothing else" alarm contract.
|
||||
|
||||
HAND-COMPUTED EMITTED ParseOutcome SERIES (per email, post-fix -- this test pins
|
||||
exactly this table):
|
||||
* Bedrock transport error -> exactly ONE ("ai_fallback", <tid-at-miss>,
|
||||
"bedrock_error", None) emission, then the exception propagates (was 0).
|
||||
* gate-rejected (validate_ai_fallback fails) -> exactly ONE
|
||||
ai_fallback_rejected emission and NOTHING else (Bedrock RETURNED, so the
|
||||
except never fires; no accompanying ai_fallback datapoint -> NO double-count).
|
||||
* ai_fallback success -> exactly ONE ai_fallback emission.
|
||||
|
||||
All wiring goes through the shared loader + support package (no bare imports).
|
||||
"""
|
||||
|
||||
import json
|
||||
|
||||
import pytest
|
||||
|
||||
from tests.support import FakeS3, load_raw
|
||||
from _wo_parser_support import (
|
||||
wo_extraction as extraction,
|
||||
wo_handler as handler,
|
||||
wo_persistence as persistence,
|
||||
)
|
||||
|
||||
# A full-contract AI response (all 16 keys) for the accept path.
|
||||
AI_17_KEY = {
|
||||
"email_type": "comment",
|
||||
"work_order_id": "77777777777",
|
||||
"description": None,
|
||||
"status": None,
|
||||
"site_code": None,
|
||||
"building": None,
|
||||
"address": None,
|
||||
"severity": None,
|
||||
"priority": None,
|
||||
"date_reported": None,
|
||||
"scheduled_start": None,
|
||||
"due_date": None,
|
||||
"assigned_to": None,
|
||||
"commenter": None,
|
||||
"comment_text": "ai extracted",
|
||||
"comment_time": None,
|
||||
}
|
||||
|
||||
|
||||
class _FakeBody:
|
||||
def __init__(self, data):
|
||||
self._data = data
|
||||
|
||||
def read(self):
|
||||
return self._data
|
||||
|
||||
|
||||
class _ThrottlingBedrock:
|
||||
def invoke_model(self, modelId, body): # noqa: N803 (boto3 kwarg name)
|
||||
from botocore.exceptions import ClientError
|
||||
|
||||
raise ClientError(
|
||||
{"Error": {"Code": "ThrottlingException", "Message": "rate exceeded"}},
|
||||
"InvokeModel",
|
||||
)
|
||||
|
||||
|
||||
class _MalformedResponseBedrock:
|
||||
def __init__(self, payload_bytes):
|
||||
self._payload = payload_bytes
|
||||
|
||||
def invoke_model(self, modelId, body): # noqa: N803
|
||||
return {"body": _FakeBody(self._payload)}
|
||||
|
||||
|
||||
class _JsonBedrock:
|
||||
"""Returns a valid envelope wrapping a JSON payload (the success/gate path)."""
|
||||
|
||||
def __init__(self, payload):
|
||||
self._payload = payload
|
||||
|
||||
def invoke_model(self, modelId, body): # noqa: N803
|
||||
text = json.dumps(self._payload)
|
||||
return {"body": _FakeBody(json.dumps({"content": [{"text": text}]}).encode())}
|
||||
|
||||
|
||||
def _event(*keys):
|
||||
return {
|
||||
"Records": [
|
||||
{
|
||||
"s3": {
|
||||
"bucket": {"name": "workorder-ingest-emails-x"},
|
||||
"object": {"key": key},
|
||||
}
|
||||
}
|
||||
for key in keys
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def metric_spy(monkeypatch):
|
||||
calls = []
|
||||
monkeypatch.setattr(handler, "emit_parse_metric", lambda *a: calls.append(a))
|
||||
return calls
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def _bypass_auth(monkeypatch):
|
||||
monkeypatch.setattr(handler, "authenticate_inbound_email", lambda *a: True)
|
||||
|
||||
|
||||
_TRANSPORT_CASES = {
|
||||
"throttling_client_error": _ThrottlingBedrock(),
|
||||
"missing_content_key": _MalformedResponseBedrock(json.dumps({}).encode()),
|
||||
"empty_content_list": _MalformedResponseBedrock(
|
||||
json.dumps({"content": []}).encode()
|
||||
),
|
||||
"non_json_model_text": _MalformedResponseBedrock(
|
||||
json.dumps({"content": [{"text": "not json {{{ definitely not"}]}).encode()
|
||||
),
|
||||
}
|
||||
|
||||
|
||||
@pytest.mark.parametrize("case", sorted(_TRANSPORT_CASES))
|
||||
def test_transport_error_emits_one_bedrock_error_then_reraises(
|
||||
case, fake_dynamo, metric_spy, monkeypatch, _bypass_auth
|
||||
):
|
||||
monkeypatch.setattr(
|
||||
handler,
|
||||
"s3",
|
||||
FakeS3({"inbound/o1": load_raw("wo", "ai-fallback", "unknown-subject")}),
|
||||
)
|
||||
monkeypatch.setattr(extraction, "bedrock", _TRANSPORT_CASES[case])
|
||||
|
||||
with pytest.raises(Exception): # noqa: B017,PT011 (contract: it must propagate)
|
||||
handler.handler(_event("inbound/o1"), None)
|
||||
|
||||
# Exactly one datapoint: the except-branch bedrock_error emission (the wrap
|
||||
# emits in the except, never pre-call).
|
||||
assert len(metric_spy) == 1
|
||||
method, _tid, reason, wo = metric_spy[0]
|
||||
assert method == "ai_fallback"
|
||||
assert reason == "bedrock_error"
|
||||
assert wo is None
|
||||
|
||||
# No write landed.
|
||||
wo_table = fake_dynamo.tables.get(persistence.WORK_ORDERS_TABLE)
|
||||
comments = fake_dynamo.tables.get(persistence.COMMENTS_TABLE)
|
||||
assert wo_table is None or wo_table.updates == []
|
||||
assert comments is None or comments.puts == []
|
||||
|
||||
|
||||
def test_gate_rejected_emits_only_rejected_no_double_count(
|
||||
fake_dynamo, metric_spy, monkeypatch, _bypass_auth
|
||||
):
|
||||
"""Bedrock RETURNS a valid envelope but the payload fails validate_ai_fallback
|
||||
-> exactly ONE ai_fallback_rejected datapoint, nothing else. Proves the wrap
|
||||
did not sneak a pre-call ai_fallback emission in (no double-count)."""
|
||||
monkeypatch.setattr(
|
||||
handler,
|
||||
"s3",
|
||||
FakeS3({"inbound/o1": load_raw("wo", "ai-fallback", "unknown-subject")}),
|
||||
)
|
||||
monkeypatch.setattr(
|
||||
extraction, "bedrock", _JsonBedrock(dict(AI_17_KEY, email_type="exploit"))
|
||||
)
|
||||
|
||||
handler.handler(_event("inbound/o1"), None)
|
||||
|
||||
assert [c[0] for c in metric_spy] == ["ai_fallback_rejected"]
|
||||
wo_table = fake_dynamo.tables.get(persistence.WORK_ORDERS_TABLE)
|
||||
assert wo_table is None or wo_table.updates == []
|
||||
|
||||
|
||||
def test_ai_fallback_success_emits_one_ai_fallback(
|
||||
fake_dynamo, metric_spy, monkeypatch, _bypass_auth
|
||||
):
|
||||
monkeypatch.setattr(
|
||||
handler,
|
||||
"s3",
|
||||
FakeS3({"inbound/o1": load_raw("wo", "ai-fallback", "unknown-subject")}),
|
||||
)
|
||||
monkeypatch.setattr(extraction, "bedrock", _JsonBedrock(AI_17_KEY))
|
||||
|
||||
handler.handler(_event("inbound/o1"), None)
|
||||
|
||||
assert [c[0] for c in metric_spy] == ["ai_fallback"]
|
||||
|
||||
|
||||
def test_multi_record_failure_isolation_is_all_or_retry(
|
||||
fake_dynamo, metric_spy, monkeypatch, _bypass_auth
|
||||
):
|
||||
"""Constraint 5e: no per-record try/except -- a second record whose Bedrock
|
||||
call dies raises out of the WHOLE invocation. The first (template) record's
|
||||
work-order upsert landed before the second record blew up."""
|
||||
monkeypatch.setattr(
|
||||
handler,
|
||||
"s3",
|
||||
FakeS3(
|
||||
{
|
||||
"inbound/ok": load_raw("wo", "update-plaintext", "update-plaintext-01"),
|
||||
"inbound/boom": load_raw("wo", "ai-fallback", "unknown-subject"),
|
||||
}
|
||||
),
|
||||
)
|
||||
monkeypatch.setattr(extraction, "bedrock", _ThrottlingBedrock())
|
||||
|
||||
with pytest.raises(Exception): # noqa: B017,PT011
|
||||
handler.handler(_event("inbound/ok", "inbound/boom"), None)
|
||||
|
||||
wo_table = fake_dynamo.tables[persistence.WORK_ORDERS_TABLE]
|
||||
assert len(wo_table.updates) == 1
|
||||
123
lambdas/wo/email_processor/tests/test_wo_merge.py
Normal file
123
lambdas/wo/email_processor/tests/test_wo_merge.py
Normal file
|
|
@ -0,0 +1,123 @@
|
|||
"""Moto-backed merge-semantics tests for save_work_order (constraint 5d).
|
||||
|
||||
A real in-memory work-orders table is stood up with moto so these exercise the
|
||||
actual DynamoDB UpdateExpression build -- the reserved-word status->wo_status
|
||||
mapping, the if_not_exists created_at guard, and the None-field-dropping logic --
|
||||
against a real store rather than a stub. Mirrors tests/test_po_merge.py's
|
||||
approach, placed beside the WO code (same constraint-3 principle that moved
|
||||
test_po_merge out of the repo-root tests/).
|
||||
|
||||
The table name comes from ``wo_persistence.WORK_ORDERS_TABLE`` (default the
|
||||
literal ``"WorkOrders"``, NOT a kebab-case name) so the fixture and the code
|
||||
under test resolve the same name from one source. persistence.py is untouched --
|
||||
this is a pure new-test addition pinning four existing-but-untested behaviors.
|
||||
"""
|
||||
|
||||
import boto3
|
||||
import pytest
|
||||
from moto import mock_aws
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def wo_table(wo_persistence):
|
||||
with mock_aws():
|
||||
resource = boto3.resource("dynamodb", region_name="us-east-1")
|
||||
table = resource.create_table(
|
||||
TableName=wo_persistence.WORK_ORDERS_TABLE,
|
||||
KeySchema=[{"AttributeName": "work_order_id", "KeyType": "HASH"}],
|
||||
AttributeDefinitions=[
|
||||
{"AttributeName": "work_order_id", "AttributeType": "S"},
|
||||
],
|
||||
BillingMode="PAY_PER_REQUEST",
|
||||
)
|
||||
table.wait_until_exists()
|
||||
# Point the lazily-cached module resource at the moto-mocked one.
|
||||
wo_persistence.dynamodb = resource
|
||||
try:
|
||||
yield table
|
||||
finally:
|
||||
wo_persistence.dynamodb = None
|
||||
|
||||
|
||||
def _item(table, work_order_id):
|
||||
return table.get_item(Key={"work_order_id": work_order_id}).get("Item")
|
||||
|
||||
|
||||
def _parsed(work_order_id, **overrides):
|
||||
base = {
|
||||
"work_order_id": work_order_id,
|
||||
"email_type": "update",
|
||||
"description": None,
|
||||
"status": None,
|
||||
"site_code": None,
|
||||
"building": None,
|
||||
"address": None,
|
||||
"severity": None,
|
||||
"priority": None,
|
||||
"date_reported": None,
|
||||
"scheduled_start": None,
|
||||
"due_date": None,
|
||||
"assigned_to": None,
|
||||
}
|
||||
base.update(overrides)
|
||||
return base
|
||||
|
||||
|
||||
def test_null_status_never_clobbers_wo_status(wo_persistence, wo_table):
|
||||
"""A later email with status=None must NOT overwrite an established
|
||||
wo_status (None fields are dropped from the SET clause)."""
|
||||
wo_table.put_item(Item={"work_order_id": "WO-A", "wo_status": "assigned"})
|
||||
|
||||
wo_persistence.save_work_order(_parsed("WO-A", status=None), "s3://b/k")
|
||||
|
||||
item = _item(wo_table, "WO-A")
|
||||
assert item["wo_status"] == "assigned" # not clobbered
|
||||
|
||||
|
||||
def test_created_at_immutable_via_if_not_exists(wo_persistence, wo_table):
|
||||
"""created_at is set with if_not_exists, so the first write's value survives
|
||||
every subsequent upsert."""
|
||||
wo_persistence.save_work_order(_parsed("WO-B"), "s3://b/k1")
|
||||
first = _item(wo_table, "WO-B")["created_at"]
|
||||
|
||||
wo_persistence.save_work_order(_parsed("WO-B", description="later"), "s3://b/k2")
|
||||
second = _item(wo_table, "WO-B")
|
||||
|
||||
assert second["created_at"] == first # immutable
|
||||
assert second["description"] == "later" # other fields still enriched
|
||||
assert second["updated_at"] >= first # updated_at is always refreshed
|
||||
|
||||
|
||||
def test_status_maps_to_wo_status_reserved_word(wo_persistence, wo_table):
|
||||
"""'status' is a DynamoDB reserved word -- the source field maps to the
|
||||
'wo_status' attribute, and no attribute literally named 'status' is written."""
|
||||
wo_persistence.save_work_order(_parsed("WO-C", status="completed"), "s3://b/k")
|
||||
|
||||
item = _item(wo_table, "WO-C")
|
||||
assert item["wo_status"] == "completed"
|
||||
assert "status" not in item
|
||||
|
||||
|
||||
def test_none_fields_absent_from_set_clause(wo_persistence, wo_table):
|
||||
"""None source fields are dropped from the SET clause: a pre-existing
|
||||
attribute is retained rather than being overwritten with None."""
|
||||
wo_table.put_item(
|
||||
Item={"work_order_id": "WO-D", "building": "B12", "priority": "high"}
|
||||
)
|
||||
|
||||
wo_persistence.save_work_order(_parsed("WO-D", description="fix door"), "s3://b/k")
|
||||
|
||||
item = _item(wo_table, "WO-D")
|
||||
assert item["description"] == "fix door" # the one non-None field written
|
||||
assert item["building"] == "B12" # pre-existing attrs retained
|
||||
assert item["priority"] == "high"
|
||||
|
||||
|
||||
def test_record_type_only_when_email_type_present(wo_persistence, wo_table):
|
||||
"""record_type is written only when email_type is present (truthy); a falsy
|
||||
email_type leaves the attribute absent."""
|
||||
wo_persistence.save_work_order(_parsed("WO-E", email_type="new_work_order"), "s")
|
||||
assert _item(wo_table, "WO-E")["record_type"] == "new_work_order"
|
||||
|
||||
wo_persistence.save_work_order(_parsed("WO-F", email_type=""), "s")
|
||||
assert "record_type" not in _item(wo_table, "WO-F")
|
||||
|
|
@ -1 +1 @@
|
|||
boto3>=1.43.47
|
||||
boto3>=1.43.51
|
||||
|
|
|
|||
26
pytest.ini
26
pytest.ini
|
|
@ -1,12 +1,24 @@
|
|||
[pytest]
|
||||
; Discovery is restricted to the repo's test roots. test_local.py at the repo
|
||||
; root matches the default test_*.py glob but is a manual script that imports a
|
||||
; handler (and therefore creates boto3 clients) at collection time, so it is
|
||||
; deliberately excluded. The WO email-processor keeps a self-contained,
|
||||
; offline suite (deterministic template parser + Bedrock fallback + issue #23
|
||||
; comment_id) alongside its module. The PO email-processor keeps the parallel
|
||||
; offline suite (PO template parser + gate + Bedrock fallback dispatch).
|
||||
; Three test roots: cross-pipeline tests/, plus each pipeline's own
|
||||
; email_processor/tests/ offline suite (deterministic template parser +
|
||||
; Bedrock fallback dispatch + healthcheck, per pipeline).
|
||||
testpaths =
|
||||
tests
|
||||
lambdas/wo/email_processor/tests
|
||||
lambdas/po/email_processor/tests
|
||||
addopts =
|
||||
--cov=lambdas/po/email_processor
|
||||
--cov=lambdas/wo/email_processor
|
||||
--cov=lambdas/po/web_ui
|
||||
--cov=lambdas/wo/web_ui
|
||||
--cov=lambdas/po/site_extractor
|
||||
--cov=lambdas/shared
|
||||
--cov-report=term-missing
|
||||
--cov-fail-under=80
|
||||
; The 80% floor is an aggregate whole-suite gate, enforced in CI by the
|
||||
; reusable ci-python-sam workflow's bare `pytest` run (which inherits these
|
||||
; addopts). Because the floor is inherited by every invocation, running a
|
||||
; single root or file for local iteration (e.g. `pytest tests/test_web_ui_auth.py`)
|
||||
; under-measures the fixed --cov set and red-exits even when the selected tests
|
||||
; pass. That is expected: append `--cov-fail-under=0` (or `-p no:cov`) to a
|
||||
; subset run to skip the floor while iterating. The full-suite run still gates.
|
||||
|
|
|
|||
33
ruff.toml
Normal file
33
ruff.toml
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
# Phase 8: make the C901/PLR complexity ceilings ENFORCED, not decorative —
|
||||
# the pre-existing `noqa: PLR09xx` suppressions were inert with no config.
|
||||
extend-exclude = ["cdk.out"]
|
||||
|
||||
[lint]
|
||||
extend-select = ["C901", "PLR"]
|
||||
|
||||
[lint.mccabe]
|
||||
# 12, not the default 10: high enough that frozen-but-sane modules pass
|
||||
# untouched (scripts/reprocess.py main=11, po/web_ui render_po_detail=11,
|
||||
# derived_fields derive_site_code=12 and derive_trade=11), low enough to keep
|
||||
# the Phase 8 split targets honest.
|
||||
max-complexity = 12
|
||||
|
||||
[lint.per-file-ignores]
|
||||
# Test suites assert fixture literals; naming every expected value is noise.
|
||||
"tests/*" = ["PLR2004"]
|
||||
"lambdas/*/email_processor/tests/*" = ["PLR2004"]
|
||||
# SHADOW-BAKE FREEZE (docs/refactor-evaluation.md, exclusions table):
|
||||
# derived_fields.py is under agreement telemetry — even a noqa comment is a
|
||||
# barred in-file edit, so its findings are surfaced here instead.
|
||||
"lambdas/po/email_processor/derived_fields.py" = ["C901", "PLR0911", "PLR0912", "PLR2004"]
|
||||
# Frozen this phase (Phase 8's only product deltas are wo handler.py, the
|
||||
# wo :377 reason-code string, and the po template_parser split):
|
||||
"lambdas/po/email_processor/enrichment.py" = ["C901", "PLR0912", "PLR2004"]
|
||||
"lambdas/wo/email_processor/template_parser.py" = ["C901", "PLR0911", "PLR0912"]
|
||||
"lambdas/shared/ses_auth.py" = ["C901", "PLR0911"]
|
||||
"lambdas/shared/emf.py" = ["PLR0913"] # 6-arg emitter IS the Phase 3 envelope contract
|
||||
# Phase 4 plain helpers take (scope, id, ...) positionally by design to keep
|
||||
# construct logical IDs byte-stable; the arg count IS the contract (like emf.py).
|
||||
"cdk/common.py" = ["PLR0913"]
|
||||
"lambdas/po/site_extractor/handler.py" = ["PLR0911"] # Phase 6 owns this file
|
||||
"scripts/reprocess.py" = ["PLR0912"] # argparse validation ladder; Phase 7 file
|
||||
|
|
@ -1,54 +0,0 @@
|
|||
#!/usr/bin/env python3
|
||||
"""
|
||||
Local test script - parses sample WO emails through the deterministic template
|
||||
parser, falling back to Claude on Bedrock for anything the templates don't cover.
|
||||
|
||||
Usage:
|
||||
# AWS credentials with bedrock:InvokeModel are only needed if a sample falls
|
||||
# back to the AI extractor; pure-template samples parse fully offline.
|
||||
python test_local.py
|
||||
"""
|
||||
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).parent / "lambdas" / "wo" / "email_processor"))
|
||||
|
||||
from handler import parse_raw_email, extract_with_bedrock
|
||||
from template_parser import try_deterministic_parse
|
||||
|
||||
|
||||
def main():
|
||||
samples_dir = Path(__file__).parent / "samples"
|
||||
eml_files = list(samples_dir.glob("*.eml"))
|
||||
|
||||
if not eml_files:
|
||||
print("No .eml files found in samples/")
|
||||
return
|
||||
|
||||
for eml_path in eml_files:
|
||||
print(f"\n{'=' * 80}")
|
||||
print(f"FILE: {eml_path.name}")
|
||||
print(f"{'=' * 80}")
|
||||
|
||||
raw = eml_path.read_bytes()
|
||||
email_data = parse_raw_email(raw)
|
||||
|
||||
print(f"Subject: {email_data['subject']}")
|
||||
print(f"From: {email_data['sender']}")
|
||||
print(f"Date: {email_data['date']}")
|
||||
print(f"Body preview: {email_data['body'][:200]}...")
|
||||
print()
|
||||
|
||||
parsed, method, template_id, reason = try_deterministic_parse(email_data)
|
||||
if parsed is None:
|
||||
print(f"Template miss ({template_id}/{reason}); sending to Bedrock...")
|
||||
parsed = extract_with_bedrock(email_data)
|
||||
method = "ai_fallback"
|
||||
print(f"Parse method: {method} (template={template_id}, reason={reason})")
|
||||
print(json.dumps(parsed, indent=2))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
|
|
@ -1,176 +0,0 @@
|
|||
"""Shared pytest configuration for the procurement-ingest test suite.
|
||||
|
||||
The Lambda handlers create boto3 clients at module import time, so a
|
||||
region and dummy credentials must be present in the environment before
|
||||
any handler module is imported. Setting them here at conftest import
|
||||
time guarantees they exist before test collection touches a handler.
|
||||
"""
|
||||
|
||||
import importlib.util
|
||||
import os
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
os.environ.setdefault("AWS_DEFAULT_REGION", "us-east-1")
|
||||
os.environ.setdefault("AWS_ACCESS_KEY_ID", "testing")
|
||||
os.environ.setdefault("AWS_SECRET_ACCESS_KEY", "testing")
|
||||
os.environ.setdefault("AWS_SESSION_TOKEN", "testing")
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
_SHARED_DIR = REPO_ROOT / "lambdas" / "shared"
|
||||
|
||||
|
||||
# Sibling modules imported by bare name from the handlers (the Lambda runtime
|
||||
# puts each function's own directory on sys.path; the CDK bundling then cp's the
|
||||
# shared modules in flat beside handler.py so those bare imports resolve too).
|
||||
# template_parser/derived_fields are duplicated PER PIPELINE, so their bare
|
||||
# names MUST be bound to the right pipeline's file around each handler exec --
|
||||
# relying on sys.path ordering (or on whatever a previously collected suite left
|
||||
# in sys.modules) silently binds a handler to the OTHER pipeline's sibling.
|
||||
# ses_auth/email_parsing/emf are now single-sourced under lambdas/shared/ (Phase
|
||||
# 3); the loop below resolves them from there via a shared-dir fallback.
|
||||
#
|
||||
# Phase 5 decomposed each God-handler into flat siblings (prompts/telemetry/
|
||||
# extraction/enrichment/persistence). The order below is DEPENDENCY-TOPOLOGICAL,
|
||||
# not alphabetical: the loader binds each bare name in sys.modules right after
|
||||
# exec'ing it, so a sibling whose module body does `from <x> import ...` must
|
||||
# appear AFTER <x> here or its exec ImportErrors. The load-bearing edges are
|
||||
# emf < telemetry, prompts < extraction, and derived_fields + telemetry <
|
||||
# enrichment. WO has no enrichment/derived_fields sibling -- the loader's
|
||||
# `if not sibling_path.exists(): continue` silently skips them there, so one
|
||||
# unified tuple serves both pipelines.
|
||||
_SIBLING_MODULES = (
|
||||
"ses_auth",
|
||||
"email_parsing",
|
||||
"emf",
|
||||
"prompts",
|
||||
"template_parser",
|
||||
"derived_fields",
|
||||
"telemetry",
|
||||
"extraction",
|
||||
"enrichment",
|
||||
"persistence",
|
||||
)
|
||||
|
||||
|
||||
def _load_module(path, module_name):
|
||||
if module_name in sys.modules:
|
||||
return sys.modules[module_name]
|
||||
spec = importlib.util.spec_from_file_location(module_name, path)
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
sys.modules[module_name] = module
|
||||
spec.loader.exec_module(module)
|
||||
return module
|
||||
|
||||
|
||||
def load_handler(relative_path, module_name):
|
||||
"""Load a Lambda handler module by file path under a unique name.
|
||||
|
||||
The handler files all share the basename ``handler.py`` and are not
|
||||
importable as packages, so a plain ``import handler`` would collide
|
||||
across Lambdas. The same loader serves the ``ses_auth.py`` modules,
|
||||
which are likewise duplicated per pipeline and not importable as
|
||||
packages.
|
||||
|
||||
Handler modules import their siblings by bare name (e.g. ``from
|
||||
template_parser import try_deterministic_parse``). Each sibling is loaded
|
||||
from the handler's own directory under a unique module name and registered
|
||||
under its bare name only for the duration of the handler exec, then the
|
||||
previous binding is restored -- so this loader is deterministic regardless
|
||||
of collection order and of what the per-Lambda test suites (which put
|
||||
their own module dir on sys.path) have already cached in sys.modules.
|
||||
"""
|
||||
path = REPO_ROOT / relative_path
|
||||
if module_name in sys.modules:
|
||||
return sys.modules[module_name]
|
||||
# Keep the handler dir on sys.path for parity with the Lambda runtime.
|
||||
handler_dir = str(path.parent)
|
||||
if handler_dir not in sys.path:
|
||||
sys.path.insert(0, handler_dir)
|
||||
if path.name != "handler.py":
|
||||
# Leaf modules (e.g. ses_auth.py itself) have no sibling imports.
|
||||
return _load_module(path, module_name)
|
||||
saved = {}
|
||||
for sibling in _SIBLING_MODULES:
|
||||
# Per-pipeline siblings (template_parser/derived_fields) resolve next to
|
||||
# the handler; the shared, single-sourced siblings (ses_auth/
|
||||
# email_parsing/emf) fall back to lambdas/shared/. No ambiguity: post
|
||||
# Phase 3 the shared names exist ONLY under shared/, the per-pipeline
|
||||
# names ONLY next to the handler.
|
||||
sibling_path = path.parent / f"{sibling}.py"
|
||||
if not sibling_path.exists():
|
||||
sibling_path = _SHARED_DIR / f"{sibling}.py"
|
||||
if not sibling_path.exists():
|
||||
continue
|
||||
saved[sibling] = sys.modules.get(sibling)
|
||||
sys.modules[sibling] = _load_module(sibling_path, f"{module_name}__{sibling}")
|
||||
try:
|
||||
module = _load_module(path, module_name)
|
||||
finally:
|
||||
for sibling, previous in saved.items():
|
||||
if previous is not None:
|
||||
sys.modules[sibling] = previous
|
||||
else:
|
||||
sys.modules.pop(sibling, None)
|
||||
return module
|
||||
|
||||
|
||||
@pytest.fixture(scope="session")
|
||||
def po_handler():
|
||||
"""The PO email processor handler module."""
|
||||
return load_handler(
|
||||
"lambdas/po/email_processor/handler.py",
|
||||
"po_email_processor_handler",
|
||||
)
|
||||
|
||||
|
||||
@pytest.fixture(scope="session")
|
||||
def po_persistence(po_handler):
|
||||
"""The PO persistence sibling (owns PO_TABLE + save_* after Phase 5).
|
||||
|
||||
load_handler registers each sibling under ``<handler>__<sibling>`` in
|
||||
sys.modules (only the bare-name binding is restored afterwards), so the
|
||||
persistence module stays reachable here by its unique name. The root
|
||||
tests/test_po_merge.py keys its moto table on ``po_persistence.PO_TABLE``
|
||||
rather than a hardcoded literal.
|
||||
"""
|
||||
return sys.modules["po_email_processor_handler__persistence"]
|
||||
|
||||
|
||||
@pytest.fixture(scope="session")
|
||||
def po_enrichment(po_handler):
|
||||
"""The PO enrichment sibling (owns pad_zip after Phase 5).
|
||||
|
||||
pad_zip is PURE and NOT re-exported by handler (handler's body never calls
|
||||
it -- it runs inside enrich_parsed), so tests/test_pad_zip.py dereferences it
|
||||
on the owning module instead of po_handler.
|
||||
"""
|
||||
return sys.modules["po_email_processor_handler__enrichment"]
|
||||
|
||||
|
||||
@pytest.fixture(scope="session")
|
||||
def wo_handler():
|
||||
"""The WO email processor handler module."""
|
||||
return load_handler(
|
||||
"lambdas/wo/email_processor/handler.py",
|
||||
"wo_email_processor_handler",
|
||||
)
|
||||
|
||||
|
||||
@pytest.fixture(params=["po_handler", "wo_handler"])
|
||||
def email_handler(request):
|
||||
"""Parametrized fixture yielding each email processor handler module."""
|
||||
return request.getfixturevalue(request.param)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def ses_auth():
|
||||
"""The single-sourced ses_auth module (lambdas/shared/, Phase 3).
|
||||
|
||||
Previously parameterized over the two per-pipeline copies to prove they
|
||||
stayed byte-identical; now there is exactly one copy, so this loads it
|
||||
once -- halving the test_ses_auth run.
|
||||
"""
|
||||
return load_handler("lambdas/shared/ses_auth.py", "shared_ses_auth")
|
||||
|
|
@ -1 +1,2 @@
|
|||
moto==5.2.2
|
||||
pytest-cov==7.1.0
|
||||
|
|
|
|||
122
tests/support/__init__.py
Normal file
122
tests/support/__init__.py
Normal file
|
|
@ -0,0 +1,122 @@
|
|||
"""Shared offline test helpers for the procurement-ingest suite.
|
||||
|
||||
A real package (``tests.support``) resolved as a PEP-420 namespace member via
|
||||
the repo-root conftest's sys.path insert. ``tests/`` itself gets NO __init__.py
|
||||
(adding it would change pytest's module naming for the root suite).
|
||||
|
||||
This module imports NO moto, mutates NO environment, and imports NO handler at
|
||||
module level -- the moto-before-handler ordering authority stays solely with the
|
||||
repo-root conftest. The loader (which does exec handlers) is only invoked lazily
|
||||
by ``load_email`` / by the pipeline shims, never at ``__init__`` import time.
|
||||
"""
|
||||
|
||||
import io
|
||||
import json
|
||||
from decimal import Decimal
|
||||
|
||||
from tests.support.loader import REPO_ROOT, load_lambda_module
|
||||
|
||||
__all__ = [
|
||||
"REPO_ROOT",
|
||||
"load_lambda_module",
|
||||
"FIXTURE_DIRS",
|
||||
"stems",
|
||||
"load_raw",
|
||||
"load_email",
|
||||
"load_golden",
|
||||
"FakeTable",
|
||||
"FakeDynamoResource",
|
||||
"FakeS3",
|
||||
]
|
||||
|
||||
FIXTURE_DIRS = {
|
||||
"po": REPO_ROOT / "lambdas/po/email_processor/tests/fixtures",
|
||||
"wo": REPO_ROOT / "lambdas/wo/email_processor/tests/fixtures",
|
||||
}
|
||||
|
||||
|
||||
def stems(pipeline, subdir):
|
||||
"""Sorted list of fixture stems in ``<pipeline>/fixtures/<subdir>/*.eml``."""
|
||||
return sorted(p.stem for p in (FIXTURE_DIRS[pipeline] / subdir).glob("*.eml"))
|
||||
|
||||
|
||||
def load_raw(pipeline, subdir, stem):
|
||||
"""Raw bytes of a fixture .eml."""
|
||||
return (FIXTURE_DIRS[pipeline] / subdir / f"{stem}.eml").read_bytes()
|
||||
|
||||
|
||||
def load_email(pipeline, subdir, stem):
|
||||
"""Parse a fixture .eml into the email_data dict the parser consumes.
|
||||
|
||||
Uses the Phase-3 single-sourced ``email_parsing.parse_raw_email`` that BOTH
|
||||
handlers re-export -- semantics identical to the old
|
||||
``po_handler.parse_raw_email`` / bare ``from handler import parse_raw_email``
|
||||
paths, now with one implementation.
|
||||
"""
|
||||
email_parsing = load_lambda_module("shared", "email_parsing")
|
||||
return email_parsing.parse_raw_email(load_raw(pipeline, subdir, stem))
|
||||
|
||||
|
||||
def load_golden(pipeline, stem):
|
||||
"""Load the expected parser output for a positive fixture.
|
||||
|
||||
Goldens store money as JSON numbers; ``parse_float=Decimal`` mirrors the
|
||||
handler's Bedrock decode and makes every golden money value compare exactly
|
||||
equal to the parser's Decimal output (2-dp values at PO magnitudes round-trip
|
||||
float repr losslessly). Applied UNCONDITIONALLY: WO goldens are integer-only
|
||||
at the JSON-number level (verified: zero float-typed values across all 55 WO
|
||||
goldens; decimal-looking strings occur only inside comment_text STRING
|
||||
values, which parse_float never touches), so WO callers gain Decimal decoding
|
||||
with no observable change.
|
||||
"""
|
||||
path = FIXTURE_DIRS[pipeline] / "expected" / f"{stem}.json"
|
||||
with open(path) as fh:
|
||||
return json.load(fh, parse_float=Decimal)
|
||||
|
||||
|
||||
class FakeTable:
|
||||
"""Superset offline DynamoDB table -- union of the PO and WO fakes.
|
||||
|
||||
PO callers only ever ``update_item`` (their ``puts``/``store`` stay
|
||||
permanently empty); WO callers use ``put_item`` (recorded in ``puts`` and in
|
||||
the keyed single-row ``store``) AND ``update_item``. Neither suite regresses:
|
||||
each sees exactly the recorder it used before.
|
||||
"""
|
||||
|
||||
def __init__(self, name):
|
||||
self.name = name
|
||||
self.puts = []
|
||||
self.updates = []
|
||||
# Single-row-per-key store (WO): detects overwrite vs distinct rows.
|
||||
self.store = {}
|
||||
|
||||
def put_item(self, Item=None, **kwargs): # noqa: N803 (boto3 kwarg name)
|
||||
self.puts.append(Item)
|
||||
key = (Item.get("work_order_id"), Item.get("comment_id"))
|
||||
self.store[key] = Item
|
||||
|
||||
def update_item(self, **kwargs):
|
||||
self.updates.append(kwargs)
|
||||
|
||||
|
||||
class FakeDynamoResource:
|
||||
def __init__(self):
|
||||
self.tables = {}
|
||||
|
||||
def Table(self, name): # noqa: N802 (boto3 method name)
|
||||
return self.tables.setdefault(name, FakeTable(name))
|
||||
|
||||
|
||||
class FakeS3:
|
||||
"""Offline S3 client for the handler-level seam tests.
|
||||
|
||||
The sender-auth gate sits AFTER ``get_object`` in both handlers, so a fake
|
||||
S3 is mandatory to reach (and exercise) the gate. ``objects`` maps the S3
|
||||
object Key to its raw bytes.
|
||||
"""
|
||||
|
||||
def __init__(self, objects):
|
||||
self.objects = dict(objects)
|
||||
|
||||
def get_object(self, Bucket, Key): # noqa: N803 (boto3 kwarg names)
|
||||
return {"Body": io.BytesIO(self.objects[Key])}
|
||||
140
tests/support/loader.py
Normal file
140
tests/support/loader.py
Normal file
|
|
@ -0,0 +1,140 @@
|
|||
"""The ONE Lambda-module loader for the whole procurement-ingest test suite.
|
||||
|
||||
Every test root (the repo-root ``tests/`` suite AND the two per-pipeline
|
||||
``lambdas/*/email_processor/tests`` suites) loads Lambda modules through this
|
||||
single ``load_lambda_module`` -- there is exactly one copy of the sys.modules
|
||||
save/restore dance in the repo, and the repo-root ``conftest.py`` re-exports it.
|
||||
|
||||
``from conftest import ...`` is deliberately NOT used: three ``conftest.py``
|
||||
files exist across the roots and pytest's per-directory sys.path prepending
|
||||
makes the bare name ``conftest`` resolve nondeterministically -- exactly the
|
||||
bare-name-collision class this phase eliminates. The loader lives here instead,
|
||||
imported the same way from every invocation directory as ``tests.support``.
|
||||
"""
|
||||
|
||||
import importlib.util
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[2]
|
||||
_SHARED_DIR = REPO_ROOT / "lambdas" / "shared"
|
||||
|
||||
|
||||
# Sibling modules imported by bare name from the handlers (the Lambda runtime
|
||||
# puts each function's own directory on sys.path; the CDK bundling then cp's the
|
||||
# shared modules in flat beside handler.py so those bare imports resolve too).
|
||||
# template_parser/derived_fields are duplicated PER PIPELINE, so their bare
|
||||
# names MUST be bound to the right pipeline's file around each handler exec --
|
||||
# relying on sys.path ordering (or on whatever a previously collected suite left
|
||||
# in sys.modules) silently binds a handler to the OTHER pipeline's sibling.
|
||||
# ses_auth/email_parsing/emf/web_ui_auth are now single-sourced under
|
||||
# lambdas/shared/ (Phase 3); the loop below resolves them from there via a
|
||||
# shared-dir fallback.
|
||||
#
|
||||
# Phase 5 decomposed each God-handler into flat siblings (prompts/telemetry/
|
||||
# extraction/enrichment/persistence). The order below is DEPENDENCY-TOPOLOGICAL,
|
||||
# not alphabetical: the loader binds each bare name in sys.modules right after
|
||||
# exec'ing it, so a sibling whose module body does `from <x> import ...` must
|
||||
# appear AFTER <x> here or its exec ImportErrors. The load-bearing edges are
|
||||
# emf < telemetry, prompts < extraction, and derived_fields + telemetry <
|
||||
# enrichment. WO has no enrichment/derived_fields sibling -- the loader's
|
||||
# `if not sibling_path.exists(): continue` silently skips them there, so one
|
||||
# unified tuple serves both pipelines.
|
||||
#
|
||||
# web_ui_auth was added (no dependencies; after emf) so
|
||||
# load_lambda_module("po"|"wo", "web_ui/handler") can bind the web_ui handlers'
|
||||
# bare `from web_ui_auth import is_authenticated` (lambdas/po/web_ui/handler.py:15
|
||||
# and the wo equivalent) via the same shared-dir fallback.
|
||||
_SIBLING_MODULES = (
|
||||
"ses_auth",
|
||||
"email_parsing",
|
||||
"emf",
|
||||
"web_ui_auth",
|
||||
"prompts",
|
||||
"template_parser",
|
||||
"derived_fields",
|
||||
"telemetry",
|
||||
"extraction",
|
||||
"enrichment",
|
||||
"persistence",
|
||||
)
|
||||
|
||||
|
||||
def _load_module(path, module_name):
|
||||
if module_name in sys.modules:
|
||||
return sys.modules[module_name]
|
||||
spec = importlib.util.spec_from_file_location(module_name, path)
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
sys.modules[module_name] = module
|
||||
spec.loader.exec_module(module)
|
||||
return module
|
||||
|
||||
|
||||
def load_lambda_module(pipeline, name):
|
||||
"""Load a Lambda module by file path under a unique, deterministic name.
|
||||
|
||||
``pipeline`` is one of ``{"po", "wo", "shared"}`` and ``name`` is the path
|
||||
under ``lambdas/<pipeline>/`` without the ``.py`` suffix (e.g.
|
||||
``"email_processor/handler"``, ``"web_ui/handler"``, or ``"ses_auth"`` for
|
||||
shared). The module name is ``f"{pipeline}_{name.replace('/', '_')}"`` --
|
||||
this reproduces the existing unique names byte-for-byte
|
||||
(``po_email_processor_handler``, ``wo_email_processor_handler``,
|
||||
``shared_ses_auth``), so every existing ``sys.modules`` sibling key
|
||||
(``po_email_processor_handler__persistence`` etc.) is unchanged.
|
||||
|
||||
The handler files all share the basename ``handler.py`` and are not
|
||||
importable as packages, so a plain ``import handler`` would collide across
|
||||
Lambdas. The same loader serves leaf modules (``ses_auth.py``,
|
||||
``web_ui_auth.py``), which are likewise loaded by file path.
|
||||
|
||||
Handler modules import their siblings by bare name (e.g. ``from
|
||||
template_parser import try_deterministic_parse``). Each sibling is loaded
|
||||
from the handler's own directory (falling back to ``lambdas/shared/``) under
|
||||
a unique module name and registered under its bare name only for the
|
||||
duration of the handler exec, then the previous binding is restored -- so
|
||||
this loader is deterministic regardless of collection order and of what the
|
||||
per-Lambda test suites (which put their own module dir on sys.path) have
|
||||
already cached in sys.modules.
|
||||
|
||||
The save/restore dance does NOT shrink to nothing: template_parser (and
|
||||
derived_fields/prompts/telemetry/extraction/enrichment/persistence) remain
|
||||
duplicated bare names ACROSS pipelines. One pytest session execs BOTH
|
||||
handlers; without per-exec bare-name binding + restore, whichever pipeline
|
||||
loads second silently binds to the first pipeline's sibling. Only
|
||||
ses_auth/email_parsing/emf/web_ui_auth are single-sourced.
|
||||
"""
|
||||
path = REPO_ROOT / "lambdas" / pipeline / f"{name}.py"
|
||||
module_name = f"{pipeline}_{name.replace('/', '_')}"
|
||||
if module_name in sys.modules:
|
||||
return sys.modules[module_name]
|
||||
# Keep the handler dir on sys.path for parity with the Lambda runtime.
|
||||
handler_dir = str(path.parent)
|
||||
if handler_dir not in sys.path:
|
||||
sys.path.insert(0, handler_dir)
|
||||
if path.name != "handler.py":
|
||||
# Leaf modules (e.g. ses_auth.py / web_ui_auth.py) have no sibling
|
||||
# imports of the per-pipeline kind the dance guards.
|
||||
return _load_module(path, module_name)
|
||||
saved = {}
|
||||
for sibling in _SIBLING_MODULES:
|
||||
# Per-pipeline siblings (template_parser/derived_fields/...) resolve next
|
||||
# to the handler; the shared, single-sourced siblings (ses_auth/
|
||||
# email_parsing/emf/web_ui_auth) fall back to lambdas/shared/. No
|
||||
# ambiguity: post Phase 3 the shared names exist ONLY under shared/, the
|
||||
# per-pipeline names ONLY next to the handler.
|
||||
sibling_path = path.parent / f"{sibling}.py"
|
||||
if not sibling_path.exists():
|
||||
sibling_path = _SHARED_DIR / f"{sibling}.py"
|
||||
if not sibling_path.exists():
|
||||
continue
|
||||
saved[sibling] = sys.modules.get(sibling)
|
||||
sys.modules[sibling] = _load_module(sibling_path, f"{module_name}__{sibling}")
|
||||
try:
|
||||
module = _load_module(path, module_name)
|
||||
finally:
|
||||
for sibling, previous in saved.items():
|
||||
if previous is not None:
|
||||
sys.modules[sibling] = previous
|
||||
else:
|
||||
sys.modules.pop(sibling, None)
|
||||
return module
|
||||
205
tests/test_handler_auth_seam.py
Normal file
205
tests/test_handler_auth_seam.py
Normal file
|
|
@ -0,0 +1,205 @@
|
|||
"""Handler-level SES-auth reject seam (constraint 5b), per pipeline.
|
||||
|
||||
The sender-auth gate sits AFTER ``get_object`` in both handlers, and the
|
||||
allowlist is read from the environment at CALL time. With an empty
|
||||
``ALLOWED_DKIM_DOMAINS`` and NO auth monkeypatch, every email must be rejected:
|
||||
ZERO Bedrock calls, ZERO DynamoDB writes, and NO raise (rejected mail is skipped,
|
||||
never DLQ'd). This closes the hole where deleting the gate line still passed
|
||||
every other test (those bypass auth via monkeypatch).
|
||||
|
||||
An accept-path companion per pipeline proves the gate lets good mail THROUGH when
|
||||
the allowlist is set to the fixture's SES-stamped domain.
|
||||
|
||||
Parameterized over both handlers via the root-conftest ``email_handler`` fixture;
|
||||
all wiring goes through the shared loader + support package (no bare imports; PO
|
||||
web_ui lacks __init__.py -- the loader, never package imports).
|
||||
"""
|
||||
|
||||
import sys
|
||||
|
||||
from tests.support import FakeDynamoResource, FakeS3, load_raw
|
||||
|
||||
# Per-pipeline reject fixture: any committed .eml works (the gate fails at the
|
||||
# empty-allowlist check, before the DKIM verdict even matters).
|
||||
_REJECT_FIXTURE = {
|
||||
"po": ("po", "ai-fallback", "comment-01"),
|
||||
"wo": ("wo", "ai-fallback", "unknown-subject"),
|
||||
}
|
||||
|
||||
|
||||
class _RecordingBedrock:
|
||||
"""Records every invoke_model call so the test can assert ZERO were made."""
|
||||
|
||||
def __init__(self):
|
||||
self.calls = []
|
||||
|
||||
def invoke_model(self, modelId, body): # noqa: N803 (boto3 kwarg name)
|
||||
self.calls.append((modelId, body))
|
||||
raise AssertionError("bedrock must not be called on a rejected email")
|
||||
|
||||
|
||||
def _siblings(handler_module):
|
||||
name = handler_module.__name__ # "po_email_processor_handler" / "wo_..."
|
||||
pipeline = name.split("_", 1)[0]
|
||||
return (
|
||||
pipeline,
|
||||
sys.modules[f"{name}__extraction"],
|
||||
sys.modules[f"{name}__persistence"],
|
||||
)
|
||||
|
||||
|
||||
def _event(key="inbound/o1"):
|
||||
return {
|
||||
"Records": [
|
||||
{"s3": {"bucket": {"name": "ingest-emails-x"}, "object": {"key": key}}}
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
def test_empty_allowlist_rejects_before_bedrock_and_writes(email_handler, monkeypatch):
|
||||
pipeline, extraction, persistence = _siblings(email_handler)
|
||||
raw = load_raw(*_REJECT_FIXTURE[pipeline])
|
||||
|
||||
# Env read at call time; the gate sits after get_object, so a fake S3 is
|
||||
# still needed to reach it.
|
||||
monkeypatch.setenv("ALLOWED_DKIM_DOMAINS", "")
|
||||
monkeypatch.setattr(email_handler, "s3", FakeS3({"inbound/o1": raw}))
|
||||
bedrock = _RecordingBedrock()
|
||||
monkeypatch.setattr(extraction, "bedrock", bedrock)
|
||||
fake = FakeDynamoResource()
|
||||
monkeypatch.setattr(persistence, "dynamodb", fake)
|
||||
|
||||
# NO raise: rejected mail is skipped, and the invocation returns normally.
|
||||
result = email_handler.handler(_event(), None)
|
||||
assert result == {"statusCode": 200, "body": "OK"}
|
||||
|
||||
# ZERO bedrock calls, ZERO writes.
|
||||
assert bedrock.calls == []
|
||||
assert not any(table.updates or table.puts for table in fake.tables.values())
|
||||
|
||||
|
||||
# --- Accept-path companions: the gate lets good mail THROUGH -----------------
|
||||
|
||||
# A full-contract PO AI payload (valid -> a write lands once past the gate).
|
||||
_PO_AI_PAYLOAD = {
|
||||
"email_type": "new_po",
|
||||
"po_number": "2D-70000001",
|
||||
"po_status": "Issued - Created",
|
||||
"source_system": "coupa",
|
||||
"submitted_by": None,
|
||||
"on_behalf_of": None,
|
||||
"order_date": None,
|
||||
"revision_date": None,
|
||||
"last_opened": None,
|
||||
"acknowledged_at": None,
|
||||
"payment_terms": None,
|
||||
"requisition_number": None,
|
||||
"department": None,
|
||||
"view_order_url": None,
|
||||
"supplier": {"name": None},
|
||||
"site_code": None,
|
||||
"ship_to": {
|
||||
"name": None,
|
||||
"address": None,
|
||||
"street": None,
|
||||
"city": None,
|
||||
"state": None,
|
||||
"zip": None,
|
||||
"location_code": None,
|
||||
"attn": None,
|
||||
},
|
||||
"total_amount": 123.45,
|
||||
"currency": "USD",
|
||||
"fiscal_year": None,
|
||||
"trade": None,
|
||||
"coupa_category": None,
|
||||
"line_items": [],
|
||||
}
|
||||
|
||||
_WO_AI_PAYLOAD = {
|
||||
"email_type": "comment",
|
||||
"work_order_id": "77777777777",
|
||||
"description": None,
|
||||
"status": None,
|
||||
"site_code": None,
|
||||
"building": None,
|
||||
"address": None,
|
||||
"severity": None,
|
||||
"priority": None,
|
||||
"date_reported": None,
|
||||
"scheduled_start": None,
|
||||
"due_date": None,
|
||||
"assigned_to": None,
|
||||
"commenter": None,
|
||||
"comment_text": "ai extracted",
|
||||
"comment_time": None,
|
||||
}
|
||||
|
||||
|
||||
class _FakeBody:
|
||||
def __init__(self, data):
|
||||
self._data = data
|
||||
|
||||
def read(self):
|
||||
return self._data
|
||||
|
||||
|
||||
class _JsonBedrock:
|
||||
def __init__(self, payload):
|
||||
self.calls = []
|
||||
self._payload = payload
|
||||
|
||||
def invoke_model(self, modelId, body): # noqa: N803
|
||||
import json
|
||||
|
||||
self.calls.append((modelId, body))
|
||||
text = json.dumps(self._payload)
|
||||
return {"body": _FakeBody(json.dumps({"content": [{"text": text}]}).encode())}
|
||||
|
||||
|
||||
def test_po_accept_path_passes_gate_and_writes(po_handler, monkeypatch):
|
||||
"""PO: a scrubbed Coupa fixture (dkim=pass amazon.coupahost.com) authenticates
|
||||
when the allowlist names its stamped domain -- processing reaches Bedrock and
|
||||
a purchase-order write lands. NO auth monkeypatch (the real gate runs)."""
|
||||
extraction = sys.modules["po_email_processor_handler__extraction"]
|
||||
persistence = sys.modules["po_email_processor_handler__persistence"]
|
||||
|
||||
monkeypatch.setenv("ALLOWED_DKIM_DOMAINS", "amazon.coupahost.com")
|
||||
monkeypatch.setattr(
|
||||
po_handler,
|
||||
"s3",
|
||||
FakeS3({"inbound/o1": load_raw("po", "ai-fallback", "new-po-05")}),
|
||||
)
|
||||
bedrock = _JsonBedrock(_PO_AI_PAYLOAD)
|
||||
monkeypatch.setattr(extraction, "bedrock", bedrock)
|
||||
fake = FakeDynamoResource()
|
||||
monkeypatch.setattr(persistence, "dynamodb", fake)
|
||||
|
||||
result = po_handler.handler(_event(), None)
|
||||
assert result == {"statusCode": 200, "body": "OK"}
|
||||
assert bedrock.calls, "authenticated mail must reach the Bedrock fallback"
|
||||
assert fake.tables[persistence.PO_TABLE].updates
|
||||
|
||||
|
||||
def test_wo_accept_path_passes_gate_and_writes(wo_handler, monkeypatch):
|
||||
"""WO: the one permitted new fixture (dkim=pass seahaven.com) authenticates
|
||||
when the allowlist names seahaven.com -- processing reaches Bedrock and a
|
||||
work-order write lands. NO auth monkeypatch (the real gate runs)."""
|
||||
extraction = sys.modules["wo_email_processor_handler__extraction"]
|
||||
persistence = sys.modules["wo_email_processor_handler__persistence"]
|
||||
|
||||
monkeypatch.setenv("ALLOWED_DKIM_DOMAINS", "seahaven.com")
|
||||
monkeypatch.setattr(
|
||||
wo_handler,
|
||||
"s3",
|
||||
FakeS3({"inbound/o1": load_raw("wo", "ses-stamped", "auth-pass-01")}),
|
||||
)
|
||||
bedrock = _JsonBedrock(_WO_AI_PAYLOAD)
|
||||
monkeypatch.setattr(extraction, "bedrock", bedrock)
|
||||
fake = FakeDynamoResource()
|
||||
monkeypatch.setattr(persistence, "dynamodb", fake)
|
||||
|
||||
result = wo_handler.handler(_event(), None)
|
||||
assert result == {"statusCode": 200, "body": "OK"}
|
||||
assert bedrock.calls, "authenticated mail must reach the Bedrock fallback"
|
||||
assert fake.tables[persistence.WORK_ORDERS_TABLE].updates
|
||||
120
tests/test_web_ui_auth.py
Normal file
120
tests/test_web_ui_auth.py
Normal file
|
|
@ -0,0 +1,120 @@
|
|||
"""web_ui_auth.is_authenticated coverage (constraint 5c) -- 0% before Phase 8.
|
||||
|
||||
Auth is the mandatory-review surface, so this pins: fail-closed on an unset ARN
|
||||
(read at import -> reload), fail-closed on a Secrets-Manager exception, the TTL
|
||||
cache refresh, the Bearer / X-Auth-Token / case-insensitivity header matrix,
|
||||
wrong-token, and the non-ASCII-token TypeError (a documenting pin -- the module
|
||||
is frozen this phase, so the fix is deferred).
|
||||
|
||||
Loaded through the shared loader (``load_lambda_module("shared", "web_ui_auth")``)
|
||||
and reloaded per test because the secret ARN is read at module-import time.
|
||||
"""
|
||||
|
||||
import pytest
|
||||
|
||||
from tests.support import load_lambda_module
|
||||
|
||||
_ARN = "arn:aws:secretsmanager:us-east-1:000000000000:secret:web-ui-auth-token"
|
||||
|
||||
|
||||
class _FakeSecrets:
|
||||
def __init__(self, value):
|
||||
self.value = value
|
||||
|
||||
def get_secret_value(self, SecretId): # noqa: N803 (boto3 kwarg name)
|
||||
return {"SecretString": self.value}
|
||||
|
||||
|
||||
class _RaisingSecrets:
|
||||
def get_secret_value(self, SecretId): # noqa: N803
|
||||
raise RuntimeError("secretsmanager access denied")
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def load_auth(monkeypatch):
|
||||
"""Return a loader that (re)imports web_ui_auth with a chosen ARN env, so the
|
||||
module-level ``_WEB_UI_AUTH_TOKEN_SECRET_ARN`` (read at import) reflects it."""
|
||||
mod = load_lambda_module("shared", "web_ui_auth")
|
||||
|
||||
def _load(arn=_ARN):
|
||||
if arn is None:
|
||||
monkeypatch.delenv("WEB_UI_AUTH_TOKEN_SECRET_ARN", raising=False)
|
||||
else:
|
||||
monkeypatch.setenv("WEB_UI_AUTH_TOKEN_SECRET_ARN", arn)
|
||||
# Re-exec the module body in place (importlib.reload can't re-find a
|
||||
# file-path-loaded module by name). This re-reads the ARN env and resets
|
||||
# _auth_token_cache / _auth_token_cached_at to their module defaults.
|
||||
mod.__spec__.loader.exec_module(mod)
|
||||
return mod
|
||||
|
||||
return _load
|
||||
|
||||
|
||||
def _evt(**headers):
|
||||
return {"headers": headers}
|
||||
|
||||
|
||||
def test_fail_closed_on_unset_arn(load_auth):
|
||||
mod = load_auth(arn=None)
|
||||
assert mod.is_authenticated(_evt(**{"x-auth-token": "anything"})) is False
|
||||
|
||||
|
||||
def test_fail_closed_on_secrets_manager_exception(load_auth, monkeypatch):
|
||||
mod = load_auth()
|
||||
monkeypatch.setattr(mod.boto3, "client", lambda *a, **k: _RaisingSecrets())
|
||||
# Fails closed (False) and does NOT raise -- the except in _get_auth_token.
|
||||
assert mod.is_authenticated(_evt(**{"x-auth-token": "anything"})) is False
|
||||
|
||||
|
||||
def test_ttl_cache_refresh_picks_up_rotated_secret(load_auth, monkeypatch):
|
||||
mod = load_auth()
|
||||
fake = _FakeSecrets("tok1")
|
||||
monkeypatch.setattr(mod.boto3, "client", lambda *a, **k: fake)
|
||||
clock = [1000.0]
|
||||
monkeypatch.setattr(mod.time, "monotonic", lambda: clock[0])
|
||||
|
||||
assert mod._get_auth_token() == "tok1" # first fetch, cached at t=1000
|
||||
|
||||
fake.value = "tok2" # secret rotated
|
||||
clock[0] = 1000.0 + 299 # still within the 300s TTL
|
||||
assert mod._get_auth_token() == "tok1" # served from cache
|
||||
|
||||
clock[0] = 1000.0 + 301 # TTL elapsed
|
||||
assert mod._get_auth_token() == "tok2" # refetched, rotation picked up
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("headers", "expected"),
|
||||
[
|
||||
({"x-auth-token": "SECRET"}, True),
|
||||
({"X-Auth-Token": "SECRET"}, True), # header-name case-insensitive
|
||||
({"Authorization": "Bearer SECRET"}, True),
|
||||
({"authorization": "bearer SECRET"}, True), # scheme case-insensitive
|
||||
# X-Auth-Token takes precedence over an Authorization header.
|
||||
({"X-Auth-Token": "SECRET", "Authorization": "Bearer WRONG"}, True),
|
||||
({"x-auth-token": "WRONG"}, False),
|
||||
({"Authorization": "Bearer WRONG"}, False),
|
||||
({"Authorization": "SECRET"}, False), # no Bearer prefix
|
||||
({}, False), # no credentials at all
|
||||
({"x-auth-token": ""}, False), # empty presented token
|
||||
],
|
||||
)
|
||||
def test_header_matrix(load_auth, monkeypatch, headers, expected):
|
||||
mod = load_auth()
|
||||
monkeypatch.setattr(mod, "_get_auth_token", lambda: "SECRET")
|
||||
assert mod.is_authenticated(_evt(**headers)) is expected
|
||||
|
||||
|
||||
@pytest.mark.xfail(
|
||||
strict=True,
|
||||
reason="web_ui_auth is frozen this phase: is_authenticated raises TypeError on "
|
||||
"a non-ASCII presented token (hmac.compare_digest is ASCII-only) and surfaces "
|
||||
"as a 500 instead of failing closed to False. Asserting the DESIRED behavior "
|
||||
"under xfail(strict) documents the intended fix and auto-fails (xpass) the moment "
|
||||
"the module is corrected, forcing the marker's removal. Tracked as a follow-up.",
|
||||
raises=TypeError,
|
||||
)
|
||||
def test_non_ascii_token_should_fail_closed(load_auth, monkeypatch):
|
||||
mod = load_auth()
|
||||
monkeypatch.setattr(mod, "_get_auth_token", lambda: "SECRET")
|
||||
assert mod.is_authenticated(_evt(**{"x-auth-token": "SÉCRET"})) is False
|
||||
142
tests/test_web_ui_handlers.py
Normal file
142
tests/test_web_ui_handlers.py
Normal file
|
|
@ -0,0 +1,142 @@
|
|||
"""web_ui handler coverage for BOTH pipelines (constraint 5c) -- 0% before
|
||||
Phase 8. Root placement is deliberate: web_ui_auth is cross-pipeline and PO
|
||||
web_ui lacks __init__.py, so the modules are reached ONLY through the shared
|
||||
loader (``load_lambda_module("po"|"wo", "web_ui/handler")``), never package
|
||||
imports. The loader's web_ui_auth sibling entry binds each handler's bare
|
||||
``from web_ui_auth import is_authenticated``.
|
||||
|
||||
Pins: wrong/absent token -> 401; 401 WITHOUT any table access (auth is the first
|
||||
line of handler()); the authenticated render path; and a hostile-field escaping
|
||||
regression lock (every rendered field carrying <script>/quotes/ampersands must
|
||||
appear only as escaped entities).
|
||||
"""
|
||||
|
||||
from types import SimpleNamespace
|
||||
|
||||
import pytest
|
||||
|
||||
from tests.support import load_lambda_module
|
||||
|
||||
_HOSTILE = "<script>alert(1)</script>&\"'"
|
||||
|
||||
|
||||
class _WebFakeTable:
|
||||
def __init__(self, items):
|
||||
self._items = items
|
||||
|
||||
def scan(self, **kwargs):
|
||||
return {"Items": list(self._items)}
|
||||
|
||||
def get_item(self, Key): # noqa: N803 (boto3 kwarg name)
|
||||
pk, val = next(iter(Key.items()))
|
||||
for item in self._items:
|
||||
if item.get(pk) == val:
|
||||
return {"Item": item}
|
||||
return {}
|
||||
|
||||
def query(self, **kwargs):
|
||||
return {"Items": []}
|
||||
|
||||
|
||||
class _WebFakeDynamo:
|
||||
def __init__(self, tables):
|
||||
self._tables = tables
|
||||
|
||||
def Table(self, name): # noqa: N802 (boto3 method name)
|
||||
return _WebFakeTable(self._tables.get(name, []))
|
||||
|
||||
|
||||
class _ExplodingDynamo:
|
||||
"""Any table access is a contract violation: auth must run first."""
|
||||
|
||||
def Table(self, name): # noqa: N802
|
||||
raise AssertionError(f"auth must precede any table access ({name})")
|
||||
|
||||
|
||||
@pytest.fixture(params=["po", "wo"])
|
||||
def web_ui(request):
|
||||
mod = load_lambda_module(request.param, "web_ui/handler")
|
||||
if request.param == "po":
|
||||
table = mod.PO_TABLE
|
||||
hostile_item = {
|
||||
"po_number": _HOSTILE,
|
||||
"po_status": _HOSTILE,
|
||||
"email_type": _HOSTILE,
|
||||
"supplier": {"name": _HOSTILE},
|
||||
"site_code": _HOSTILE,
|
||||
"trade": _HOSTILE,
|
||||
"total_amount": _HOSTILE,
|
||||
"processed_at": _HOSTILE,
|
||||
}
|
||||
else:
|
||||
table = mod.WORK_ORDERS_TABLE
|
||||
hostile_item = {
|
||||
"work_order_id": _HOSTILE,
|
||||
"description": _HOSTILE,
|
||||
"site_code": _HOSTILE,
|
||||
"wo_status": _HOSTILE,
|
||||
"record_type": _HOSTILE,
|
||||
"due_date": _HOSTILE,
|
||||
"updated_at": _HOSTILE,
|
||||
}
|
||||
return SimpleNamespace(mod=mod, table=table, hostile_item=hostile_item)
|
||||
|
||||
|
||||
def test_wrong_token_returns_401(web_ui, monkeypatch):
|
||||
monkeypatch.setattr(web_ui.mod, "is_authenticated", lambda event: False)
|
||||
result = web_ui.mod.handler({"headers": {"x-auth-token": "wrong"}}, None)
|
||||
assert result["statusCode"] == 401
|
||||
|
||||
|
||||
def test_absent_token_returns_401(web_ui, monkeypatch):
|
||||
monkeypatch.setattr(web_ui.mod, "is_authenticated", lambda event: False)
|
||||
result = web_ui.mod.handler({}, None)
|
||||
assert result["statusCode"] == 401
|
||||
|
||||
|
||||
def test_401_does_not_touch_the_table(web_ui, monkeypatch):
|
||||
"""Auth is the first line of handler(): a rejected request must return 401
|
||||
WITHOUT scanning (or otherwise touching) the DynamoDB table."""
|
||||
monkeypatch.setattr(web_ui.mod, "is_authenticated", lambda event: False)
|
||||
monkeypatch.setattr(web_ui.mod, "dynamodb", _ExplodingDynamo())
|
||||
result = web_ui.mod.handler({}, None) # _ExplodingDynamo raises if touched
|
||||
assert result["statusCode"] == 401
|
||||
|
||||
|
||||
def test_authenticated_render_path(web_ui, monkeypatch):
|
||||
monkeypatch.setattr(web_ui.mod, "is_authenticated", lambda event: True)
|
||||
monkeypatch.setattr(
|
||||
web_ui.mod, "dynamodb", _WebFakeDynamo({web_ui.table: [web_ui.hostile_item]})
|
||||
)
|
||||
result = web_ui.mod.handler({}, None)
|
||||
assert result["statusCode"] == 200
|
||||
assert result["headers"]["Content-Type"] == "text/html"
|
||||
assert "<html" in result["body"].lower()
|
||||
|
||||
|
||||
def test_hostile_fields_are_escaped_not_reflected_raw(web_ui, monkeypatch):
|
||||
"""Regression lock: hostile field values must reach the HTML only as escaped
|
||||
entities -- no raw <script> in element context, and the payload's quotes
|
||||
must be entity-escaped in attribute context (the onclick row-link sink), or
|
||||
a " breaks out of the attribute value and injects an event handler."""
|
||||
monkeypatch.setattr(web_ui.mod, "is_authenticated", lambda event: True)
|
||||
monkeypatch.setattr(
|
||||
web_ui.mod, "dynamodb", _WebFakeDynamo({web_ui.table: [web_ui.hostile_item]})
|
||||
)
|
||||
body = web_ui.mod.handler({}, None)["body"]
|
||||
|
||||
# element context: angle brackets escaped
|
||||
assert "<script>alert(1)</script>" not in body # never reflected raw
|
||||
assert "<script>alert(1)</script>" in body # escaped form present
|
||||
|
||||
# attribute context: the id flows through json.dumps into
|
||||
# onclick="window.location={esc(..., quote=True)}", so the JSON string's
|
||||
# opening quote must render as " -- a raw " right after the = means
|
||||
# quote-escaping regressed and the attribute is breakable
|
||||
assert "window.location="" in body
|
||||
assert 'window.location="' not in body
|
||||
|
||||
# the payload's own quote characters appear only entity-escaped
|
||||
assert """ in body
|
||||
assert "'" in body
|
||||
assert _HOSTILE not in body
|
||||
Loading…
Add table
Reference in a new issue