@atmem/architect 0.0.0-stage → 0.2.0

package/src/records.mjs

@@ -0,0 +1,177 @@
+// Project records beside the diagram: requirements, assumptions, open questions,
+// and decisions with supersession history. See specs/002-project-model.
+import { sha256 } from '@noble/hashes/sha2.js';
+
+export const REQUIREMENT_KINDS = ["functional", "nonfunctional"];
+export const CATEGORIES = [
+  "security",
+  "reliability",
+  "availability",
+  "scalability",
+  "performance",
+  "maintainability",
+  "cost",
+  "compliance",
+  "other",
+];
+export const PRIORITIES = ["must", "should", "could"];
+export const REQUIREMENT_STATUSES = ["open", "met", "at-risk", "not-met"];
+export const SOURCES = ["user", "agent", "import"];
+export const OPS = [">=", "<=", "=="];
+
+const text = (value, max = 2000) => {const result=String(value??"");if(result.length>max)throw Error(`A project record exceeds ${max.toLocaleString('en')} characters; split it into linked records. No content was truncated.`);return result;};
+const pick = (value, allowed, fallback) => (allowed.includes(value) ? value : fallback);
+const links = (value) => {if(Array.isArray(value)&&value.length>50)throw Error("A record links more than 50 components; no links were truncated.");return Array.isArray(value)?value.map(id=>text(id,100)).filter(Boolean):[];};
+const today = () => new Date().toLocaleDateString("en-CA");
+const day = (value) => (/^\d{4}-\d{2}-\d{2}$/.test(value) ? value : today());
+const uid = (prefix) => `${prefix}-${crypto.randomUUID().slice(0, 8)}`;
+
+// A measure needs a numeric target when compared with >= or <=.
+export function measureProblem(measure) {
+  if (!measure) return null;
+  if (!text(measure.metric).trim()) return "Name the metric.";
+  if (!OPS.includes(measure.op)) return "Choose >=, <= or ==.";
+  if (measure.op !== "==" && (typeof measure.target !== "number" || !Number.isFinite(measure.target)))
+    return "Use a number for >= and <= targets.";
+  return null;
+}
+
+function cleanMeasure(m) {
+  if (!m || typeof m !== "object") return null;
+  const target =
+    typeof m.target === "number" && Number.isFinite(m.target)
+      ? m.target
+      : typeof m.target === "boolean"
+        ? m.target
+        : text(m.target, 100);
+  const measure = { metric: text(m.metric, 150), op: m.op, target, unit: text(m.unit, 40) };
+  return measureProblem(measure) ? null : measure;
+}
+
+export function cleanRequirement(r) {
+  const measure = cleanMeasure(r?.measure);
+  return {
+    id: text(r?.id || uid("req"), 60),
+    kind: pick(r?.kind, REQUIREMENT_KINDS, "functional"),
+    category: pick(r?.category, CATEGORIES, "other"),
+    statement: text(r?.statement, 1000),
+    ...(r?.rationale ? {rationale:text(r.rationale,1000)} : {}),
+    ...(r?.basis ? {basis:text(r.basis,1000)} : {}),
+    priority: pick(r?.priority, PRIORITIES, "should"),
+    status: pick(r?.status, REQUIREMENT_STATUSES, "open"),
+    source: pick(r?.source, SOURCES, "user"),
+    links: links(r?.links),
+    ...(measure ? { measure } : {}),
+  };
+}
+
+export function cleanAssumption(a) {
+  return {
+    id: text(a?.id || uid("asm"), 60),
+    statement: text(a?.statement, 1000),
+    source: pick(a?.source, SOURCES, "user"),
+    owner: text(a?.owner, 120),
+    links: links(a?.links),
+    madeAt: day(a?.madeAt),
+  };
+}
+
+export function cleanQuestion(q) {
+  return {
+    id: text(q?.id || uid("q"), 60),
+    question: text(q?.question, 1000),
+    owner: text(q?.owner, 120),
+    status: q?.status === "answered" ? "answered" : "open",
+    answer: text(q?.answer, 2000),
+    links: links(q?.links),
+  };
+}
+
+export const newRequirement = (fields = {}) => cleanRequirement({ kind: "nonfunctional", category: "performance", ...fields });
+export const newAssumption = (fields = {}) => cleanAssumption(fields);
+export const newQuestion = (fields = {}) => cleanQuestion(fields);
+
+// Records that point at components no longer on the canvas.
+export function missingLinks(project, record) {
+  const ids = new Set(project.nodes.map((n) => n.id));
+  return record.links.filter((id) => !ids.has(id));
+}
+
+export function linkedTo(project, componentId) {
+  const has = (r) => r.links.includes(componentId);
+  return {
+    needs: (project.needs || []).filter(has),
+    assumptions: (project.assumptions || []).filter(has),
+    questions: (project.openQuestions || []).filter(has),
+  };
+}
+
+// ---- Decisions ----
+
+export const slugSubject = (title) => {
+  const full = String(title ?? "");
+  const slug = full
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "") || "general";
+  if (slug.length <= 80) return slug;
+  // This is a derived lookup key, not the decision title. Bind the suffix to
+  // the whole title so proposals sharing a long prefix keep distinct histories.
+  const digest = Array.from(sha256(new TextEncoder().encode(full)), byte =>
+    byte.toString(16).padStart(2, "0")).join("").slice(0, 16);
+  return `${slug.slice(0, 63).replace(/-+$/, "")}-${digest}`;
+};
+
+function nextDecisionId(decisions) {
+  const max = Math.max(0, ...decisions.map((d) => Number(/^adr-(\d+)$/.exec(d.id)?.[1] || 0)));
+  return `adr-${String(max + 1).padStart(3, "0")}`;
+}
+
+// Revise a decision: a new record becomes current, the old one is superseded and kept.
+export function reviseDecision(project, id, changes, reason, revision = project.revision) {
+  const decisions = project.decisions || [];
+  const old = decisions.find((d) => d.id === id);
+  if (!old) throw Error("Decision not found.");
+  if (old.status === "Superseded") throw Error("This decision is already superseded; revise the current one.");
+  if (!text(reason).trim()) throw Error("Give a reason for the change.");
+  const next = {
+    ...old,
+    ...changes,
+    id: nextDecisionId(decisions),
+    subject: old.subject,
+    status: "Accepted",
+    date: today(),
+    revision,
+    supersedes: old.id,
+    supersededBy: null,
+    reason: text(reason),
+  };
+  return {
+    ...project,
+    decisions: [
+      ...decisions.map((d) => (d.id === old.id ? { ...d, status: "Superseded", supersededBy: next.id } : d)),
+      next,
+    ],
+  };
+}
+
+export function currentDecision(decisions = [], subject) {
+  const live = decisions.filter((d) => d.subject === subject && d.status !== "Superseded");
+  return live.at(-1) || null;
+}
+
+// Oldest first, ending with the current decision.
+export function decisionHistory(decisions = [], subject) {
+  const current = currentDecision(decisions, subject);
+  if (!current) return [];
+  const byId = new Map(decisions.map((d) => [d.id, d]));
+  const chain = [current];
+  const seen = new Set([current.id]);
+  let at = current;
+  while (at.supersedes && byId.has(at.supersedes) && !seen.has(at.supersedes)) {
+    at = byId.get(at.supersedes);
+    seen.add(at.id);
+    chain.unshift(at);
+  }
+  return chain;
+}

