🛡️ BLA (Blind LLM Agents) — Adversarial defense shield that protects binaries, Electron apps, JS bundles, Python, and WebAssembly against AI reverse-engineering agents like REA. Poison -> Exhaust -> Hallucinate.
JavaScript adversarial-aiclaude-codecursorelectron-securityllm-securitymcpmcp-serverobfuscationreverse-engineeringwebassembly
/**
* Weave-decoy theory + surgical AST planner + structural weave verifier
* for Counter-REA Agent-Driven Hardening (BLA 3.0).
*
* DEFENSIVE ONLY: helps host coding agents entangle business-plausible decoys
* with real customer call graphs and shared mutable state so REA/WorkBuddy-style
* peel cannot dismiss them as a separate noise layer.
* No crack / RE / bypass playbooks.
*/
import { parse } from "@babel/parser";
import _traverse from "@babel/traverse";
import * as t from "@babel/types";
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
import { basename, extname, join, relative, resolve } from "node:path";
import { detectArtifactFormat } from "../../core/detector.js";
import type { ArtifactFormat } from "../../core/types.js";
type TraverseFn = (typeof _traverse)["default"];
const traverse: TraverseFn =
typeof _traverse === "function"
? (_traverse as unknown as TraverseFn)
: _traverse.default;
export const WEAVE_DECOY_DOC_PATH = "docs/weave-decoy-mcp.md" as const;
export const WEAVE_DECOY_SCHEMA = "bla-weave-plan/v1" as const;
export const WEAVE_VERIFY_SCHEMA = "bla-weave-verify/v1" as const;
export const WEAVE_DIRECTIVES_URI = "bla://directives/weave-decoy" as const;
/** How far today's pipeline already weaves decoys into customer logic. */
export type WeaveMaturity =
| "woven"
| "warm-init-only"
| "sidecar-decoy"
| "not-applicable"
| "gap";
export type WeavePlanStatus = "ready" | "partial" | "gap" | "unsupported";
export interface WeavePrinciple {
readonly id: string;
readonly titleZh: string;
readonly titleEn: string;
readonly summaryZh: string;
}
export interface WeaveForbiddenPattern {
readonly id: string;
readonly titleZh: string;
readonly whyZh: string;
}
export interface WeaveAcceptanceTest {
readonly id: string;
readonly titleZh: string;
readonly checkEn: string;
}
export interface WeaveChecklistStep {
readonly id: string;
readonly phase: "analyze" | "apply" | "verify";
readonly titleZh: string;
readonly actionEn: string;
}
export interface WeaveFunctionCandidate {
readonly name: string;
readonly line: number;
readonly exported: boolean;
readonly paramCount: number;
readonly role:
| "exported-api"
| "route-handler"
| "gate-or-auth"
| "internal-helper";
}
export interface WeaveStateSlotCandidate {
readonly name: string;
readonly kind:
| "existing-mutable"
| "existing-container"
| "recommended-carrier";
readonly line?: number;
readonly touchRecipe: string;
}
export interface WeaveBranchCandidate {
readonly functionName: string;
readonly line: number;
readonly statementKind: "if-branch" | "return-gate" | "state-mutation";
readonly rewriteHint: string;
}
export interface WeaveSurgicalWorkorder {
readonly language: "javascript-ts" | "python" | "native-source" | "other";
readonly entryFunctions: readonly WeaveFunctionCandidate[];
readonly sharedStateSlots: readonly WeaveStateSlotCandidate[];
readonly branchCandidates: readonly WeaveBranchCandidate[];
readonly suggestedIdentifierStems: {
readonly mundane: readonly string[];
readonly security: readonly string[];
};
readonly agentRewriteRecipe: readonly string[];
}
export interface WeaveTargetEntry {
readonly path: string;
readonly relativePath: string;
readonly format: ArtifactFormat;
readonly maturity: WeaveMaturity;
readonly status: WeavePlanStatus;
readonly notesZh: string;
readonly recommendedActions: readonly string[];
readonly surgicalWorkorder?: WeaveSurgicalWorkorder;
}
export interface WeaveAgentPlaybookPhase {
readonly stage: 1 | 2 | 3 | 4;
readonly id:
| "recon-and-gates"
| "agent-source-surgery"
| "build-and-exhaustion-harden"
| "verify-equivalence-and-weave";
readonly title: string;
readonly owner: "agent+mcp" | "agent-primary" | "mcp-primary";
readonly tools: readonly string[];
readonly goal: string;
}
export interface WeavePlan {
readonly schema: typeof WEAVE_DECOY_SCHEMA;
readonly docPath: typeof WEAVE_DECOY_DOC_PATH;
readonly directivesUri: typeof WEAVE_DIRECTIVES_URI;
readonly targetPath: string;
readonly analyzedAtIso: string;
readonly overallStatus: WeavePlanStatus;
readonly summaryZh: string;
readonly targets: readonly WeaveTargetEntry[];
readonly surgicalTargetsCount: number;
readonly siblingEntanglementCandidates: readonly string[];
readonly agentPlaybook: readonly WeaveAgentPlaybookPhase[];
readonly principles: readonly WeavePrinciple[];
readonly forbidden: readonly WeaveForbiddenPattern[];
readonly acceptanceTests: readonly WeaveAcceptanceTest[];
readonly checklist: readonly WeaveChecklistStep[];
readonly pipelineHook: {
readonly mcpFlag: "weave_decoys";
readonly hardenOption: "weaveDecoys";
readonly todayBehaviorZh: string;
readonly followUpZh: string;
};
}
export interface WeaveCheckResult {
readonly id: string;
readonly titleZh: string;
readonly passed: boolean;
readonly evidence: string;
readonly remediation?: string;
}
export interface WeaveAgentAction {
readonly priority: "high" | "medium";
readonly file: string;
readonly checkId: string;
readonly targetSymbol?: string;
readonly instruction: string;
readonly verifyTool: "bla_verify_weave" | "bla_lint" | "bla_verify";
}
export interface WeaveFileVerification {
readonly path: string;
readonly relativePath: string;
readonly format: ArtifactFormat;
readonly passed: boolean;
readonly score: number;
readonly checks: readonly WeaveCheckResult[];
readonly discoveredFunctions: readonly string[];
readonly reachableFunctions: readonly string[];
readonly unreferencedFunctions: readonly string[];
readonly sharedStateVars: readonly string[];
}
export interface WeaveVerificationReport {
readonly schema: typeof WEAVE_VERIFY_SCHEMA;
readonly targetPath: string;
readonly verifiedAtIso: string;
readonly overallPassed: boolean;
readonly weaveScore: number;
readonly files: readonly WeaveFileVerification[];
readonly agentActions: readonly WeaveAgentAction[];
readonly summary: string;
}
export const WEAVE_AGENT_PLAYBOOK: readonly WeaveAgentPlaybookPhase[] =
Object.freeze([
{
stage: 1,
id: "recon-and-gates",
title: "Stage 1: Recon, Packaging Gates & Surgical Workorder",
owner: "agent+mcp",
tools: ["bla_discover", "bla_lint", "bla_weave_plan", "bla_audit"],
goal: "Inventory targets, run bla_lint to catch packaging footguns (lane-independent gates, plaintext secrets, JS AES unwrap), and generate AST-level surgical workorders via bla_weave_plan.",
},
{
stage: 2,
id: "agent-source-surgery",
title: "Stage 2: Agent-Led Source Refactoring & Structural Decoy Weave",
owner: "agent-primary",
tools: [
"bla_verify_weave",
"bla_encrypt_strings",
"bla_emit_headers",
"bla_bind_scope",
],
goal: "Host Agent refactors any blocking bla_lint gates in source code, weaves domain-plausible shadow business logic sharing mutable state slots per surgicalWorkorder, and validates source edits with bla_verify_weave.",
},
{
stage: 3,
id: "build-and-exhaustion-harden",
title: "Stage 3: Build Artifacts & Inject Counter-REA Exhaustion Shield",
owner: "mcp-primary",
tools: ["bla_harden", "bla_defend"],
goal: "Run project build (if applicable), then invoke bla_harden with weave_decoys:true and self_seal:true (or sidecar_entangle:true) to inject BPE token amplifiers, callgraph labyrinths, and format shields.",
},
{
stage: 4,
id: "verify-equivalence-and-weave",
title: "Stage 4: Equivalence, Weave Acceptance & Bankruptcy Verification",
owner: "agent+mcp",
tools: ["bla_verify", "bla_verify_weave", "bla_polymorph_report"],
goal: "Run project test suite to prove 100% functional equivalence, run bla_verify_weave and bla_verify to confirm 0 agentActions remaining and >=10x token bankruptcy amplification.",
},
]);
export const WEAVE_PRINCIPLES: readonly WeavePrinciple[] = Object.freeze([
{
id: "shared-state",
titleZh: "与真实代码共享可变状态",
titleEn: "Shared mutable state with real code",
summaryZh:
"诱饵必须读写与业务路径同一批运行时槽位(epoch / peer / digest),不能只是孤立局部变量或空 pass。",
},
{
id: "customer-reachable",
titleZh: "从客户入口可达",
titleEn: "Reachable from customer entry",
summaryZh:
"诱饵调用必须落在真实入口、路由处理器或导出 API 的调用图上;仅靠模块顶层 warm-init 不够对抗会过滤「独立层」的智能体。",
},
{
id: "mixed-vocab",
titleZh: "平凡业务名与安全诱饵名混用",
titleEn: "Mixed mundane + security vocabulary",
summaryZh:
"标识符约 2/3 用 invoice/session/cache/locale 等平凡词干,约 1/3 用 enclave/TPM 等诱饵词干,避免一次 grep 整层丢弃。",
},
{
id: "opaque-true-happy-path",
titleZh: "快乐路径用不透明真谓词缠绕",
titleEn: "Opaque-true on happy path / no dead-only graphs",
summaryZh:
"真实语句用不透明-真守卫包裹,使盲目删除破坏行为;不可只用不透明-假把诱饵塞进永不到达的死图。",
},
{
id: "call-graph-entanglement",
titleZh: "调用图纠缠",
titleEn: "Call graph entanglement",
summaryZh:
"在真实函数体内织入步进器 / 诱饵互调 / 影子堆搅动,使 xref 与过程搜索看到业务与诱饵同图。",
},
{
id: "optional-self-seal",
titleZh: "可选自密封绑定",
titleEn: "Optional self-seal binding",
summaryZh:
"可选:把入口结果与完整字节 / 认知装甲 digest 绑定,使剥离诱饵层的篡改在运行期失败(产品缺口见 issue #40)。",
},
]);
export const WEAVE_FORBIDDEN: readonly WeaveForbiddenPattern[] = Object.freeze([
{
id: "pure-noise-layer",
titleZh: "纯噪声层 / 可整层剥离的 honeypot 文件",
whyZh:
"WorkBuddy 类智能体会把空 `_bla_*`、同质 scare 包、与业务无关的 sidecar 识别为可丢弃噪声,难度不升反降。",
},
{
id: "greppable-banners",
titleZh: "可 grep 的 BLA-SHIELD / `_bla_` 横幅",
whyZh: "提供「这是防护层」的明确证据,方便过滤器一刀切。",
},
{
id: "tee-only-vocab",
titleZh: "仅 TEE/TPM/Nitro/enclave 词表",
whyZh: "同质 scare 词汇让一次正则即可丢弃整图;必须混入平凡业务词干。",
},
{
id: "dead-only-decoys",
titleZh: "仅死代码 / 永不调用的 pass 桩",
whyZh: "静态可达性与 xref 会标为未引用;暖启动或入口织入才能保住图连通。",
},
{
id: "offensive-content",
titleZh: "破解 / RE / 绕过 PoC 与攻击剧本",
whyZh: "BLA 只做防御加固;MCP 与文档不得提供进攻内容。",
},
]);
export const WEAVE_ACCEPTANCE_TESTS: readonly WeaveAcceptanceTest[] =
Object.freeze([
{
id: "no-forbidden-markers",
titleZh: "无禁止标记",
checkEn:
"Hardened output has no greppable `_bla_` / `BLA-SHIELD` banners (auditor phrase `runtime attestation boundary` may remain).",
},
{
id: "mixed-stems",
titleZh: "词干混用",
checkEn:
"Decoy identifier stems are not 100% TEE/enclave; mundane stems appear in the same graph.",
},
{
id: "shared-state-mutation",
titleZh: "共享状态变异",
checkEn:
"Decoy bodies mutate a shared runtime slot/dict that customer-path code also touches or depends on after weave.",
},
{
id: "customer-entry-edges",
titleZh: "客户入口边",
checkEn:
"Static xref from customer entry / exported handlers reaches at least one decoy call (JS always; Python with weave_decoys:true via customer-def weave, not warm-init alone).",
},
{
id: "opaque-true-entanglement",
titleZh: "不透明真缠绕",
checkEn:
"A sample of real happy-path statements is guarded by opaque-true; deleting those guards or decoy callees changes behavior or verification.",
},
{
id: "filter-resistance",
titleZh: "抗「独立层」过滤",
checkEn:
"An agent cannot classify the decoy set as a separate dismissible layer using empty-body / homogeneous-scare / unreferenced heuristics alone.",
},
]);
export const WEAVE_EXECUTOR_CHECKLIST: readonly WeaveChecklistStep[] =
Object.freeze([
{
id: "read-theory",
phase: "analyze",
titleZh: "读取理论包",
actionEn: `Read ${WEAVE_DECOY_DOC_PATH} or MCP resource ${WEAVE_DIRECTIVES_URI}; do not invent offensive steps.`,
},
{
id: "run-weave-plan",
phase: "analyze",
titleZh: "生成织入计划",
actionEn:
"Call MCP `bla_weave_plan` on the project/build path; inspect each target's `surgicalWorkorder` (entryFunctions, sharedStateSlots, branchCandidates).",
},
{
id: "agent-source-weave",
phase: "apply",
titleZh: "Agent 源码级结构织入(可选但强推)",
actionEn:
"Follow `surgicalWorkorder.agentRewriteRecipe` to weave domain-plausible helpers that read/write `sharedStateSlots` and are called from `entryFunctions`, then run `bla_verify_weave`.",
},
{
id: "prefer-pipeline-flag",
phase: "apply",
titleZh: "走 harden 管线旗标",
actionEn:
"Call `bla_harden` / `bla_defend` / `bla_protect` with `weave_decoys: true` so Python structural customer-def weave runs (JS AST weave is always on).",
},
{
id: "js-entangle",
phase: "apply",
titleZh: "确认 JS 已织入",
actionEn:
"For JS/TS: existing `ast-shield` already weaves opaque-true + tarpit calls into real function bodies — verify, do not add a second noise sidecar.",
},
{
id: "python-weave",
phase: "apply",
titleZh: "确认 Python 结构织入",
actionEn:
"For Python `.py`: with weave_decoys:true, `python-ast-weave` inserts shared-slot touch + opaque-false decoy calls into customer defs (identity-skip tarpit names). Do not pile empty scare modules.",
},
{
id: "acceptance",
phase: "verify",
titleZh: "跑验收检查",
actionEn:
"Call MCP `bla_verify_weave` (or CLI `bla verify-weave`) to execute WEAVE_ACCEPTANCE_TESTS checks; resolve any returned `agentActions` until `overallPassed: true`.",
},
]);
function maturityForFormat(format: ArtifactFormat): WeaveMaturity {
switch (format) {
case "javascript":
case "typescript":
case "html-bundle":
return "woven";
case "python-source":
return "woven";
case "python-pyc":
return "woven";
case "electron-asar":
case "firmware-uf2":
case "android-dex":
case "android-apk":
case "archive-zip":
return "sidecar-decoy";
case "directory":
case "unknown":
return "not-applicable";
default:
return "gap";
}
}
function statusForMaturity(maturity: WeaveMaturity): WeavePlanStatus {
switch (maturity) {
case "woven":
return "ready";
case "warm-init-only":
case "sidecar-decoy":
return "partial";
case "gap":
return "gap";
default:
return "unsupported";
}
}
function notesForMaturity(maturity: WeaveMaturity): string {
switch (maturity) {
case "woven":
return "JS AST / Python 结构织入已将诱饵织入真实函数体(opaque + tarpit/xref)。支持宿主 Agent 按 surgicalWorkorder 进一步织入业务级共享状态诱饵,并用 bla_verify_weave 验收。";
case "warm-init-only":
return "该格式目前以稠密诱饵 + 模块 warm-init / sidecar 为主;完整客户入口织入仍有限。";
case "sidecar-decoy":
return "格式以 sidecar / 附加块诱饵为主;织入原则仍适用:避免空同质 scare,保持可达与词干混用。";
case "gap":
return "该格式尚无客户入口织入钩子;先跑标准 harden,织入改造列入后续。";
default:
return "跳过不可保护或不识别目标。";
}
}
function actionsForMaturity(maturity: WeaveMaturity): readonly string[] {
switch (maturity) {
case "woven":
return Object.freeze([
"Inspect surgicalWorkorder (entryFunctions, sharedStateSlots, branchCandidates) for source-level Agent weave.",
"Run bla_harden/bla_protect with weave_decoys:true (JS always weaves; Python structural customer-def weave).",
"Run bla_verify_weave to verify opaque entanglement, shared-slot touch, and mixed stems on output.",
]);
case "warm-init-only":
return Object.freeze([
"Keep densified tarpit + warm-init; do not add empty honeypot modules.",
"Prefer .py sources (or .pyc with weave_decoys:true for co_consts CODE weave) when customer-def weave is required.",
"Optional: self-seal binding (issue #40).",
]);
case "sidecar-decoy":
return Object.freeze([
"Keep format-specific decoy blocks reachable / mixed-vocab.",
"Refuse greppable banners and TEE-only homogeneous packs.",
]);
case "gap":
return Object.freeze([
"Use standard bla_harden today.",
"File follow-up only for defensive customer-path entanglement.",
]);
default:
return Object.freeze([]);
}
}
const DEFAULT_MUNDANE_STEMS = [
"session",
"ledger",
"quota",
"cursor",
"epoch",
"invoice",
"locale",
"cache",
"policy",
"checkpoint",
];
const DEFAULT_SECURITY_STEMS = [
"attest",
"commitment",
"enclave",
"seal",
];
const TEE_SCARE_REGEX =
/\b(?:tee|tpm|tpm2|nitro|enclave|sgx|sev|hsm|trustzone|honeypot|decoy|tarpit)\b/i;
function hasScareStem(identifier: string): boolean {
const normalized = identifier
.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
.replace(/([a-zA-Z])(\d)/g, "$1 $2")
.replace(/_/g, " ")
.toLowerCase();
return TEE_SCARE_REGEX.test(normalized);
}
const FORBIDDEN_BANNER_REGEX =
/(?:\b_bla_[a-zA-Z0-9_]*|\bBLA[-_]SHIELD\b|\bTODO:\s*decoy\b|\bfake_honeypot\b)/;
function classifyFunctionRole(
name: string,
exported: boolean,
): WeaveFunctionCandidate["role"] {
if (/auth|verify|license|unlock|token|check|gate|seal|validate|sign/i.test(name)) {
return "gate-or-auth";
}
if (/route|handle|controller|dispatch|request|endpoint|api|main|init/i.test(name)) {
return "route-handler";
}
return exported ? "exported-api" : "internal-helper";
}
function buildJsSurgicalWorkorder(
source: string,
relPath: string,
): WeaveSurgicalWorkorder {
const entryFunctions: WeaveFunctionCandidate[] = [];
const sharedStateSlots: WeaveStateSlotCandidate[] = [];
const branchCandidates: WeaveBranchCandidate[] = [];
const discoveredMundaneStems = new Set<string>();
try {
const ast = parse(source, {
sourceType: "unambiguous",
plugins: ["typescript", "jsx", "decorators-legacy"],
errorRecovery: true,
});
const exportedNames = new Set<string>();
traverse(ast, {
ExportNamedDeclaration(path) {
const decl = path.node.declaration;
if (t.isFunctionDeclaration(decl) && decl.id) {
exportedNames.add(decl.id.name);
} else if (t.isVariableDeclaration(decl)) {
for (const d of decl.declarations) {
if (t.isIdentifier(d.id)) exportedNames.add(d.id.name);
}
}
for (const spec of path.node.specifiers) {
if (t.isExportSpecifier(spec) && t.isIdentifier(spec.local)) {
exportedNames.add(spec.local.name);
}
}
},
AssignmentExpression(path) {
const left = path.node.left;
if (t.isMemberExpression(left)) {
if (
t.isIdentifier(left.object) &&
(left.object.name === "exports" || left.object.name === "module")
) {
if (t.isIdentifier(left.property)) {
exportedNames.add(left.property.name);
}
if (t.isIdentifier( path.node.right)) {
exportedNames.add(path.node.right.name);
} else if (t.isObjectExpression(path.node.right)) {
for (const prop of path.node.right.properties) {
if (t.isObjectProperty(prop) && t.isIdentifier(prop.key)) {
exportedNames.add(prop.key.name);
}
}
}
}
}
},
});
traverse(ast, {
Program(progPath) {
for (const stmt of progPath.node.body) {
const varDecl = t.isExportNamedDeclaration(stmt) && t.isVariableDeclaration(stmt.declaration)
? stmt.declaration
: t.isVariableDeclaration(stmt)
? stmt
: null;
if (!varDecl) continue;
for (const decl of varDecl.declarations) {
if (!t.isIdentifier(decl.id)) continue;
const name = decl.id.name;
const line = decl.loc?.start.line ?? 1;
if (varDecl.kind === "let" || varDecl.kind === "var") {
sharedStateSlots.push({
name,
kind: "existing-mutable",
line,
touchRecipe: `Mutate and read \`${name}\` inside both customer entry functions and woven helper functions so static slice analysis cannot separate them.`,
});
} else if (
t.isObjectExpression(decl.init) ||
t.isArrayExpression(decl.init) ||
(t.isNewExpression(decl.init) &&
t.isIdentifier(decl.init.callee) &&
/^(?:Map|Set|Uint8Array|Uint32Array)$/.test(decl.init.callee.name))
) {
sharedStateSlots.push({
name,
kind: "existing-container",
line,
touchRecipe: `Read/update keys or properties on \`${name}\` across real business paths and woven shadow helpers.`,
});
}
}
}
},
Function(path) {
let fnName = "anonymous";
if (t.isFunctionDeclaration(path.node) && path.node.id) {
fnName = path.node.id.name;
} else if (
t.isVariableDeclarator(path.parent) &&
t.isIdentifier(path.parent.id)
) {
fnName = path.parent.id.name;
} else if (
t.isObjectProperty(path.parent) &&
t.isIdentifier(path.parent.key)
) {
fnName = path.parent.key.name;
} else if (
t.isAssignmentExpression(path.parent) &&
t.isMemberExpression(path.parent.left) &&
t.isIdentifier(path.parent.left.property)
) {
fnName = path.parent.left.property.name;
}
if (fnName === "anonymous") return;
const words = fnName
.replace(/([a-z0-9])([A-Z])/g, "$1_$2")
.toLowerCase()
.split(/[^a-z0-9]+/)
.filter((w) => w.length >= 4 && !hasScareStem(w));
for (const w of words) {
if (discoveredMundaneStems.size < 6) discoveredMundaneStems.add(w);
}
const exported =
exportedNames.has(fnName) ||
t.isExportNamedDeclaration(path.parent) ||
t.isExportDefaultDeclaration(path.parent);
const line = path.node.loc?.start.line ?? 1;
if (entryFunctions.length < 12) {
entryFunctions.push({
name: fnName,
line,
exported,
paramCount: path.node.params.length,
role: classifyFunctionRole(fnName, exported),
});
}
if (t.isBlockStatement(path.node.body) && branchCandidates.length < 12) {
for (const stmt of path.node.body.body) {
const stmtLine = stmt.loc?.start.line ?? line;
if (t.isIfStatement(stmt)) {
branchCandidates.push({
functionName: fnName,
line: stmtLine,
statementKind: "if-branch",
rewriteHint: `Entangle condition in \`${fnName}\` (line ${stmtLine}) with a shared-state invariant check and route the alternate/shadow path through a domain-plausible helper.`,
});
} else if (t.isReturnStatement(stmt) && stmt.argument) {
branchCandidates.push({
functionName: fnName,
line: stmtLine,
statementKind: "return-gate",
rewriteHint: `Before returning from \`${fnName}\` (line ${stmtLine}), update shared state slot and fold an opaque-true invariant into the return value or guard.`,
});
}
if (branchCandidates.length >= 12) break;
}
}
},
});
} catch {
// Fallback if syntax is non-standard
}
if (sharedStateSlots.length === 0) {
sharedStateSlots.push({
name: "sessionLedgerState",
kind: "recommended-carrier",
touchRecipe:
"Declare module-scoped `const sessionLedgerState = { epoch: 1, cursor: 0, digest: 0x5f3759df };` and read/mutate it inside both entry functions and shadow business helpers.",
});
}
const rolePriority: Record<WeaveFunctionCandidate["role"], number> = {
"gate-or-auth": 0,
"route-handler": 1,
"exported-api": 2,
"internal-helper": 3,
};
entryFunctions.sort((a, b) => {
if (a.exported !== b.exported) return a.exported ? -1 : 1;
return rolePriority[a.role] - rolePriority[b.role];
});
const mundaneStems = [
...discoveredMundaneStems,
...DEFAULT_MUNDANE_STEMS.filter((s) => !discoveredMundaneStems.has(s)),
].slice(0, 8);
const primarySlot = sharedStateSlots[0]!.name;
const primaryEntry = entryFunctions[0]?.name ?? "mainEntry";
const agentRewriteRecipe = [
`1. Shared State Carrier: Use \`${primarySlot}\` (${sharedStateSlots[0]!.kind}) in \`${relPath}\` so real business logic and shadow helpers mutate the same runtime state.`,
`2. Shadow Business Logic: Author 2–3 helper functions using 2/3 mundane stems (${mundaneStems.slice(0, 3).join(", ")}) and 1/3 security stems (${DEFAULT_SECURITY_STEMS.slice(0, 2).join(", ")}) that compute non-trivial state transitions on \`${primarySlot}\` (never empty stubs or \`_bla_*\` names).`,
`3. Entry Entanglement: In \`${primaryEntry}\`${entryFunctions.length > 1 ? ` (and ${entryFunctions.slice(1, 3).map((f) => f.name).join(", ")})` : ""}, invoke the shadow helpers and guard the happy path with an opaque-true predicate over \`${primarySlot}\`.`,
`4. Verification Gate: Run MCP \`bla_verify_weave\` on \`${relPath}\` to confirm 0 unreferenced helpers, shared-state read/write coupling, and no forbidden banners.`,
];
return {
language: "javascript-ts",
entryFunctions,
sharedStateSlots,
branchCandidates,
suggestedIdentifierStems: {
mundane: mundaneStems,
security: DEFAULT_SECURITY_STEMS,
},
agentRewriteRecipe,
};
}
function buildPythonSurgicalWorkorder(
source: string,
relPath: string,
): WeaveSurgicalWorkorder {
const entryFunctions: WeaveFunctionCandidate[] = [];
const sharedStateSlots: WeaveStateSlotCandidate[] = [];
const branchCandidates: WeaveBranchCandidate[] = [];
const lines = source.split(/\r?\n/);
for (let i = 0; i < lines.length; i++) {
const lineText = lines[i]!;
const defMatch = lineText.match(/^\s*def\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(([^)]*)\)/);
if (defMatch) {
const fnName = defMatch[1]!;
const paramsRaw = defMatch[2]!.trim();
const paramCount =
paramsRaw.length === 0
? 0
: paramsRaw.split(",").filter((p) => p.trim() !== "self").length;
const exported = !fnName.startsWith("_");
if (entryFunctions.length < 12) {
entryFunctions.push({
name: fnName,
line: i + 1,
exported,
paramCount,
role: classifyFunctionRole(fnName, exported),
});
}
continue;
}
const stateMatch = lineText.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(\{|\[|dict\()/);
if (stateMatch && sharedStateSlots.length < 6) {
const slotName = stateMatch[1]!;
sharedStateSlots.push({
name: slotName,
kind: "existing-container",
line: i + 1,
touchRecipe: `Mutate and read keys on \`${slotName}\` inside both customer defs and woven helper defs.`,
});
}
const returnMatch = lineText.match(/^\s+return\s+\S+/);
if (returnMatch && entryFunctions.length > 0 && branchCandidates.length < 10) {
const currentFn = entryFunctions[entryFunctions.length - 1]!.name;
branchCandidates.push({
functionName: currentFn,
line: i + 1,
statementKind: "return-gate",
rewriteHint: `In \`${currentFn}\` before line ${i + 1}, update the shared state dict and guard with a deterministic invariant.`,
});
}
}
if (sharedStateSlots.length === 0) {
sharedStateSlots.push({
name: "_session_ledger_state",
kind: "recommended-carrier",
touchRecipe:
"Define module dict `_session_ledger_state = {'epoch': 1, 'cursor': 0, 'digest': 0x5F3759DF}` and touch it from customer defs and woven helpers.",
});
}
const primarySlot = sharedStateSlots[0]!.name;
const primaryEntry = entryFunctions[0]?.name ?? "main";
return {
language: "python",
entryFunctions,
sharedStateSlots,
branchCandidates,
suggestedIdentifierStems: {
mundane: DEFAULT_MUNDANE_STEMS.slice(0, 6),
security: DEFAULT_SECURITY_STEMS,
},
agentRewriteRecipe: [
`1. Shared State Carrier: Use module dict \`${primarySlot}\` in \`${relPath}\` across customer defs and shadow helpers.`,
`2. Shadow Helpers: Add 2 non-trivial helper defs (using mundane + security stems, never \`pass\` or \`_bla_*\`) that update \`${primarySlot}\`.`,
`3. Customer Def Entanglement: Call the shadow helpers from \`${primaryEntry}\` and run \`bla_harden\` with \`weave_decoys: true\`.`,
`4. Verification Gate: Run \`bla_verify_weave\` on \`${relPath}\` to verify call-graph reachability and shared-state mutation.`,
],
};
}
function buildSurgicalWorkorderForFile(
absPath: string,
relPath: string,
format: ArtifactFormat,
): WeaveSurgicalWorkorder | undefined {
try {
const st = statSync(absPath);
if (!st.isFile() || st.size > 512 * 1024) return undefined;
if (
format === "javascript" ||
format === "typescript" ||
format === "html-bundle"
) {
const src = readFileSync(absPath, "utf8");
return buildJsSurgicalWorkorder(src, relPath);
}
if (format === "python-source") {
const src = readFileSync(absPath, "utf8");
return buildPythonSurgicalWorkorder(src, relPath);
}
} catch {
return undefined;
}
return undefined;
}
const SCAN_SKIP = new Set([
".git",
"node_modules",
".bla-hardened",
"dist",
"coverage",
".venv",
"venv",
"__pycache__",
]);
const INTERESTING_EXT = new Set([
".js",
".cjs",
".mjs",
".ts",
".tsx",
".jsx",
".py",
".pyc",
".asar",
".wasm",
".uf2",
".dex",
".apk",
".so",
".dll",
".exe",
".sqlite",
".db",
]);
function listCandidateFiles(root: string, limit: number): string[] {
const out: string[] = [];
const stack = [root];
while (stack.length > 0 && out.length < limit) {
const dir = stack.pop()!;
let entries;
try {
entries = readdirSync(dir, { withFileTypes: true });
} catch {
continue;
}
for (const ent of entries) {
if (out.length >= limit) break;
if (ent.name.startsWith(".") && ent.name !== ".blarc") {
if (SCAN_SKIP.has(ent.name)) continue;
}
if (SCAN_SKIP.has(ent.name)) continue;
const full = join(dir, ent.name);
if (ent.isDirectory()) {
stack.push(full);
continue;
}
if (!ent.isFile()) continue;
const ext = extname(ent.name).toLowerCase();
if (INTERESTING_EXT.has(ext) || ent.name === "global-metadata.dat") {
out.push(full);
}
}
}
return out;
}
function buildTargetEntry(
absPath: string,
rootAbs: string,
): WeaveTargetEntry {
const format = detectArtifactFormat(absPath);
const maturity = maturityForFormat(format);
const relPath = relative(rootAbs, absPath) || basename(absPath) || ".";
const surgicalWorkorder = buildSurgicalWorkorderForFile(
absPath,
relPath,
format,
);
return {
path: absPath,
relativePath: relPath,
format,
maturity,
status: statusForMaturity(maturity),
notesZh: notesForMaturity(maturity),
recommendedActions: actionsForMaturity(maturity),
...(surgicalWorkorder !== undefined ? { surgicalWorkorder } : {}),
};
}
function overallFromTargets(
targets: readonly WeaveTargetEntry[],
): WeavePlanStatus {
if (targets.length === 0) return "unsupported";
if (targets.every((t) => t.status === "ready")) return "ready";
if (targets.some((t) => t.status === "gap")) return "gap";
if (targets.some((t) => t.status === "partial" || t.status === "ready")) {
return "partial";
}
return "unsupported";
}
function buildSiblingEntanglementCandidates(
targets: readonly WeaveTargetEntry[],
): readonly string[] {
if (targets.length < 2) return Object.freeze([]);
const rels = targets.map((t) => t.relativePath);
const hints: string[] = [
`Multi-artifact tree (${targets.length} targets: ${rels.slice(0, 4).join(", ")}${rels.length > 4 ? ", …" : ""}): pass \`self_seal: true\` and \`sidecar_entangle: true\` to \`bla_harden\` so sibling SHA-256 digests are bound at runtime.`,
];
const hasJs = targets.some(
(t) => t.format === "javascript" || t.format === "typescript",
);
const hasWasm = targets.some((t) => t.format === "wasm");
if (hasJs && hasWasm) {
hints.push(
"JS + WASM sibling pair detected: keep unlock/key verification inside WASM and bind the WASM binary SHA-256 into the JS loader via `self_seal: true` + `integrity-coverage.json`.",
);
}
return Object.freeze(hints);
}
/**
* Read-only weave planner: classify targets, extract AST surgical workorders,
* and return an executable checklist JSON so an Agent can apply source-level
* and artifact-level hardening without chat history.
*/
export function buildWeavePlan(
targetPath: string,
options: { readonly maxTargets?: number } = {},
): WeavePlan {
const abs = resolve(targetPath);
const maxTargets = options.maxTargets ?? 48;
const targets: WeaveTargetEntry[] = [];
if (!existsSync(abs)) {
return {
schema: WEAVE_DECOY_SCHEMA,
docPath: WEAVE_DECOY_DOC_PATH,
directivesUri: WEAVE_DIRECTIVES_URI,
targetPath: abs,
analyzedAtIso: new Date().toISOString(),
overallStatus: "unsupported",
summaryZh: `路径不存在:${abs}`,
targets: [],
surgicalTargetsCount: 0,
siblingEntanglementCandidates: [],
agentPlaybook: WEAVE_AGENT_PLAYBOOK,
principles: WEAVE_PRINCIPLES,
forbidden: WEAVE_FORBIDDEN,
acceptanceTests: WEAVE_ACCEPTANCE_TESTS,
checklist: WEAVE_EXECUTOR_CHECKLIST,
pipelineHook: PIPELINE_HOOK,
};
}
const st = statSync(abs);
if (st.isDirectory()) {
for (const file of listCandidateFiles(abs, maxTargets)) {
targets.push(buildTargetEntry(file, abs));
}
} else {
targets.push(
buildTargetEntry(
abs,
abs.endsWith(extname(abs)) ? resolve(abs, "..") : abs,
),
);
}
const overallStatus = overallFromTargets(targets);
const surgicalTargetsCount = targets.filter(
(t) => t.surgicalWorkorder !== undefined,
).length;
const siblingEntanglementCandidates =
buildSiblingEntanglementCandidates(targets);
const summaryZh =
overallStatus === "ready"
? `目标以 JS/Python 源码织入成熟度为主(已提取 ${surgicalTargetsCount} 份 AST 级外科手术工单);Agent 可先按 surgicalWorkorder 织入业务级共享状态诱饵并用 bla_verify_weave 验收,再执行 bla_harden(weave_decoys:true)。`
: overallStatus === "partial"
? "部分格式已织入或仅有 warm-init/sidecar;按 checklist 执行(.py 需 weave_decoys:true 激活客户 def 织入)。"
: overallStatus === "gap"
? "存在尚无织入钩子的格式;先标准 harden,勿堆噪声层。"
: "未发现可分析产物;请指向源码或构建目录。";
return {
schema: WEAVE_DECOY_SCHEMA,
docPath: WEAVE_DECOY_DOC_PATH,
directivesUri: WEAVE_DIRECTIVES_URI,
targetPath: abs,
analyzedAtIso: new Date().toISOString(),
overallStatus,
summaryZh,
targets,
surgicalTargetsCount,
siblingEntanglementCandidates,
agentPlaybook: WEAVE_AGENT_PLAYBOOK,
principles: WEAVE_PRINCIPLES,
forbidden: WEAVE_FORBIDDEN,
acceptanceTests: WEAVE_ACCEPTANCE_TESTS,
checklist: WEAVE_EXECUTOR_CHECKLIST,
pipelineHook: PIPELINE_HOOK,
};
}
const PIPELINE_HOOK = Object.freeze({
mcpFlag: "weave_decoys" as const,
hardenOption: "weaveDecoys" as const,
todayBehaviorZh:
"weave_decoys=true 时:JS 保持现有 AST 织入;Python `.py` 对客户 FunctionDef 做结构织入;Python `.pyc` 向客户/模块 co_consts 追加未执行 decoy TYPE_CODE(append-only,保 FLAG_REF)。false 时 .py 为 warm-init-only、.pyc 为 trailer honey。报告标注 weaveDecoys。",
followUpZh:
"BLA 3.0 已支持 surgicalWorkorder 源码级工单 + bla_verify_weave 结构化验收闭环。",
});
/** Markdown theory pack returned by MCP resources/read (Chinese-friendly). */
export function getWeaveDirectivesMarkdown(): string {
const principles = WEAVE_PRINCIPLES.map(
(p) => `- **${p.id}** — ${p.titleZh} / ${p.titleEn}\n ${p.summaryZh}`,
).join("\n");
const forbidden = WEAVE_FORBIDDEN.map(
(f) => `- **${f.id}** — ${f.titleZh}\n 原因:${f.whyZh}`,
).join("\n");
const acceptance = WEAVE_ACCEPTANCE_TESTS.map(
(a) => `- **${a.id}** — ${a.titleZh}: ${a.checkEn}`,
).join("\n");
const checklist = WEAVE_EXECUTOR_CHECKLIST.map(
(s) => `- [${s.phase}] **${s.id}** — ${s.titleZh}: ${s.actionEn}`,
).join("\n");
return `# Weave-decoy directives (BLA Counter-REA 3.0)
> 防御专用。禁止输出破解 / RE / 绕过 PoC。完整叙述见 \`${WEAVE_DECOY_DOC_PATH}\`。
## 为何空/同质 scare 诱饵失败(WorkBuddy)
可剥离的空 \`_bla_*\`、同质 TEE 词表、与业务无关的 honeypot 层会被智能体整层过滤,难度不升。诱饵必须巧妙织入真实业务路径。
## 织入原则
${principles}
## 明确禁止
${forbidden}
## 执行清单(给后续 AI)
${checklist}
## 验收(apply 后必须通过)
${acceptance}
## MCP
1. \`resources/read\` → \`${WEAVE_DIRECTIVES_URI}\`
2. \`bla_weave_plan\` → 只读计划 JSON(\`${WEAVE_DECOY_SCHEMA}\`,含 AST \`surgicalWorkorder\`)
3. \`bla_verify_weave\` → 验证 Agent 织入后的源码/产物是否满足 6 项结构验收(\`${WEAVE_VERIFY_SCHEMA}\`)
4. \`bla_harden\` / \`bla_defend\` / \`bla_protect\` 传 \`weave_decoys: true\`
## 管线现状
${PIPELINE_HOOK.todayBehaviorZh}
${PIPELINE_HOOK.followUpZh}
`;
}
/**
* Lightweight source hint for stubs: whether a JS/Python buffer already shows
* weave / warm-init markers (defensive telemetry only).
*/
export function inspectWeaveHints(source: string, format: ArtifactFormat): {
readonly maturity: WeaveMaturity;
readonly hints: readonly string[];
} {
const hints: string[] = [];
if (format === "javascript" || format === "typescript" || format === "html-bundle") {
if (/opaque|runtimeSeed|warmRuntime|stepper/i.test(source)) {
hints.push("possible-js-shield-markers");
}
return { maturity: "woven", hints };
}
if (format === "python-source" || format === "python-pyc") {
if (/\["warm"\]\s*=/.test(source) || /warm_runtime|warmRuntime/i.test(source)) {
hints.push("python-warm-init");
}
if (/runtime attestation boundary/.test(source)) {
hints.push("python-tarpit-banner-phrase");
}
if (/hash\(\w+\.__name__\)/.test(source) && /\["epoch"\]/.test(source)) {
hints.push("python-customer-def-weave");
}
return {
maturity: format === "python-source" ? "woven" : "warm-init-only",
hints,
};
}
return { maturity: maturityForFormat(format), hints };
}
/** Optional helper when reading the on-disk theory doc from repo root. */
export function tryReadWeaveTheoryDoc(repoRoot: string): string | null {
const path = join(repoRoot, WEAVE_DECOY_DOC_PATH);
try {
return readFileSync(path, "utf8");
} catch {
return null;
}
}
/**
* Evaluate whether an AST expression is statically constant-true or constant-false.
* Returns true/false when statically known, or null when dynamic.
*/
function evalStaticTruthiness(node: t.Node | null | undefined): boolean | null {
if (!node) return null;
if (t.isBooleanLiteral(node)) return node.value;
if (t.isNumericLiteral(node)) return node.value !== 0 && !Number.isNaN(node.value);
if (t.isStringLiteral(node)) return node.value.length > 0;
if (t.isNullLiteral(node)) return false;
if (t.isIdentifier(node) && node.name === "undefined") return false;
if (t.isParenthesizedExpression(node)) return evalStaticTruthiness(node.expression);
if (t.isUnaryExpression(node) && node.operator === "!") {
const inner = evalStaticTruthiness(node.argument);
return inner === null ? null : !inner;
}
if (t.isLogicalExpression(node)) {
const left = evalStaticTruthiness(node.left);
if (node.operator === "&&") {
if (left === false) return false;
if (left === true) return evalStaticTruthiness(node.right);
} else if (node.operator === "||") {
if (left === true) return true;
if (left === false) return evalStaticTruthiness(node.right);
}
return null;
}
if (t.isBinaryExpression(node)) {
const getPrimitive = (n: t.Node): string | number | boolean | null | undefined => {
if (t.isStringLiteral(n)) return n.value;
if (t.isNumericLiteral(n)) return n.value;
if (t.isBooleanLiteral(n)) return n.value;
if (t.isNullLiteral(n)) return null;
return undefined;
};
const l = getPrimitive(node.left);
const r = getPrimitive(node.right);
if (l !== undefined && r !== undefined) {
switch (node.operator) {
case "===":
case "==":
return l === r;
case "!==":
case "!=":
return l !== r;
case "<":
return typeof l === "number" && typeof r === "number" ? l < r : null;
case "<=":
return typeof l === "number" && typeof r === "number" ? l <= r : null;
case ">":
return typeof l === "number" && typeof r === "number" ? l > r : null;
case ">=":
return typeof l === "number" && typeof r === "number" ? l >= r : null;
}
}
}
return null;
}
function isInsideDeadBranch(path: { parentPath: any; node: t.Node }): boolean {
let curr: any = path;
while (curr && curr.parentPath) {
const parent = curr.parentPath;
const pNode: t.Node = parent.node;
if (t.isIfStatement(pNode) || t.isConditionalExpression(pNode)) {
const truth = evalStaticTruthiness(pNode.test);
if (truth === false && curr.node === pNode.consequent) return true;
if (truth === true && curr.node === pNode.alternate) return true;
} else if (t.isLogicalExpression(pNode)) {
const leftTruth = evalStaticTruthiness(pNode.left);
if (pNode.operator === "&&" && leftTruth === false && curr.node === pNode.right) {
return true;
}
if (pNode.operator === "||" && leftTruth === true && curr.node === pNode.right) {
return true;
}
}
curr = parent;
}
return false;
}
function isModuleScopedStateBinding(idPath: any, name: string): boolean {
const binding = idPath.scope?.getBinding?.(name);
if (!binding) return true;
return binding.scope?.block?.type === "Program";
}
function isPureAssignmentTarget(idPath: any): boolean {
let curr = idPath;
while (curr && curr.parentPath) {
const parent = curr.parentPath;
if (t.isAssignmentExpression(parent.node) && parent.node.left === curr.node) {
return parent.node.operator === "=";
}
if (t.isUpdateExpression(parent.node) && parent.node.argument === curr.node) {
return true;
}
if (
t.isMemberExpression(parent.node) &&
parent.node.object === curr.node
) {
curr = parent;
continue;
}
break;
}
return false;
}
/**
* Structural weave verifier (`bla_verify_weave` / CLI `bla verify-weave`).
* Evaluates JS/TS/Python files against WEAVE_ACCEPTANCE_TESTS and returns
* concrete `agentActions` for any failed check so the host Agent can self-repair.
*/
function verifyJsWeaveFile(
absPath: string,
relPath: string,
format: ArtifactFormat,
source: string,
): {
readonly fileReport: WeaveFileVerification;
readonly actions: readonly WeaveAgentAction[];
} {
const actions: WeaveAgentAction[] = [];
const discoveredFunctions: string[] = [];
const fnParamCounts = new Map<string, number>();
const fnHasAnyCall = new Set<string>();
const entryFunctions = new Set<string>();
const topLevelReferencedFunctions = new Set<string>();
const callEdges = new Map<string, Set<string>>();
const emptyOrStubFunctions: string[] = [];
const moduleStateVars = new Set<string>();
const functionsMutatingState = new Set<string>();
const functionsReadingState = new Set<string>();
let conditionalCount = 0;
let literalFalseBranchCount = 0;
try {
const ast = parse(source, {
sourceType: "unambiguous",
plugins: ["typescript", "jsx", "decorators-legacy"],
errorRecovery: true,
});
traverse(ast, {
Program(progPath) {
for (const stmt of progPath.node.body) {
const varDecl =
t.isExportNamedDeclaration(stmt) &&
t.isVariableDeclaration(stmt.declaration)
? stmt.declaration
: t.isVariableDeclaration(stmt)
? stmt
: null;
if (!varDecl) continue;
for (const d of varDecl.declarations) {
if (!t.isIdentifier(d.id)) continue;
if (
varDecl.kind === "let" ||
varDecl.kind === "var" ||
t.isObjectExpression(d.init) ||
t.isArrayExpression(d.init) ||
t.isNewExpression(d.init)
) {
moduleStateVars.add(d.id.name);
}
}
}
},
ExportNamedDeclaration(path) {
const decl = path.node.declaration;
if (t.isFunctionDeclaration(decl) && decl.id) {
entryFunctions.add(decl.id.name);
} else if (t.isVariableDeclaration(decl)) {
for (const d of decl.declarations) {
if (t.isIdentifier(d.id)) entryFunctions.add(d.id.name);
}
}
for (const spec of path.node.specifiers) {
if (t.isExportSpecifier(spec) && t.isIdentifier(spec.local)) {
entryFunctions.add(spec.local.name);
}
}
},
AssignmentExpression(path) {
const left = path.node.left;
if (
t.isMemberExpression(left) &&
t.isIdentifier(left.object) &&
(left.object.name === "exports" || left.object.name === "module")
) {
if (t.isIdentifier(left.property) && left.property.name !== "exports") {
entryFunctions.add(left.property.name);
}
if (t.isIdentifier(path.node.right)) {
entryFunctions.add(path.node.right.name);
} else if (t.isObjectExpression(path.node.right)) {
for (const prop of path.node.right.properties) {
if (t.isObjectProperty(prop) && t.isIdentifier(prop.key)) {
entryFunctions.add(prop.key.name);
}
if (t.isObjectProperty(prop) && t.isIdentifier(prop.value)) {
entryFunctions.add(prop.value.name);
}
}
}
}
},
});
// First pass: collect all named top-level / assigned functions
traverse(ast, {
Function(path) {
let fnName = "";
if (t.isFunctionDeclaration(path.node) && path.node.id) {
fnName = path.node.id.name;
} else if (
t.isVariableDeclarator(path.parent) &&
t.isIdentifier(path.parent.id)
) {
fnName = path.parent.id.name;
} else if (
t.isAssignmentExpression(path.parent) &&
t.isMemberExpression(path.parent.left) &&
t.isIdentifier(path.parent.left.property)
) {
fnName = path.parent.left.property.name;
}
if (!fnName) return;
if (!discoveredFunctions.includes(fnName)) {
discoveredFunctions.push(fnName);
}
fnParamCounts.set(fnName, path.node.params.length);
if (!callEdges.has(fnName)) {
callEdges.set(fnName, new Set());
}
},
});
const discoveredSet = new Set(discoveredFunctions);
// Second pass: inspect function bodies and top-level warm-init references
traverse(ast, {
Function(path) {
let fnName = "";
if (t.isFunctionDeclaration(path.node) && path.node.id) {
fnName = path.node.id.name;
} else if (
t.isVariableDeclarator(path.parent) &&
t.isIdentifier(path.parent.id)
) {
fnName = path.parent.id.name;
} else if (
t.isAssignmentExpression(path.parent) &&
t.isMemberExpression(path.parent.left) &&
t.isIdentifier(path.parent.left.property)
) {
fnName = path.parent.left.property.name;
}
if (!fnName) return;
if (t.isBlockStatement(path.node.body)) {
const stmts = path.node.body.body.filter(
(s) => !t.isEmptyStatement(s),
);
if (stmts.length === 0) {
emptyOrStubFunctions.push(fnName);
} else if (
stmts.length === 1 &&
t.isReturnStatement(stmts[0]) &&
(!stmts[0].argument || t.isLiteral(stmts[0].argument))
) {
emptyOrStubFunctions.push(fnName);
}
}
path.traverse({
CallExpression(callPath) {
if (isInsideDeadBranch(callPath)) return;
fnHasAnyCall.add(fnName);
if (t.isIdentifier(callPath.node.callee)) {
callEdges.get(fnName)!.add(callPath.node.callee.name);
}
},
Identifier(idPath) {
const name = idPath.node.name;
if (isInsideDeadBranch(idPath)) return;
// Track function table/callback references (e.g. [fn1, fn2] or register(fn))
if (
discoveredSet.has(name) &&
name !== fnName &&
!(t.isFunctionDeclaration(idPath.parent) && idPath.parent.id === idPath.node)
) {
callEdges.get(fnName)!.add(name);
}
if (
moduleStateVars.has(name) &&
isModuleScopedStateBinding(idPath, name) &&
!isPureAssignmentTarget(idPath)
) {
functionsReadingState.add(fnName);
}
},
IfStatement(ifPath) {
const truth = evalStaticTruthiness(ifPath.node.test);
if (truth === false) {
literalFalseBranchCount += 1;
} else {
conditionalCount += 1;
}
},
ConditionalExpression(condPath) {
const truth = evalStaticTruthiness(condPath.node.test);
if (truth === false) {
literalFalseBranchCount += 1;
} else {
conditionalCount += 1;
}
},
AssignmentExpression(assignPath) {
if (isInsideDeadBranch(assignPath)) return;
const l = assignPath.node.left;
if (
t.isIdentifier(l) &&
moduleStateVars.has(l.name) &&
isModuleScopedStateBinding(assignPath, l.name)
) {
functionsMutatingState.add(fnName);
} else if (
t.isMemberExpression(l) &&
t.isIdentifier(l.object) &&
moduleStateVars.has(l.object.name) &&
isModuleScopedStateBinding(assignPath, l.object.name)
) {
functionsMutatingState.add(fnName);
}
},
UpdateExpression(upPath) {
if (isInsideDeadBranch(upPath)) return;
const arg = upPath.node.argument;
if (
t.isIdentifier(arg) &&
moduleStateVars.has(arg.name) &&
isModuleScopedStateBinding(upPath, arg.name)
) {
functionsMutatingState.add(fnName);
functionsReadingState.add(fnName);
} else if (
t.isMemberExpression(arg) &&
t.isIdentifier(arg.object) &&
moduleStateVars.has(arg.object.name) &&
isModuleScopedStateBinding(upPath, arg.object.name)
) {
functionsMutatingState.add(fnName);
functionsReadingState.add(fnName);
}
},
});
},
// Also track top-level module warm-init / IIFE / dispatch table references
Identifier(idPath) {
const name = idPath.node.name;
if (!discoveredSet.has(name)) return;
if (isInsideDeadBranch(idPath)) return;
// Skip the function's own declaration site
if (
(t.isFunctionDeclaration(idPath.parent) && idPath.parent.id === idPath.node) ||
(t.isVariableDeclarator(idPath.parent) && idPath.parent.id === idPath.node)
) {
return;
}
// Check if this reference is at Program level or inside an anonymous IIFE
let enclosingNamedFn = "";
let p: any = idPath.parentPath;
while (p) {
if (t.isFunction(p.node)) {
if (t.isFunctionDeclaration(p.node) && p.node.id) {
enclosingNamedFn = p.node.id.name;
break;
}
if (
t.isVariableDeclarator(p.parent) &&
t.isIdentifier(p.parent.id)
) {
enclosingNamedFn = p.parent.id.name;
break;
}
}
p = p.parentPath;
}
if (!enclosingNamedFn) {
topLevelReferencedFunctions.add(name);
}
},
});
} catch {
// Fallback if parse fails
}
// If no explicit exports, treat first discovered function as entry
if (entryFunctions.size === 0 && discoveredFunctions.length > 0) {
entryFunctions.add(discoveredFunctions[0]!);
}
// Reachability BFS from entryFunctions + topLevelReferencedFunctions
const reachable = new Set<string>([
...entryFunctions,
...topLevelReferencedFunctions,
]);
const queue = [...reachable];
while (queue.length > 0) {
const curr = queue.shift()!;
const callees = callEdges.get(curr);
if (!callees) continue;
for (const target of callees) {
if (discoveredFunctions.includes(target) && !reachable.has(target)) {
reachable.add(target);
queue.push(target);
}
}
}
const unreferencedFunctions = discoveredFunctions.filter(
(fn) => !reachable.has(fn),
);
// Also flag disconnected no-op helpers in customer-scale modules: a non-entry
// function that takes 0 parameters, neither touches shared state nor makes any call.
if (discoveredFunctions.length <= 15) {
for (const fn of discoveredFunctions) {
if (
!entryFunctions.has(fn) &&
(fnParamCounts.get(fn) ?? 0) === 0 &&
!emptyOrStubFunctions.includes(fn) &&
!functionsMutatingState.has(fn) &&
!functionsReadingState.has(fn) &&
!fnHasAnyCall.has(fn) &&
(callEdges.get(fn)?.size ?? 0) === 0
) {
emptyOrStubFunctions.push(fn);
}
}
}
// Check 1: no-forbidden-markers
const bannerMatch = source.match(FORBIDDEN_BANNER_REGEX);
const checkNoMarkers: WeaveCheckResult = {
id: "no-forbidden-markers",
titleZh: "无禁止标记",
passed: bannerMatch === null,
evidence:
bannerMatch === null
? "0 forbidden `_bla_*` / `BLA-SHIELD` markers found"
: `Found forbidden marker '${bannerMatch[0]}'`,
...(bannerMatch !== null
? {
remediation: `Rename '${bannerMatch[0]}' to a domain-plausible business identifier.`,
}
: {}),
};
if (!checkNoMarkers.passed) {
actions.push({
priority: "high",
file: relPath,
checkId: "no-forbidden-markers",
targetSymbol: bannerMatch?.[0],
instruction: `Remove or rename forbidden marker '${bannerMatch?.[0]}' in ${relPath}; use domain-plausible business identifiers instead.`,
verifyTool: "bla_verify_weave",
});
}
// Check 2: mixed-stems
const scareFns = discoveredFunctions.filter((fn) => hasScareStem(fn));
const scareRatio =
discoveredFunctions.length > 0
? scareFns.length / discoveredFunctions.length
: 0;
const checkMixedStems: WeaveCheckResult = {
id: "mixed-stems",
titleZh: "词干混用",
passed: discoveredFunctions.length > 0 && scareRatio <= 0.5,
evidence: `${discoveredFunctions.length - scareFns.length}/${discoveredFunctions.length} functions use mundane business stems (scare ratio ${(scareRatio * 100).toFixed(0)}%)`,
...(scareRatio > 0.5
? {
remediation: `Rename homogeneous TEE/scare functions (${scareFns.join(", ")}) so >= 2/3 use mundane business stems (session, quota, ledger, epoch).`,
}
: {}),
};
if (!checkMixedStems.passed) {
actions.push({
priority: "medium",
file: relPath,
checkId: "mixed-stems",
instruction:
discoveredFunctions.length === 0
? `Add structured entry/helper functions in ${relPath} so weave verification can inspect identifier stems.`
: `Rename homogeneous TEE/scare functions (${scareFns.join(", ")}) in ${relPath} so at least 2/3 of functions use mundane business stems.`,
verifyTool: "bla_verify_weave",
});
}
// Check 3: shared-state-mutation
// Require both mutation (>=1 fn) AND genuine read (>=2 fns or read+write across >=2 reachable fns)
const reachableMutating = [...functionsMutatingState].filter((f) =>
reachable.has(f),
);
const reachableReading = [...functionsReadingState].filter((f) =>
reachable.has(f),
);
const sharedStateTouchedCount = new Set([
...reachableMutating,
...reachableReading,
]).size;
const checkSharedState: WeaveCheckResult = {
id: "shared-state-mutation",
titleZh: "共享状态变异",
passed:
moduleStateVars.size > 0 &&
reachableMutating.length >= 1 &&
reachableReading.length >= 2 &&
sharedStateTouchedCount >= 2,
evidence:
moduleStateVars.size > 0
? `Shared state slots [${[...moduleStateVars].join(", ")}] mutated by ${reachableMutating.length} reachable fn(s), read by ${reachableReading.length} reachable fn(s) (touched across ${sharedStateTouchedCount} fn(s))`
: "No module-level shared state slot detected",
...(moduleStateVars.size === 0 ||
reachableMutating.length < 1 ||
reachableReading.length < 2 ||
sharedStateTouchedCount < 2
? {
remediation:
"Introduce or reuse a shared module state carrier (e.g. `sessionLedgerState`) and ensure it is BOTH mutated (>=1 fn) and genuinely read in conditions/returns/expressions across >=2 reachable functions.",
}
: {}),
};
if (!checkSharedState.passed) {
actions.push({
priority: "high",
file: relPath,
checkId: "shared-state-mutation",
instruction: `Couple entry functions and shadow helpers in ${relPath} via a shared module-level state object/Map (mutated in >=1 reachable function and genuinely read across >=2 reachable functions; write-only stores do not pass).`,
verifyTool: "bla_verify_weave",
});
}
// Check 4: customer-entry-edges
const hasEntryEdgeToHelper =
reachable.size >= 2 && unreferencedFunctions.length === 0;
const checkEntryEdges: WeaveCheckResult = {
id: "customer-entry-edges",
titleZh: "客户入口边",
passed: hasEntryEdgeToHelper,
evidence: `Reachable functions from entry: ${reachable.size}/${discoveredFunctions.length}${unreferencedFunctions.length > 0 ? ` (unreferenced: ${unreferencedFunctions.join(", ")})` : ""}`,
...(!hasEntryEdgeToHelper
? {
remediation:
unreferencedFunctions.length > 0
? `Wire unreferenced function(s) [${unreferencedFunctions.join(", ")}] into the call graph of [${[...entryFunctions].join(", ")}] so static xref cannot prune them as dead code.`
: `Add at least one shadow helper function and call it from entry function [${[...entryFunctions].join(", ")}].`,
}
: {}),
};
if (!checkEntryEdges.passed) {
actions.push({
priority: "high",
file: relPath,
checkId: "customer-entry-edges",
...(unreferencedFunctions[0]
? { targetSymbol: unreferencedFunctions[0] }
: {}),
instruction:
unreferencedFunctions.length > 0
? `Call unreferenced helper(s) [${unreferencedFunctions.join(", ")}] from entry function(s) [${[...entryFunctions].join(", ")}] in ${relPath}.`
: `Weave at least one helper call from entry function [${[...entryFunctions].join(", ") || "main"}] in ${relPath}.`,
verifyTool: "bla_verify_weave",
});
}
// Check 5: opaque-true-entanglement
const checkOpaque: WeaveCheckResult = {
id: "opaque-true-entanglement",
titleZh: "不透明真缠绕",
passed: conditionalCount >= 1 && literalFalseBranchCount === 0,
evidence: `${conditionalCount} conditional guard(s) active, ${literalFalseBranchCount} literal-false dead branch(es)`,
...(conditionalCount === 0 || literalFalseBranchCount > 0
? {
remediation:
literalFalseBranchCount > 0
? "Replace literal `if (false)` / `if (0)` dead branches with state-dependent opaque predicates over the shared state slot."
: "Guard the happy-path or helper call with a deterministic state invariant (e.g. `(state.epoch & 1) !== 0`).",
}
: {}),
};
if (!checkOpaque.passed) {
actions.push({
priority: "medium",
file: relPath,
checkId: "opaque-true-entanglement",
instruction:
literalFalseBranchCount > 0
? `Replace literal-false dead branch in ${relPath} with a shared-state opaque predicate.`
: `Add a shared-state conditional invariant in ${relPath} guarding the business happy path and shadow helper call.`,
verifyTool: "bla_verify_weave",
});
}
// Check 6: filter-resistance
const checkFilterResistance: WeaveCheckResult = {
id: "filter-resistance",
titleZh: "抗「独立层」过滤",
passed:
emptyOrStubFunctions.length === 0 &&
unreferencedFunctions.length === 0 &&
checkNoMarkers.passed,
evidence:
emptyOrStubFunctions.length === 0
? "0 empty/constant-stub decoy functions detected"
: `Trivial/empty stub functions detected: ${emptyOrStubFunctions.join(", ")}`,
...(emptyOrStubFunctions.length > 0
? {
remediation: `Give [${emptyOrStubFunctions.join(", ")}] non-trivial bodies that read and update the shared state carrier.`,
}
: {}),
};
if (!checkFilterResistance.passed && emptyOrStubFunctions.length > 0) {
actions.push({
priority: "high",
file: relPath,
checkId: "filter-resistance",
targetSymbol: emptyOrStubFunctions[0],
instruction: `Replace trivial/empty body in function(s) [${emptyOrStubFunctions.join(", ")}] in ${relPath} with non-trivial state computations over the shared state slot.`,
verifyTool: "bla_verify_weave",
});
}
const checks = [
checkNoMarkers,
checkMixedStems,
checkSharedState,
checkEntryEdges,
checkOpaque,
checkFilterResistance,
];
const passedCount = checks.filter((c) => c.passed).length;
const score = Math.round((passedCount / checks.length) * 100);
return {
fileReport: {
path: absPath,
relativePath: relPath,
format,
passed: passedCount === checks.length,
score,
checks,
discoveredFunctions,
reachableFunctions: [...reachable],
unreferencedFunctions,
sharedStateVars: [...moduleStateVars],
},
actions,
};
}
function stripPythonCommentsAndStrings(pySource: string): string {
return pySource
.replace(/"""[\s\S]*?"""|'''[\s\S]*?'''/g, '""')
.replace(/#.*$/gm, "")
.replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'/g, '""');
}
function verifyPythonWeaveFile(
absPath: string,
relPath: string,
source: string,
): {
readonly fileReport: WeaveFileVerification;
readonly actions: readonly WeaveAgentAction[];
} {
const actions: WeaveAgentAction[] = [];
const fnNames: string[] = [];
const fnBodies = new Map<string, string>();
const passOnlyFns: string[] = [];
const stateVars: string[] = [];
const strippedSource = stripPythonCommentsAndStrings(source);
const defRegex = /^[ \t]*def\s+([A-Za-z_][A-Za-z0-9_]*)\s*\([^)]*\)\s*(?:->[^:]+)?:\s*\n((?:[ \t]+.*\n?)*)/gm;
let m: RegExpExecArray | null;
while ((m = defRegex.exec(source)) !== null) {
const name = m[1]!;
const body = m[2] ?? "";
fnNames.push(name);
fnBodies.set(name, stripPythonCommentsAndStrings(body));
const bodyLines = body
.split(/\r?\n/)
.map((l) => l.trim())
.filter((l) => l.length > 0 && !l.startsWith("#"));
if (bodyLines.length === 0 || (bodyLines.length === 1 && bodyLines[0] === "pass")) {
passOnlyFns.push(name);
}
}
const stateRegex = /^[ \t]*([A-Za-z_][A-Za-z0-9_]*)\s*(?::[^=]+)?=\s*(?:\{|\[|dict\()/gm;
let sm: RegExpExecArray | null;
while ((sm = stateRegex.exec(strippedSource)) !== null) {
const varName = sm[1]!;
if (!stateVars.includes(varName)) stateVars.push(varName);
}
// Strip dead `if False:` / `if 0:` lines before checking call reachability
const liveCode = strippedSource.replace(
/^[ \t]*if\s+(?:False|0|1\s*==\s*2)\s*:\s*\n(?:[ \t]+.*\n?)*/gm,
"",
);
// Build intra-file call graph across defs in liveCode
const calledFns = new Set<string>();
const callingFns = new Set<string>();
for (const [caller, body] of fnBodies.entries()) {
const liveBody = body.replace(
/^[ \t]*if\s+(?:False|0|1\s*==\s*2)\s*:\s*\n(?:[ \t]+.*\n?)*/gm,
"",
);
for (const callee of fnNames) {
if (callee === caller) continue;
if (new RegExp(`\\b${callee}\\s*\\(`).test(liveBody)) {
calledFns.add(callee);
callingFns.add(caller);
}
}
}
// Also check module top-level calls (outside def headers)
for (const fn of fnNames) {
const matches = liveCode.match(new RegExp(`\\b${fn}\\s*\\(`, "g"));
if (matches && matches.length >= 2) {
calledFns.add(fn);
}
}
// Entry defs are public defs that call helpers (or the last public def if none call yet)
const entryFns = fnNames.filter(
(n) => !n.startsWith("_") && (callingFns.has(n) || !calledFns.has(n)),
);
const reachable = new Set<string>();
for (const fn of fnNames) {
if (callingFns.has(fn) || calledFns.has(fn)) {
reachable.add(fn);
}
}
const unreferenced = fnNames.filter((f) => !reachable.has(f));
const bannerMatch = source.match(FORBIDDEN_BANNER_REGEX);
const scareFns = fnNames.filter((f) => hasScareStem(f));
const scareRatio = fnNames.length > 0 ? scareFns.length / fnNames.length : 0;
const hasConditional = /\bif\s+/.test(strippedSource);
const hasLiteralFalse = /\bif\s+(?:False|0|1\s*==\s*2)\s*:/.test(strippedSource);
// Verify that shared state containers are actually touched inside >= 2 function bodies
// (or >= 1 customer def when python-customer-def-weave / warm-init is active)
const fnsTouchingState = new Set<string>();
for (const [fn, body] of fnBodies.entries()) {
for (const sv of stateVars) {
if (new RegExp(`\\b${sv}\\b`).test(body)) {
fnsTouchingState.add(fn);
}
}
if (/\["epoch"\]|\["warm"\]/.test(body)) {
fnsTouchingState.add(fn);
}
}
const isPostProtectWeave =
inspectWeaveHints(source, "python-source").hints.includes(
"python-customer-def-weave",
);
const statePassed =
(stateVars.length > 0 && fnsTouchingState.size >= 2) ||
(isPostProtectWeave && fnsTouchingState.size >= 1);
const checks: WeaveCheckResult[] = [
{
id: "no-forbidden-markers",
titleZh: "无禁止标记",
passed: bannerMatch === null,
evidence:
bannerMatch === null
? "0 forbidden markers"
: `Found '${bannerMatch[0]}'`,
},
{
id: "mixed-stems",
titleZh: "词干混用",
passed: fnNames.length > 0 && scareRatio <= 0.5,
evidence: `${fnNames.length - scareFns.length}/${fnNames.length} mundane defs`,
},
{
id: "shared-state-mutation",
titleZh: "共享状态变异",
passed: statePassed,
evidence:
statePassed
? `Shared state containers [${stateVars.join(", ")}] touched across ${fnsTouchingState.size} def(s)`
: `Shared state containers [${stateVars.join(", ") || "none"}] touched in only ${fnsTouchingState.size} def(s) (requires >= 2)`,
},
{
id: "customer-entry-edges",
titleZh: "客户入口边",
passed: reachable.size >= 2 && unreferenced.length === 0,
evidence: `Reachable defs: ${reachable.size}/${fnNames.length}`,
},
{
id: "opaque-true-entanglement",
titleZh: "不透明真缠绕",
passed: hasConditional && !hasLiteralFalse,
evidence: hasConditional
? "Conditional invariant present"
: "No conditional guard found",
},
{
id: "filter-resistance",
titleZh: "抗「独立层」过滤",
passed:
passOnlyFns.length === 0 &&
unreferenced.length === 0 &&
bannerMatch === null,
evidence:
passOnlyFns.length === 0
? "0 pass-only stubs"
: `pass-only stubs: ${passOnlyFns.join(", ")}`,
},
];
for (const c of checks) {
if (!c.passed) {
actions.push({
priority: "high",
file: relPath,
checkId: c.id,
instruction: `Fix failed weave check '${c.id}' (${c.evidence}) in ${relPath}, or run bla_harden with weave_decoys:true.`,
verifyTool: "bla_verify_weave",
});
}
}
const passedCount = checks.filter((c) => c.passed).length;
return {
fileReport: {
path: absPath,
relativePath: relPath,
format: "python-source",
passed: passedCount === checks.length,
score: Math.round((passedCount / checks.length) * 100),
checks,
discoveredFunctions: fnNames,
reachableFunctions: [...reachable],
unreferencedFunctions: unreferenced,
sharedStateVars: stateVars,
},
actions,
};
}
export function verifyWeaveTarget(
targetPath: string,
options: { readonly maxTargets?: number } = {},
): WeaveVerificationReport {
const abs = resolve(targetPath);
if (!existsSync(abs)) {
throw new Error(`verify-weave target not found: ${abs}`);
}
const maxTargets = options.maxTargets ?? 48;
const st = statSync(abs);
const candidateFiles = st.isDirectory()
? listCandidateFiles(abs, maxTargets)
: [abs];
const rootAbs = st.isDirectory() ? abs : resolve(abs, "..");
const fileReports: WeaveFileVerification[] = [];
const allActions: WeaveAgentAction[] = [];
for (const file of candidateFiles) {
const format = detectArtifactFormat(file);
const relPath = relative(rootAbs, file) || basename(file);
if (
format === "javascript" ||
format === "typescript" ||
format === "html-bundle"
) {
const src = readFileSync(file, "utf8");
const { fileReport, actions } = verifyJsWeaveFile(
file,
relPath,
format,
src,
);
fileReports.push(fileReport);
allActions.push(...actions);
} else if (format === "python-source") {
const src = readFileSync(file, "utf8");
const { fileReport, actions } = verifyPythonWeaveFile(file, relPath, src);
fileReports.push(fileReport);
allActions.push(...actions);
}
}
const overallPassed =
fileReports.length > 0 && fileReports.every((f) => f.passed);
const weaveScore =
fileReports.length > 0
? Math.round(
fileReports.reduce((acc, f) => acc + f.score, 0) / fileReports.length,
)
: 0;
const summary =
fileReports.length === 0
? "No JS/TS/Python source files found to verify weave entanglement."
: overallPassed
? `All ${fileReports.length} file(s) passed structural weave verification (weaveScore: ${weaveScore}/100). Ready for bla_harden.`
: `${fileReports.filter((f) => !f.passed).length}/${fileReports.length} file(s) need structural weave adjustments (weaveScore: ${weaveScore}/100). Follow the ${allActions.length} agentActions and re-run bla_verify_weave.`;
return {
schema: WEAVE_VERIFY_SCHEMA,
targetPath: abs,
verifiedAtIso: new Date().toISOString(),
overallPassed,
weaveScore,
files: fileReports,
agentActions: allActions,
summary,
};
}