package/src/resources.mjs

@@ -0,0 +1,163 @@
+import {approvalProfiles} from './approval-applications.mjs';
+import {declaredRegion} from './deployment-region.mjs';
+import {containerRuntime} from './container-runtime.mjs';
+import {resourceAddress,assertDistinctIdentifiers} from './identifiers.mjs';
+import {capabilityCompositionPlan} from './delivery-capabilities.mjs';
+import {hasInvoice,invoiceResourcePlan}from'./invoice-plan.mjs';
+import {publicFaqPlan} from './public-faq.mjs';
+import {ibmStructuredPlan} from './ibm-structured.mjs';
+import {structuredApiPlan} from './structured-api.mjs';
+import {azureStructuredPlan} from './azure-structured.mjs';
+import {gcpStructuredPlan} from './gcp-structured.mjs';
+import {existingDeployment} from './deployment-ownership.mjs';
+import {externalIdentity,validateExternalReferences} from './external-identities.mjs';
+import {hasContainers,containerContract} from './container-contracts.mjs';
+import {existingReference} from './existing-references.mjs';
+import {hasCrossCloud,crossCloudPlan} from './cross-cloud-storage.mjs';
+import {webPlan} from './rag-web.mjs';
+import {sourceContractPlan} from './source-contracts.mjs';
+import {ragPlan} from './bounded-rag.mjs';
+import {summaryPlan} from './bedrock-summary.mjs';
+import { asyncPipelinePlan } from './async-documents.mjs';
+import { runtimeSettings } from "./runtime-settings.mjs";
+// A schedule of the diagram's intent, not discovered cloud inventory.
+import { storageAccessPlan } from "./s3-access.mjs";
+import { roleOf } from "./review.mjs";
+
+const SERVICES = [
+  [/\bcloudfront\b/i, "Amazon CloudFront", ["aws_cloudfront_distribution"], "Requests, transfer and private static assets"],
+  [/\bcognito\b/i, "Amazon Cognito", ["aws_cognito_user_pool"], "Active users and authentication features"],
+  [/\bapi\s*gateway\b/i, "Amazon API Gateway", ["aws_apigatewayv2_api"], "API requests, transfer and access logs"],
+  [/\bs3\b/i, "Amazon S3", ["aws_s3_bucket", "aws_s3_bucket_public_access_block", "aws_s3_bucket_server_side_encryption_configuration", "aws_s3_bucket_versioning", "aws_s3_bucket_ownership_controls", "aws_s3_bucket_policy"], "Storage, requests, retrieval and transfer"],
+  [/bedrock.*guard|guard.*bedrock/i, "Amazon Bedrock Guardrails", ["aws_bedrock_guardrail"], "Enabled policy checks and text units; confirm each policy's charge"],
+  [/bedrock.*knowledge|knowledge.*bedrock/i, "Amazon Bedrock Knowledge Bases", ["aws_bedrockagent_knowledge_base", "aws_iam_role"], "Embeddings, ingestion, vector store and retrieval; select the backing store"],
+  [/\bbedrock\b/i, "Amazon Bedrock", [], "Model-specific input/output tokens; guardrails, embeddings and knowledge bases separately"],
+  [/\blambda\b/i, "AWS Lambda", ["aws_lambda_function", "aws_iam_role"], "Requests, duration, memory and logs"],
+  [/\bopensearch\b/i, "Amazon OpenSearch", [], "Deployment mode, indexing/search capacity and storage"],
+  [/\bapp\s*runner\b/i, "AWS App Runner", ["aws_apprunner_service"], "Provisioned and active compute, builds, logs and transfer"],
+  [/\b(ecs|fargate)\b/i, "Amazon ECS", ["aws_ecs_service", "aws_ecs_task_definition"], "Compute, load balancing, networking, images and logs"],
+  [/\bdynamodb\b/i, "Amazon DynamoDB", ["aws_dynamodb_table"], "Read/write requests, storage and backup"],
+  [/\bsqs\b/i, "Amazon SQS", ["aws_sqs_queue"], "Requests, payload size and transfer"],
+  [/\bsagemaker\b/i, "Amazon SageMaker AI", [], "Training, serving instances, processing and storage"],
+  [/\b(iot|kinesis)\b/i, "AWS ingestion service", [], "Messages, connections, processing and retention"],
+  [/\bcloudtrail\b/i, "AWS CloudTrail", ["aws_cloudtrail"], "Management/data events, delivery, retention and query costs"],
+  [/\bcloudwatch\b/i, "Amazon CloudWatch", ["aws_cloudwatch_log_group"], "Logs, metrics, alarms and retention"],
+  [/\biam\b/i, "AWS IAM", ["aws_iam_policy"], "Review associated services; IAM policy alone is not an application guardrail"],
+];
+const CANDIDATES = { data: "Storage or existing data connector", ingest: "Ingestion / processing service", index: "Search / vector index", llm: "Model API and model selection", guard: "Guardrails and access policies", human: "Approval workflow", app: "Application runtime and API", output: "User interface / delivery integration", model: "Model training or serving", monitor: "Monitoring and alerting" };
+
+// Explicit selections are authoritative; labels are only candidates, never a way to
+// override an unsupported or conflicting selection. Generic names retain open modes.
+export function resolveService(data) {
+  if(data.implementation==='approval-workflow')return null;
+  if (data.provider !== "aws") return null;
+  const value = String(data.service || data.label || "");
+  if (/bedrock/i.test(value) && /\b(model|inference|invoke)\b/i.test(value) && /(guardrail|knowledge)/i.test(value) && /\bwith\b|[+&]/i.test(value)) return { ambiguous: true, selected: !!data.service };
+  let matches = SERVICES.filter(([re]) => re.test(value));
+  if (/bedrock.*(guard|knowledge)|(guard|knowledge).*bedrock/i.test(value)) matches = matches.filter(([,name]) => name !== "Amazon Bedrock");
+  if (matches.length !== 1) return { ambiguous: matches.length > 1, selected: !!data.service };
+  let [, name, resources, costs] = matches[0];
+  if (name === "Amazon OpenSearch") {
+    if (/serverless/i.test(value)) { name = "Amazon OpenSearch Serverless"; resources = ["aws_opensearchserverless_collection"]; }
+    else if (/\b(domain|provisioned|managed cluster)\b/i.test(value)) { name = "Amazon OpenSearch domain"; resources = ["aws_opensearch_domain"]; }
+  }
+  return { name, resources, costs, selected: !!data.service };
+}
+
+export function resourcePlan(project) {
+  approvalProfiles(project);
+  validateExternalReferences(project);
+ assertDistinctIdentifiers(project.nodes.map(n=>n.id));
+ return capabilityCompositionPlan(project,standaloneResourcePlan)||standaloneResourcePlan(project);
+}
+function standaloneResourcePlan(project) {
+  validateExternalReferences(project);
+  if(hasInvoice(project))return invoiceResourcePlan(project);
+  if(hasCrossCloud(project))return crossCloudPlan(project);
+  const nodes = project.nodes.filter((n) => n.data.kind !== "note");
+  const ids = new Set(nodes.map((n) => n.id));
+  const rows = nodes.map((n) => {
+    const match = resolveService(n.data);
+    const existing = existingDeployment(n);
+    const foundation = !existing && n.data.provider === "aws" && match?.name === "Amazon S3";
+    const compute=!existing && n.data.provider==="aws" && match?.name==="AWS Lambda" && n.data.implementation==="text-statistics";
+    // Encode the complete ID: stable on reorder/rename, valid Terraform identifier, no collisions.
+    const address = resourceAddress(n.id);
+    return { id: n.id, address, label: n.data.label, provider: n.data.provider,
+      service: match?.name || n.data.service || CANDIDATES[roleOf(n)] || "Service to be selected",
+      sourceExisting:n.data.origin === "existing", selection: match?.ambiguous ? "Ambiguous service names" : match?.name ? (match.selected ? "Explicit service field; deployment review required" : "Named in diagram") : "Needs service confirmation", existing,
+      region: n.data.config?.region || "To be selected", resources: match?.resources || [],
+      costDrivers: match?.costs || "Confirm service, capacity and billable dimensions",
+      dependencies: project.edges.filter((e) => e.target === n.id && ids.has(e.source)).map((e) => e.source),
+      terraform: existing ? "Existing — reference/import plan needed" : foundation ? "S3 foundation generated" : "Implementation needed",
+      foundation, compute, api:!existing&&match?.name==="Amazon API Gateway"&&n.data.implementation==="iam-rag-api", structured:n.data.implementation==="bedrock-structured", summary:!existing&&n.data.provider==="aws"&&match?.name==="AWS Lambda"&&(n.data.implementation==="bedrock-summary"||(n.data.implementation==="bedrock-structured"&&n.data.config?.outputContract)), settings: runtimeSettings(n.data.config),
+    };
+  });
+  const asyncPlan=asyncPipelinePlan(project,rows);
+  const modelPlan=summaryPlan(project,rows);
+  const retrievalPlan=ragPlan(project,rows);
+  const structuredPlan=structuredApiPlan(project,rows,modelPlan);
+  const connectorPlan=sourceContractPlan(project,rows,retrievalPlan);
+  const browserPlan=webPlan(project,rows,{entries:[...retrievalPlan.entries,...structuredPlan.entries]});
+  const accessPlan=storageAccessPlan(project,rows);
+  const azurePlan=azureStructuredPlan(project,rows);
+  const googlePlan=gcpStructuredPlan(project,rows);
+  const ibmPlan=ibmStructuredPlan(project,rows);
+  const faqPlan=publicFaqPlan(project,rows);
+  for(const row of rows){
+    row.reference=accessPlan.bindings.some(b=>b.id===row.id);
+    row.externalReference=row.existing && row.provider==="tools" && nodes.find(n=>n.id===row.id)?.data.binding==="web-browser";
+    row.existingServiceReference=existingReference(nodes.find(n=>n.id===row.id),externalIdentity(project,row.id));
+    row.containerContract=containerContract(nodes.find(n=>n.id===row.id));
+    row.implemented=faqPlan.editorIds.includes(row.id)||faqPlan.componentIds.includes(row.id)||ibmPlan.componentIds.includes(row.id)||googlePlan.componentIds.includes(row.id)||azurePlan.componentIds.includes(row.id)||(structuredPlan.entries.some(e=>e.api.id===row.id)&&browserPlan.entries.some(e=>e.api.id===row.id))||!!row.containerContract||!!row.existingServiceReference||row.externalReference||row.foundation||row.compute||row.reference||browserPlan.componentIds.includes(row.id)||connectorPlan.sources.some(s=>s.id===row.id)||retrievalPlan.componentIds.includes(row.id)||modelPlan.modelIds.includes(row.id)||modelPlan.entries.some(e=>e.worker.id===row.id)||asyncPlan.componentIds.includes(row.id);
+    if(faqPlan.componentIds.includes(row.id)){row.costDrivers='Compute and HTTP requests, model input/output tokens, catalog read/write/versioned storage, logs and transfer; verify current regional service/model prices and quotas. Capacity limits are not invoice caps.';row.resources={aws:['aws_lambda_function','aws_apigatewayv2_api','aws_s3_bucket','aws_iam_role'],azure:['azurerm_linux_web_app','azurerm_storage_account','azurerm_storage_container'],gcp:['google_cloud_run_v2_service','google_storage_bucket','google_service_account'],ibm:['ibm_code_engine_app','ibm_cos_bucket','ibm_iam_trusted_profile']}[row.provider];row.terraform='Public-only cited FAQ source, browser, private catalog, separate editor/runtime roles and regional model transport generated; destination behavior unverified';}
+    if(azurePlan.componentIds.includes(row.id)){row.resources=['azurerm_linux_web_app','azurerm_service_plan','azurerm_cognitive_account','azurerm_cognitive_deployment','azuread_application_registration'];row.terraform='Composed Azure structured application source, browser, Entra authorization and regional model deployment generated; destination behavior unverified';}
+    if(ibmPlan.componentIds.includes(row.id)){row.resources=['ibm_code_engine_app','ibm_resource_instance','ibm_appid_application','ibm_iam_trusted_profile','ibm_iam_trusted_profile_link'];row.terraform='Composed IBM structured application source, browser, App ID authorization and keyless regional model transport generated; destination behavior unverified';}
+    if(googlePlan.componentIds.includes(row.id)){row.resources=['google_cloud_run_v2_service','google_service_account','google_project_iam_custom_role','google_iap_web_cloud_run_service_iam_member'];row.terraform='Composed Google structured application source, browser, IAP identity and regional model transport generated; destination behavior unverified';}
+    if(asyncPlan.componentIds.includes(row.id))row.terraform="Typed asynchronous pipeline implementation generated";
+    if(modelPlan.modelIds.includes(row.id))row.terraform="Existing regional foundation model — required model ID input generated";
+    if(modelPlan.entries.some(e=>e.worker.id===row.id))row.terraform=row.structured?"Schema-checked structured generation handler, scoped model permission and caller binding generated":"Bedrock summary handler, scoped model permission and caller binding generated";
+    if(retrievalPlan.componentIds.includes(row.id))row.terraform="Bounded IAM-authenticated RAG implementation generated";
+    if(connectorPlan.sources.some(s=>s.id===row.id))row.terraform="Local source-contract runner generated; native vendor integration unverified";
+    if(browserPlan.componentIds.includes(row.id))row.terraform="Private web hosting and Cognito authorization-code/PKCE sign-in generated";
+    if(row.containerContract){row.service=row.containerContract.service;row.resources=[row.containerContract.type];row.terraform="Native private container footprint generated; supplied image and application behavior require validation";}
+    if(row.compute){row.terraform="Text-statistics function, execution role, logs, version and alias generated";row.resources=["aws_lambda_function","aws_iam_role","aws_iam_role_policy","aws_cloudwatch_log_group","aws_lambda_alias","aws_lambda_permission"];}
+    if(faqPlan.editorIds.includes(row.id)){row.resources=[];row.terraform='Existing public catalog editor — provider-native role/group input and separate conditional editor CLI generated; actual access unverified';}
+    if(row.externalReference)row.terraform="External browser — no infrastructure to provision; connection behavior still requires validation";
+    if(row.existingServiceReference){row.resources=[];row.terraform="Existing service reference — preserved without provisioning or import; behavior and connections remain unverified";}
+    if(row.reference){row.terraform="Existing IAM principal — required ARN input generated";row.service="Existing AWS IAM principal";row.selection="Explicit principal binding";}
+  }
+  if(hasContainers(project))for(const row of rows)if(!row.existing&&!row.containerContract){row.implemented=false;row.terraform="Container compiler composition does not implement this required component";}
+  if(faqPlan.entries.length)for(const row of rows)if(!row.existing&&!faqPlan.componentIds.includes(row.id)){row.implemented=false;row.terraform='Public FAQ composition does not yet implement this additional required component';}
+  const connections = project.edges.filter((e) => ids.has(e.source) && ids.has(e.target)).map((e) => ({ id: e.id, source: e.source, target: e.target, data: e.label || "data", generated: (faqPlan.edgeIds.includes(e.id)||ibmPlan.edgeIds.includes(e.id)||googlePlan.edgeIds.includes(e.id)||azurePlan.edgeIds.includes(e.id)||accessPlan.connections.some(c=>c.id===e.id)||asyncPlan.edgeIds.includes(e.id)||modelPlan.edgeIds.includes(e.id)||retrievalPlan.edgeIds.includes(e.id)||connectorPlan.connections.some(c=>c.id===e.id)||(browserPlan.edgeIds.includes(e.id)||structuredPlan.entries.some(x=>browserPlan.entries.some(w=>w.api.id===x.api.id)&&x.edges.some(y=>y.id===e.id)))), status: (faqPlan.edgeIds.includes(e.id)||ibmPlan.edgeIds.includes(e.id)||googlePlan.edgeIds.includes(e.id)||azurePlan.edgeIds.includes(e.id)||accessPlan.connections.some(c=>c.id===e.id)||asyncPlan.edgeIds.includes(e.id)||modelPlan.edgeIds.includes(e.id)||retrievalPlan.edgeIds.includes(e.id)||connectorPlan.connections.some(c=>c.id===e.id)||(browserPlan.edgeIds.includes(e.id)||structuredPlan.entries.some(x=>browserPlan.entries.some(w=>w.api.id===x.api.id)&&x.edges.some(y=>y.id===e.id)))) ? "Scoped access policy generated; account and runtime verification required" : "Application integration and permissions not implemented" }));
+  if(faqPlan.entries.length)for(const connection of connections)if(!faqPlan.edgeIds.includes(connection.id)){connection.generated=false;connection.status='Additional required integration is not implemented by this public FAQ composition';}
+  const missingStorageAccess=rows.filter(r=>(r.foundation||r.compute||r.summary||r.api)&&!accessPlan.connections.some(e=>e.target===r.id)&&!browserPlan.entries.some(e=>e.api.id===r.id||e.worker.id===r.id));
+  const containerSettingGaps=rows.filter(r=>r.containerContract).flatMap(row=>[...containerRuntime(nodes.find(n=>n.id===row.id)).gaps,...declaredRegion(nodes.find(n=>n.id===row.id)).gaps].map(g=>({id:`container-setting-${row.address}-${g.key}`,componentIds:[row.id],message:`${row.label}: explicit ${g.key}=${JSON.stringify(g.value)} ${g.reason}.`})));
+  const gaps = [
+    ...containerSettingGaps.map(g=>g.message),
+    ...missingStorageAccess.map(r=>`${r.label}: explicit caller access contract is missing.`),
+    ...rows.filter((r) => !r.implemented).map((r) => `${r.label}: ${r.terraform}.`),
+    ...connections.filter(e=>!e.generated).map((e) => `Wire ${e.source} → ${e.target}: implement data flow, access policy and acceptance test.`),
+    ...(!rows.length ? ["No resources in the design yet."] : []),
+  ];
+  const encode=value=>Array.from(new TextEncoder().encode(value),b=>b.toString(16).padStart(2,"0")).join("");
+  const gapDetails=[
+    ...containerSettingGaps,
+    ...missingStorageAccess.map(r=>({id:`access-${r.address}`,componentIds:[r.id],taskId:`TASK-RESOURCE-${encode(r.id)}`,message:`${r.label}: explicit caller access contract is missing.`})),
+    ...rows.filter(r=>!r.implemented).map(r=>({id:`resource-${r.address}`,componentIds:[r.id],taskId:`TASK-RESOURCE-${encode(r.id)}`,message:`${r.label}: ${r.terraform}.`})),
+    ...connections.filter(e=>!e.generated).map(e=>({id:`connection-${encode(e.id)}`,edgeIds:[e.id],taskId:`TASK-INTEGRATION-${encode(e.id)}`,message:`Wire ${e.source} → ${e.target}: implement data flow, access policy and acceptance test.`})),
+    ...(!rows.length?[{id:'architecture-empty',taskId:'TASK-SCOPE',message:'No resources in the design yet.'}]:[]),
+  ];
+  return { revision: project.revision, rows, connections, accessPlan, asyncPlan, publicFaqPlan:faqPlan, azureStructuredPlan:azurePlan, gcpStructuredPlan:googlePlan, ibmStructuredPlan:ibmPlan, summaryPlan:modelPlan, structuredApiPlan:structuredPlan, ragPlan:retrievalPlan, sourceContractPlan:connectorPlan, webPlan:browserPlan, gaps, gapDetails, scope: "Diagram-derived resource schedule; service choices and resource types require engineering review.", sources: [
+    "https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket",
+    "https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/bedrock_guardrail",
+    "https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/bedrockagent_knowledge_base",
+    "https://aws.amazon.com/bedrock/pricing/",
+  ] };
+}
+
+export function resourceMarkdown(project) {
+  const plan = resourcePlan(project);
+  const c = (v) => String(v ?? "").replaceAll("|", "\\|").replaceAll("\n", " ");
+  return `## Cloud resource schedule\n\n${plan.scope}\n\n| Block ID | Component | Provider | Service | Region | Ownership | Terraform coverage |\n|---|---|---|---|---|---|---|\n${plan.rows.map((r) => `| ${c(r.id)} | ${c(r.label)} | ${r.provider} | ${c(r.service)} | ${c(r.region)} | ${r.existing ? "Existing" : "Proposed"} | ${r.terraform} |`).join("\n")}\n\n### Resources and cost dimensions\n\n${plan.rows.map((r) => `- **${c(r.label)}** (${c(r.id)}): ${r.resources.join(", ") || "Resource types to confirm"}. ${r.costDrivers}. Depends on: ${r.dependencies.join(", ") || "none drawn"}.`).join("\n")}\n\n### Engineering work remaining\n\n${plan.gaps.map((g) => `- ${g}`).join("\n") || "Generated configuration remains unverified. Validate every delivery unit, interface, destination input, cost and security boundary before applying."}\n\nReferences (resource semantics; not retrieved prices):\n${plan.sources.map((s) => `- ${s}`).join("\n")}\n`;
+}

package/src/review.mjs

@@ -0,0 +1,252 @@
+// Architecture review: deterministic, provider-neutral rules over the project model.
+// See specs/003-architecture-review. Each finding names its rule, so it can be traced.
+
+export const RULES_VERSION = "1.0.0";
+export const ATTRIBUTES = [
+  ["security", "Security & controls"],
+  ["reliability", "Reliability"],
+  ["availability", "Availability"],
+  ["scalability", "Scalability"],
+  ["performance", "Performance"],
+  ["maintainability", "Maintainability"],
+  ["cost", "Cost"],
+];
+export const SEVERITIES = ["blocker", "major", "minor", "info"];
+
+// What a block does, whether runnable (kind) or sketched (role).
+export function roleOf(n) {
+  const { kind, role } = n.data;
+  if (role) return role;
+  return (
+    { source: "data", stream: "data", history: "data", features: "ingest", train: "model", registry: "model", predict: "model", monitor: "monitor", agent: "llm", guard: "guard", tool: "app", output: "output" }[kind] || "other"
+  );
+}
+const isHuman = (n) => roleOf(n) === "human" || /\b(approv|human|review queue|person)\b/i.test(n.data.label);
+const isGuard = (n) => roleOf(n) === "guard" || isHuman(n);
+
+function downstream(p, id, seen = new Set()) {
+  for (const e of p.edges)
+    if (e.source === id && !seen.has(e.target)) {
+      seen.add(e.target);
+      downstream(p, e.target, seen);
+    }
+  return seen;
+}
+// Paths from `from` to any node matching `to` that avoid nodes matching `via`.
+function reachesAvoiding(p, from, to, via) {
+  const stack = [from],
+    seen = new Set([from]);
+  while (stack.length) {
+    const id = stack.pop();
+    for (const e of p.edges.filter((x) => x.source === id)) {
+      const n = p.nodes.find((x) => x.id === e.target);
+      if (!n || seen.has(n.id) || via(n)) continue;
+      if (to(n)) return true;
+      seen.add(n.id);
+      stack.push(n.id);
+    }
+  }
+  return false;
+}
+
+const hasNeed = (p, category, re) =>
+  (p.needs || []).some((r) => r.category === category && (!re || re.test(`${r.statement} ${r.measure?.metric || ""}`)));
+const fact = (p, name) => [...(p.facts || [])].reverse().find((f) => f.name === name);
+
+const RULES = [
+  {
+    id: "SEC-001",
+    attribute: "security",
+    severity: "blocker",
+    check(p) {
+      const llms = p.nodes.filter((n) => roleOf(n) === "llm");
+      const exits = (n) => ["app", "output"].includes(roleOf(n));
+      const open = llms.filter((n) => reachesAvoiding(p, n.id, exits, isGuard));
+      return open.map((n) => ({
+        statement: `${n.data.label} can reach users or systems without a guardrail or approval step.`,
+        rationale: "Generated content can be wrong, unsafe or leak data; it needs a check before it leaves the system.",
+        action: "Define and represent output validation or an approval control where needed; specify failure behavior and test it. Verify source authorization before retrieval and citation grounding separately: a guardrail block alone proves neither.",
+        components: [n.id],
+      }));
+    },
+  },
+  {
+    id: "SEC-002",
+    attribute: "security",
+    severity: "major",
+    check(p) {
+      const sensitive = p.nodes.filter((n) => n.data.config?.classification === "Confidential");
+      const flagged = fact(p, "data.sensitive")?.value === true;
+      if (!sensitive.length && !flagged) return [];
+      if (hasNeed(p, "compliance", /stay|resid|region|locat/i)) return [];
+      return [
+        {
+          statement: "Sensitive data is involved but where it must be stored is not stated.",
+          rationale: "Data residency rules decide which regions and services are allowed.",
+          action: "Add a compliance requirement such as “data stays in the EU”, and set regions on data blocks.",
+          components: sensitive.map((n) => n.id),
+        },
+      ];
+    },
+  },
+  {
+    id: "SEC-003",
+    attribute: "security",
+    severity: "major",
+    check(p) {
+      const actors = p.nodes.filter((n) => ["llm", "model"].includes(roleOf(n)));
+      // Systems that receive actions (integrations), not the interface people read.
+      const apps = p.nodes.filter((n) => roleOf(n) === "app" && (n.data.kind === "tool" || /integration/i.test(n.data.category || "")));
+      const unchecked = apps.filter((a) => actors.some((m) => downstream(p, m.id).has(a.id) && reachesAvoiding(p, m.id, (x) => x.id === a.id, isHuman)));
+      if (!unchecked.length || hasNeed(p, "security", /person|human|approv/i)) return [];
+      return [
+        {
+          statement: "Automated results reach other systems with no person approving them.",
+          rationale: "Actions taken on model output (orders, emails, records) need clear human accountability.",
+          action: "Add an approval step, or record a requirement that states which actions need approval.",
+          components: unchecked.map((n) => n.id),
+        },
+      ];
+    },
+  },
+  {
+    id: "REL-001",
+    attribute: "reliability",
+    severity: "major",
+    check(p) {
+      const models = p.nodes.filter((n) => ["llm", "model"].includes(roleOf(n)));
+      if (!models.length || p.nodes.some((n) => roleOf(n) === "monitor")) return [];
+      return [
+        {
+          statement: "No monitoring for model quality or drift.",
+          rationale: "Model answers and predictions degrade quietly; someone needs to see it happen.",
+          action: "Add a monitoring block (quality, drift, cost) and decide who is alerted.",
+          components: models.map((n) => n.id),
+        },
+      ];
+    },
+  },
+  {
+    id: "REL-002",
+    attribute: "reliability",
+    severity: "minor",
+    check(p) {
+      const apps = p.nodes.filter((n) => roleOf(n) === "app" && n.data.origin === "existing");
+      return apps.length
+        ? [
+            {
+              statement: "The design depends on existing systems; their failure behaviour is not described.",
+              rationale: "If an integration is down, requests may be lost or duplicated.",
+              action: "State what happens when each existing system is unavailable (retry, queue, fallback).",
+              components: apps.map((n) => n.id),
+            },
+          ]
+        : [];
+    },
+  },
+  {
+    id: "AVL-001",
+    attribute: "availability",
+    severity: "minor",
+    check: (p) =>
+      p.nodes.length && !hasNeed(p, "availability")
+        ? [{ statement: "No availability target.", rationale: "Without one, nobody can say whether a single region or a single endpoint is enough.", action: "Add a requirement such as “available 99.5% of the time” or “business hours only”.", components: [] }]
+        : [],
+  },
+  {
+    id: "PRF-001",
+    attribute: "performance",
+    severity: "minor",
+    check: (p) =>
+      p.nodes.some((n) => ["llm", "model"].includes(roleOf(n))) && !hasNeed(p, "performance")
+        ? [{ statement: "No response-time target.", rationale: "Model size, retrieval depth and region all trade speed against cost.", action: "Add a requirement such as “responds within 5 seconds”.", components: [] }]
+        : [],
+  },
+  {
+    id: "SCL-001",
+    attribute: "scalability",
+    severity: "info",
+    check: (p) =>
+      p.nodes.length && !fact(p, "requests.per_month") && !fact(p, "users")
+        ? [{ statement: "Expected usage is unknown, so scale can't be assessed.", rationale: "Usage drives capacity, limits and cost.", action: "Tell us in the chat roughly how many people use it and how often.", components: [] }]
+        : [],
+  },
+  {
+    id: "MNT-001",
+    attribute: "maintainability",
+    severity: "minor",
+    check: (p) => {
+      const loose = (p.needs || []).filter((r) => r.kind === "nonfunctional" && !r.measure);
+      return loose.length
+        ? [{ statement: `${loose.length} quality requirement${loose.length > 1 ? "s have" : " has"} no measurable target.`, rationale: "A target makes it testable and lets the review say met or not met.", action: `Add a metric and target to: ${loose.map((r) => `“${r.statement}”`).join(", ")}.`, components: [] }]
+        : [];
+    },
+  },
+  {
+    id: "MNT-002",
+    attribute: "maintainability",
+    severity: "minor",
+    check: (p) => {
+      const unowned = (p.decisions || []).filter((d) => d.status === "Accepted" && !d.owner?.trim());
+      return unowned.length
+        ? [{ statement: `${unowned.length} accepted decision${unowned.length > 1 ? "s have" : " has"} no owner.`, rationale: "Someone must be accountable for each choice before build.", action: "Assign an owner in Design → Decisions.", components: [] }]
+        : [];
+    },
+  },
+  {
+    id: "CST-001",
+    attribute: "cost",
+    severity: "info",
+    check: (p) =>
+      p.nodes.length && !fact(p, "budget.per_month") && !hasNeed(p, "cost")
+        ? [{ statement: "No budget stated.", rationale: "Without one, the estimate can't flag an option as too expensive.", action: "Mention a monthly running budget, or a range, in the chat.", components: [] }]
+        : [],
+  },
+  {
+    id: "DSN-001",
+    attribute: "maintainability",
+    severity: "info",
+    check: (p) => {
+      const sketch = p.nodes.filter((n) => n.data.kind === "resource");
+      return sketch.length
+        ? [{ statement: `${sketch.length} block${sketch.length > 1 ? "s are" : " is"} sketch-only and can't be test-run yet.`, rationale: "Sketch blocks describe intent; runnable fixtures exist only for some workflows.", action: "Keep designing; assign a runnable behaviour in block detail when one exists.", components: sketch.map((n) => n.id) }]
+        : [];
+    },
+  },
+];
+
+const keyOf = (rule, components) => `${rule}:${[...components].sort().join(",")}`;
+
+// Findings are recomputed from current data; accepted risks persist by rule + components.
+export function review(full) {
+  const notes = new Set(full.nodes.filter((n) => n.data.kind === "note").map((n) => n.id));
+  const project = { ...full, nodes: full.nodes.filter((n) => !notes.has(n.id)), edges: full.edges.filter((e) => !notes.has(e.source) && !notes.has(e.target)) };
+  const accepted = project.reviewAccepted || {};
+  return RULES.flatMap((rule) =>
+    rule.check(project).map((f, i) => {
+      const key = keyOf(rule.id, f.components);
+      return {
+        id: `${rule.id}-${i + 1}`,
+        key,
+        rule: rule.id,
+        version: RULES_VERSION,
+        attribute: rule.attribute,
+        severity: rule.severity,
+        ...f,
+        source: `AtMem AI Architect rule ${rule.id} v${RULES_VERSION}`,
+        status: accepted[key] ? "accepted" : "open",
+        ...(accepted[key] ? { acceptance: accepted[key] } : {}),
+      };
+    }),
+  );
+}
+
+export function acceptRisk(project, finding, reason, owner) {
+  if (!String(reason || "").trim() || !String(owner || "").trim()) throw Error("Accepting a risk needs a reason and an owner.");
+  return {
+    ...project,
+    reviewAccepted: { ...(project.reviewAccepted || {}), [finding.key]: { reason, owner, date: new Date().toLocaleDateString("en-CA") } },
+  };
+}
+
+export const blockers = (findings) => findings.filter((f) => f.severity === "blocker" && f.status === "open");