archgraph-argo 0.27.0 → 0.28.0

package/argo/scripts/argo-mcp-server.js

@@ -14,11 +14,16 @@ const {
 } = require('./repositoryArgoEnvironment.js');
 const {
   loadSchemaBundleAndOntology,
-} = require('./argob-schema.js');
+} = require('./schema-bundle.js');
 const {
   externalQueryRequested,
   queryExternalRead,
 } = require('./external-graph-query.js');
+const {
+  authorizeWorkspaceWrite,
+  isWriteTool,
+  stripTrustedSessionField,
+} = require('./workspace-write-guard.js');
 const {
   getWorkspaceRoot,
   hasStaticWorkspace,
@@ -134,7 +139,7 @@ const TOOLS = [
   },
   {
     name: 'getIntentElementContext',
-    description: 'read-only query that returns an intent subgraph context for one element. Uses ArchiMate semantic dependency traversal with dependencyDepth and dependentDepth, preserving native subgraph elements, relationships, and views.',
+    description: 'read-only query that returns an intent subgraph context for one element. Uses ArchiMate semantic dependency traversal with dependencyDepth and dependentDepth, preserving native subgraph elements, relationships, and views. Output is bounded by maxBytes (default ARGO_CONTEXT_MAX_BYTES or 32000): beyond it non-focus members degrade to identity (id/type/name) with a complete id manifest under truncation, so the host never silently cuts the payload. On a large/hub element leave includeAttributes/includeTestcases off and prefer queryNeo4jGraph to locate ids, then read them narrowly.',
     inputSchema: intentElementContextInputSchema(),
   },
   {
@@ -149,12 +154,18 @@ const TOOLS = [
   },
   {
     name: 'addArchitectureElement',
-    description: 'Use for one element. Creates a new element or adds an existing element to view_ids. view_ids is required so elements never exist outside views.',
+    description: 'Use for one element. Creates a new element or adds an existing element to view_ids. view_ids is required so elements never exist outside views. element.id is OPTIONAL: omit it and the server auto-allocates a unique id (returned in the result); provide it to pin a specific id (must not collide with a different element).',
     inputSchema: {
       type: 'object',
       required: ['element', 'view_ids'],
       properties: {
-        element: { type: 'object' },
+        element: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: 'Element id (OPTIONAL). Omit to let the server auto-allocate a unique id (a semantic slug from the name, e.g. "graph-wiki-federation-center", suffixed -002.. if taken). If provided it must not collide with a DIFFERENT element (a same (type,name) match is idempotent reuse).' },
+          },
+          description: 'The element to create/attach. `id` is optional — omit it and the server allocates one (returned in the result).',
+        },
         view_ids: { type: 'array', minItems: 1, items: { type: 'string' } },
         onConflict: { type: 'string', enum: ['reuse', 'allowDuplicate'], description: 'Dedup policy (default reuse). reuse: find-or-create — attach an existing exact (type, name) match; a same-type semantic near-duplicate also blocks creation. allowDuplicate: create anyway (even if a duplicate exists), requires a justification.' },
         justification: { type: 'string', description: 'Required when onConflict is allowDuplicate.' },
@@ -193,7 +204,7 @@ const TOOLS = [
   },
   {
     name: 'addArchitectureRelationship',
-    description: 'Use for one relationship. Creates a new relationship or adds an existing relationship to view_ids. relationship.type is the ArchiMate 3.2 relationship type and is validated against endpoint element types.',
+    description: 'Use for one relationship. Creates a new relationship or adds an existing relationship to view_ids. relationship.type is the ArchiMate 3.2 relationship type and is validated against endpoint element types. relationship.id is OPTIONAL: omit it and the server auto-allocates a unique id (returned in the result).',
     inputSchema: {
       type: 'object',
       required: ['relationship', 'view_ids'],
@@ -237,7 +248,7 @@ const TOOLS = [
   },
   {
     name: 'addArchitectureView',
-    description: 'Use for one view. The graph must have exactly one top-level view named SystemArchitecture; all sub-views must attach to an element with parent_element_id.',
+    description: 'Use for one view. The graph must have exactly one top-level view named SystemArchitecture; all sub-views must attach to an element with parent_element_id. view.view_id is OPTIONAL: omit it and the server auto-allocates a unique view_id (returned in the result).',
     inputSchema: {
       type: 'object',
       required: ['view'],
@@ -337,8 +348,9 @@ function intentElementContextInputSchema() {
       dependentDepth: { type: 'number', description: 'Default: 1. Semantic dependents that rely on the focus element.' },
       associationDepth: { type: 'number', description: 'Default: 1. Association neighbors are expanded at least one layer.' },
       associationNeighborDependencyDepth: { type: 'number', description: 'Default: 0. Optional dependency expansion from association neighbors.' },
-      includeAttributes: { type: 'boolean', description: 'Default: false. Include `attributes` (commit/session/release ledgers) verbatim; omitted by default from this structural read (the focus element always keeps its own).' },
-      includeTestcases: { type: 'boolean', description: 'Default: false. Include member `testcases` verbatim; omitted by default from this structural read.' },
+      includeAttributes: { type: 'boolean', description: 'Default: false. Include `attributes` (commit/session/release ledgers) verbatim; omitted by default from this structural read (the focus element always keeps its own). On a hub element this ledger can dominate the payload.' },
+      includeTestcases: { type: 'boolean', description: 'Default: false. Include member `testcases` verbatim; omitted by default from this structural read. On a hub element this can be large.' },
+      maxBytes: { type: 'number', description: 'Optional output budget in UTF-8 bytes. Default: ARGO_CONTEXT_MAX_BYTES env or 32000. 0 = unlimited. Above the budget, non-focus members degrade to identity (id/type/name) with a complete id manifest under `truncation`; the payload is never silently truncated by the host.' },
     },
     additionalProperties: false,
   };
@@ -404,6 +416,33 @@ function resolveWorkspaceRoot(args) {
 }
 
 async function callTool(name, args = {}, progressToken = null, dependencies = undefined) {
+  // Cross-project WRITE guard (single choke point for every tool): a write tool
+  // may only target this server's HOME workspace, or a host-designated trusted
+  // session workspace when the process was launched by a trusted broker
+  // (ARGO_WORKSPACE_ROOT_TRUSTED=1). A foreign `workspaceRoot` is rejected
+  // fail-closed before any side effect; READ tools stay ungated so cross-project
+  // reading still works. See workspace-write-guard.js.
+  if (isWriteTool(name, args)) {
+    const decision = authorizeWorkspaceWrite({ tool: name, args, homeRoot: getWorkspaceRoot() });
+    if (!decision.allowed) {
+      return toolResult({
+        status: 'failed',
+        error: {
+          category: decision.category,
+          message: decision.message,
+          tool: decision.tool,
+          homeWorkspaceRoot: decision.homeWorkspaceRoot,
+          requestedWorkspaceRoot: decision.requestedWorkspaceRoot,
+          ...(decision.trustedSessionWorkspaceRoot
+            ? { trustedSessionWorkspaceRoot: decision.trustedSessionWorkspaceRoot }
+            : {}),
+        },
+      });
+    }
+  }
+  // The broker-only field is not part of any tool's schema: honor it above, then
+  // drop it before dispatch so schema validation never sees it.
+  args = stripTrustedSessionField(args);
   loadRepositoryArgoEnvironment(resolveWorkspaceRoot(args));
   try {
     const crash = require('./graph-rag/mcpCrashDiagnostics.js');
@@ -420,6 +459,13 @@ async function callTool(name, args = {}, progressToken = null, dependencies = un
       tool: name,
       args,
     });
+    // getSystemArchitecture declares an outputSchema, so its result MUST carry
+    // matching structuredContent even on the cross-project path (which bypasses
+    // the systemarchitecture module's own toolResult). A missing
+    // structuredContent makes the MCP client reject the call with -32600.
+    if (name === 'getSystemArchitecture') {
+      return toolResult(result, systemArchitectureMcp.buildGetSystemArchitectureStructuredContent(result));
+    }
     return toolResult(result);
   }
   if (name === 'initializeWorkspace') {
@@ -438,7 +484,7 @@ async function callTool(name, args = {}, progressToken = null, dependencies = un
     return toolResult({
       status: report.status,
       workspaceRoot: workspace.workspaceRoot,
-      // The resolved modeling language for this workspace (default ArgoBument vs
+      // The resolved modeling language for this workspace (default ArchiMate 3.2 vs
       // the repository's own .argo/schema bundle) so init names the active schema.
       schema: workspace.schema,
       schemaBundle: report.schemaBundle,
@@ -535,7 +581,7 @@ async function initializeWorkspace(workspaceRoot) {
   const graphTargetPath = path.join(workspaceRoot, ...WORKSPACE_GRAPH_PATH_SEGMENTS);
   const graphRelativePath = normalizeRelativePath(path.relative(workspaceRoot, graphTargetPath));
   if (!fs.existsSync(graphTargetPath)) {
-    // Only the built-in ArgoBument default schema auto-provides a graph (the
+    // Only the built-in ArchiMate 3.2 default schema auto-provides a graph (the
     // packaged default). For any custom / replaced schema the graph is the user's
     // own: never copy the packaged (mismatched) graph — fail closed if missing.
     let ontology = null;
@@ -590,7 +636,7 @@ async function initializeWorkspace(workspaceRoot) {
   } catch (error) {
     qeaFullProjection = { status: 'failed', error: String(error && error.message ? error.message : error) };
   }
-  // Report which schema this workspace resolves to (default ArgoBument vs a
+  // Report which schema this workspace resolves to (default ArchiMate 3.2 vs a
   // repository's own .argo/schema bundle) so the caller/human can see the active
   // modeling language right after init.
   let schema;
@@ -678,7 +724,7 @@ function normalizeRelativePath(value) {
   return String(value).replace(/\\/g, '/');
 }
 
-function toolResult(payload) {
+function toolResult(payload, structuredContent = undefined) {
   return {
     content: [
       {
@@ -686,6 +732,7 @@ function toolResult(payload) {
         text: JSON.stringify(payload, null, 2),
       },
     ],
+    ...(structuredContent === undefined ? {} : { structuredContent }),
     isError: payload.status === 'failed',
   };
 }

package/argo/scripts/ensureArgoHarnessEnvironment.js

@@ -57,7 +57,7 @@ async function runHarnessReport({ checkOnly, workspaceRoot, includeBootstrap })
   try {
     report.harnessEnvironment = loadRepositoryArgoEnvironment(workspaceRoot);
     try {
-      const { bundle, ontology } = require('./argob-schema.js').loadSchemaBundleAndOntology(workspaceRoot);
+      const { bundle, ontology } = require('./schema-bundle.js').loadSchemaBundleAndOntology(workspaceRoot);
       report.schemaBundle = {
         kind: bundle.kind,
         language: ontology.language,

package/argo/scripts/external-graph-query.js

@@ -1,162 +1,162 @@
-'use strict';
-
-// Cross-project graph query (federation client side).
-//
-// A read tool call may carry an optional `projectId`. Absent => the local
-// workspace (unchanged). Present => the call is routed to the federation center
-// (`POST <centerUrl>/graph/read`), which authorizes and forwards to the mirror
-// engine; the native ARGO result is passed through with a `namespaceKey`. There
-// is NO silent fallback to the local graph.
-//
-// The requester identity is the project's own `projectId`, read from
-// `<workspace>/.argo/federation.json`. If it is missing, external queries fail
-// with an explicit "register first" error — the id is never guessed.
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-const EXTERNAL_READ_TOOLS = new Set([
-  'getSystemArchitecture',
-  'getIntentElementContext',
-  'getArchitectureViewContext',
-  'queryNeo4jGraph',
-  'memory_search',
-]);
-
-const FEDERATION_FILE = path.join('.argo', 'federation.json');
-const DEFAULT_CENTER_URL = 'https://argo.derekworkspacev5.com';
-
-function loadFederationIdentity(workspaceRoot) {
-  const file = path.join(workspaceRoot || process.cwd(), FEDERATION_FILE);
-  if (!fs.existsSync(file)) {
-    return null;
-  }
-  try {
-    const identity = JSON.parse(fs.readFileSync(file, 'utf8'));
-    return identity && typeof identity === 'object' ? identity : null;
-  } catch {
-    return null;
-  }
-}
-
-function isExternalQuery(args) {
-  return Boolean(args) && typeof args.projectId === 'string' && args.projectId.trim() !== '';
-}
-
-// A tool call is external iff it is one of the readable tools AND carries projectId.
-function externalQueryRequested(toolName, args) {
-  return EXTERNAL_READ_TOOLS.has(toolName) && isExternalQuery(args);
-}
-
-function forwardedArgs(args) {
-  const out = { ...(args || {}) };
-  // projectId is the router parameter; workspaceRoot/architecturePath are local-only.
-  delete out.projectId;
-  delete out.workspaceRoot;
-  delete out.architecturePath;
-  return out;
-}
-
-/**
- * Route an external read. Returns the native ARGO result (with an added
- * `namespaceKey`) on success, or `{ status:'failed', error:{...} }` — never the
- * local result.
- *
- * @param {object} options
- * @param {string} options.workspaceRoot
- * @param {string} options.tool
- * @param {object} options.args
- * @param {Function} [options.fetchImpl] - injectable fetch (tests)
- */
-async function queryExternalRead({ workspaceRoot, tool, args, fetchImpl }) {
-  const fetchFn = fetchImpl || globalThis.fetch;
-  if (typeof fetchFn !== 'function') {
-    return { status: 'failed', error: { category: 'EXTERNAL_QUERY_UNREACHABLE', message: 'global fetch is unavailable in this runtime' } };
-  }
-
-  const identity = loadFederationIdentity(workspaceRoot);
-  if (!identity || typeof identity.projectId !== 'string' || identity.projectId.trim() === '') {
-    return {
-      status: 'failed',
-      error: {
-        category: 'EXTERNAL_QUERY_NOT_REGISTERED',
-        message: `No federation identity at ${FEDERATION_FILE}. Register this project with the federation center first (registry_register) and write its projectId to ${FEDERATION_FILE}.`,
-      },
-    };
-  }
-
-  if (!EXTERNAL_READ_TOOLS.has(tool)) {
-    return {
-      status: 'failed',
-      error: { category: 'EXTERNAL_QUERY_TOOL_NOT_ALLOWED', message: `tool '${tool}' is not externally readable`, allowed: [...EXTERNAL_READ_TOOLS] },
-    };
-  }
-
-  const centerUrl = String(identity.centerUrl || DEFAULT_CENTER_URL).replace(/\/+$/, '');
-  const url = `${centerUrl}/graph/read`;
-  const body = {
-    requester: identity.projectId,
-    projectId: args.projectId,
-    tool,
-    args: forwardedArgs(args),
-  };
-
-  let response;
-  try {
-    response = await fetchFn(url, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify(body),
-    });
-  } catch (error) {
-    return {
-      status: 'failed',
-      error: {
-        category: 'EXTERNAL_QUERY_UNREACHABLE',
-        message: `federation center unreachable: ${error && error.message ? error.message : error}`,
-        centerUrl,
-      },
-    };
-  }
-
-  let payload = null;
-  try { payload = await response.json(); } catch { /* leave null */ }
-
-  if (response.status === 200 && payload && payload.status === 'ok') {
-    // The engine returns the ARGO tool result; unwrap a {content:[{text}]}
-    // envelope so callers get the native payload, then stamp the namespaceKey.
-    let result = payload.result;
-    if (result && Array.isArray(result.content) && result.content[0] && typeof result.content[0].text === 'string') {
-      try { result = JSON.parse(result.content[0].text); } catch { /* keep the envelope */ }
-    }
-    if (result && typeof result === 'object') {
-      result = { ...result, namespaceKey: payload.namespaceKey || `proj:${args.projectId}` };
-    }
-    return result;
-  }
-
-  const denied = Boolean(payload && payload.status === 'denied');
-  const reason = (payload && payload.reason)
-    || (response.status === 403 ? 'not_authorized' : `http_${response.status}`);
-  return {
-    status: 'failed',
-    error: {
-      category: denied ? 'EXTERNAL_QUERY_DENIED' : 'EXTERNAL_QUERY_FAILED',
-      reason,
-      httpStatus: response.status,
-      requester: identity.projectId,
-      projectId: args.projectId,
-      namespaceKey: `proj:${args.projectId}`,
-    },
-  };
-}
-
-module.exports = {
-  EXTERNAL_READ_TOOLS,
-  FEDERATION_FILE,
-  DEFAULT_CENTER_URL,
-  loadFederationIdentity,
-  isExternalQuery,
-  externalQueryRequested,
-  queryExternalRead,
-};
+'use strict';
+
+// Cross-project graph query (federation client side).
+//
+// A read tool call may carry an optional `projectId`. Absent => the local
+// workspace (unchanged). Present => the call is routed to the federation center
+// (`POST <centerUrl>/graph/read`), which authorizes and forwards to the mirror
+// engine; the native ARGO result is passed through with a `namespaceKey`. There
+// is NO silent fallback to the local graph.
+//
+// The requester identity is the project's own `projectId`, read from
+// `<workspace>/.argo/federation.json`. If it is missing, external queries fail
+// with an explicit "register first" error — the id is never guessed.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const EXTERNAL_READ_TOOLS = new Set([
+  'getSystemArchitecture',
+  'getIntentElementContext',
+  'getArchitectureViewContext',
+  'queryNeo4jGraph',
+  'memory_search',
+]);
+
+const FEDERATION_FILE = path.join('.argo', 'federation.json');
+const DEFAULT_CENTER_URL = 'https://argo.derekworkspacev5.com';
+
+function loadFederationIdentity(workspaceRoot) {
+  const file = path.join(workspaceRoot || process.cwd(), FEDERATION_FILE);
+  if (!fs.existsSync(file)) {
+    return null;
+  }
+  try {
+    const identity = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return identity && typeof identity === 'object' ? identity : null;
+  } catch {
+    return null;
+  }
+}
+
+function isExternalQuery(args) {
+  return Boolean(args) && typeof args.projectId === 'string' && args.projectId.trim() !== '';
+}
+
+// A tool call is external iff it is one of the readable tools AND carries projectId.
+function externalQueryRequested(toolName, args) {
+  return EXTERNAL_READ_TOOLS.has(toolName) && isExternalQuery(args);
+}
+
+function forwardedArgs(args) {
+  const out = { ...(args || {}) };
+  // projectId is the router parameter; workspaceRoot/architecturePath are local-only.
+  delete out.projectId;
+  delete out.workspaceRoot;
+  delete out.architecturePath;
+  return out;
+}
+
+/**
+ * Route an external read. Returns the native ARGO result (with an added
+ * `namespaceKey`) on success, or `{ status:'failed', error:{...} }` — never the
+ * local result.
+ *
+ * @param {object} options
+ * @param {string} options.workspaceRoot
+ * @param {string} options.tool
+ * @param {object} options.args
+ * @param {Function} [options.fetchImpl] - injectable fetch (tests)
+ */
+async function queryExternalRead({ workspaceRoot, tool, args, fetchImpl }) {
+  const fetchFn = fetchImpl || globalThis.fetch;
+  if (typeof fetchFn !== 'function') {
+    return { status: 'failed', error: { category: 'EXTERNAL_QUERY_UNREACHABLE', message: 'global fetch is unavailable in this runtime' } };
+  }
+
+  const identity = loadFederationIdentity(workspaceRoot);
+  if (!identity || typeof identity.projectId !== 'string' || identity.projectId.trim() === '') {
+    return {
+      status: 'failed',
+      error: {
+        category: 'EXTERNAL_QUERY_NOT_REGISTERED',
+        message: `No federation identity at ${FEDERATION_FILE}. Register this project with the federation center first (registry_register) and write its projectId to ${FEDERATION_FILE}.`,
+      },
+    };
+  }
+
+  if (!EXTERNAL_READ_TOOLS.has(tool)) {
+    return {
+      status: 'failed',
+      error: { category: 'EXTERNAL_QUERY_TOOL_NOT_ALLOWED', message: `tool '${tool}' is not externally readable`, allowed: [...EXTERNAL_READ_TOOLS] },
+    };
+  }
+
+  const centerUrl = String(identity.centerUrl || DEFAULT_CENTER_URL).replace(/\/+$/, '');
+  const url = `${centerUrl}/graph/read`;
+  const body = {
+    requester: identity.projectId,
+    projectId: args.projectId,
+    tool,
+    args: forwardedArgs(args),
+  };
+
+  let response;
+  try {
+    response = await fetchFn(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+  } catch (error) {
+    return {
+      status: 'failed',
+      error: {
+        category: 'EXTERNAL_QUERY_UNREACHABLE',
+        message: `federation center unreachable: ${error && error.message ? error.message : error}`,
+        centerUrl,
+      },
+    };
+  }
+
+  let payload = null;
+  try { payload = await response.json(); } catch { /* leave null */ }
+
+  if (response.status === 200 && payload && payload.status === 'ok') {
+    // The engine returns the ARGO tool result; unwrap a {content:[{text}]}
+    // envelope so callers get the native payload, then stamp the namespaceKey.
+    let result = payload.result;
+    if (result && Array.isArray(result.content) && result.content[0] && typeof result.content[0].text === 'string') {
+      try { result = JSON.parse(result.content[0].text); } catch { /* keep the envelope */ }
+    }
+    if (result && typeof result === 'object') {
+      result = { ...result, namespaceKey: payload.namespaceKey || `proj:${args.projectId}` };
+    }
+    return result;
+  }
+
+  const denied = Boolean(payload && payload.status === 'denied');
+  const reason = (payload && payload.reason)
+    || (response.status === 403 ? 'not_authorized' : `http_${response.status}`);
+  return {
+    status: 'failed',
+    error: {
+      category: denied ? 'EXTERNAL_QUERY_DENIED' : 'EXTERNAL_QUERY_FAILED',
+      reason,
+      httpStatus: response.status,
+      requester: identity.projectId,
+      projectId: args.projectId,
+      namespaceKey: `proj:${args.projectId}`,
+    },
+  };
+}
+
+module.exports = {
+  EXTERNAL_READ_TOOLS,
+  FEDERATION_FILE,
+  DEFAULT_CENTER_URL,
+  loadFederationIdentity,
+  isExternalQuery,
+  externalQueryRequested,
+  queryExternalRead,
+};

package/argo/scripts/graph-rag/liveEmbeddingProviderConfig.js

@@ -99,8 +99,11 @@ const HOST_ONLY_ENV_KEYS = Object.freeze([
   'ARGO_MCP_SEMANTIC_DEDUP',
   'ARGO_MCP_SEMANTIC_DEDUP_THRESHOLD',
   'ARGO_SEMANTIC_DEDUP_THRESHOLD',
+  'ARGO_WORKSPACE_WRITE_GUARD',
+  'ARGO_WORKSPACE_ROOT_TRUSTED',
   'ARGO_COST_PROFILER',
   'ARGO_COST_TRACE_MAX_BYTES',
+  'ARGO_CONTEXT_MAX_BYTES',
 ]);
 const PROHIBITED_RUNTIME_FIELD_KEYS = Object.freeze(['neo4jUri', 'embeddingCredential']);
 const SECRET_KEYS = new Set(['ARGO_NEO4J_DATABASE_PASSWORD', 'QWEN_KEY', 'ARGO_RERANK_API_KEY', EMBEDDING_API_KEY_KEY]);

package/argo/scripts/graph-semantics.js

@@ -8,10 +8,10 @@
 // view element limit) is supplied by an *ontology* so a repository that ships
 // its own schema under .argo/schema is validated against its own language.
 //
-// The ontology argument is optional: when omitted, the default ArgoBument
+// The ontology argument is optional: when omitted, the default ArchiMate 3.2
 // (ArchiMate 3.2 + ARGO) ontology is used, preserving historical behaviour.
 
-const { loadSchemaBundleAndOntology } = require('./argob-schema.js');
+const { loadSchemaBundleAndOntology } = require('./schema-bundle.js');
 
 let defaultOntology = null;
 
@@ -30,7 +30,7 @@ function resolveOntology(ontology) {
  *
  * @param {object} document - parsed SystemArchitecture JSON
  * @param {string[]} errors - error accumulator
- * @param {object} [ontology] - resolved modeling language (defaults to ArgoBument)
+ * @param {object} [ontology] - resolved modeling language (defaults to ArchiMate 3.2)
  */
 function validateGraphSemantics(document, errors, ontology) {
   if (!document || typeof document !== 'object') {
@@ -259,8 +259,105 @@ function validateViewElementLimits(document, errors, options = {}) {
   }
 }
 
+// Per-element-type attribute contract (issue #3): required attributes, a
+// controlled vocabulary per attribute (enumByAttr) and uniqueness per attribute.
+// Supplied by the active schema bundle's `attributesByElementType`; absent => no-op
+// (fully backward compatible).
+function attributeEntriesByName(element) {
+  const map = new Map();
+  const entries = Array.isArray(element && element.attributes) ? element.attributes : [];
+  for (const entry of entries) {
+    if (!entry || typeof entry !== 'object' || typeof entry.name !== 'string' || entry.name === '') {
+      continue;
+    }
+    if (!map.has(entry.name)) {
+      map.set(entry.name, []);
+    }
+    map.get(entry.name).push(entry);
+  }
+  return map;
+}
+
+function attributeValueOf(entry) {
+  if (entry.value !== undefined && entry.value !== null) {
+    return entry.value;
+  }
+  if (entry.content !== undefined && entry.content !== null) {
+    return entry.content;
+  }
+  return undefined;
+}
+
+function validateAttributeContracts(document, errors, ontology) {
+  const language = resolveOntology(ontology);
+  const contracts = language.attributesByElementType;
+  if (!contracts || typeof contracts !== 'object') {
+    return;
+  }
+  const uniqueTrackers = new Map();
+  for (const type of Object.keys(contracts)) {
+    uniqueTrackers.set(type, new Map());
+  }
+
+  for (const element of document.elements || []) {
+    if (!element || typeof element !== 'object') {
+      continue;
+    }
+    const contract = contracts[element.type];
+    if (!contract || typeof contract !== 'object') {
+      continue;
+    }
+    const byName = attributeEntriesByName(element);
+
+    for (const name of Array.isArray(contract.required) ? contract.required : []) {
+      const entries = byName.get(name);
+      const present = Array.isArray(entries) && entries.some((entry) => {
+        const value = attributeValueOf(entry);
+        return value !== undefined && value !== '';
+      });
+      if (!present) {
+        errors.push(`element '${element.id}' (type '${element.type}') is missing required attribute '${name}'`);
+      }
+    }
+
+    const enumByAttr = contract.enumByAttr && typeof contract.enumByAttr === 'object' ? contract.enumByAttr : {};
+    for (const [attr, allowed] of Object.entries(enumByAttr)) {
+      if (!Array.isArray(allowed)) {
+        continue;
+      }
+      for (const entry of byName.get(attr) || []) {
+        const value = attributeValueOf(entry);
+        if (value === undefined) {
+          continue;
+        }
+        const matches = allowed.some((option) => option === value || JSON.stringify(option) === JSON.stringify(value));
+        if (!matches) {
+          errors.push(`element '${element.id}' (type '${element.type}') attribute '${attr}' value ${JSON.stringify(value)} is not one of: ${allowed.map((option) => JSON.stringify(option)).join(', ')}`);
+        }
+      }
+    }
+
+    for (const attr of Array.isArray(contract.unique) ? contract.unique : []) {
+      const tracker = uniqueTrackers.get(element.type);
+      for (const entry of byName.get(attr) || []) {
+        const value = attributeValueOf(entry);
+        if (value === undefined) {
+          continue;
+        }
+        const key = JSON.stringify(value);
+        if (tracker.has(key) && tracker.get(key) !== element.id) {
+          errors.push(`element '${element.id}' (type '${element.type}') attribute '${attr}' value ${key} duplicates element '${tracker.get(key)}'`);
+        } else if (!tracker.has(key)) {
+          tracker.set(key, element.id);
+        }
+      }
+    }
+  }
+}
+
 module.exports = {
   validateGraphSemantics,
   validateArchiMateEndpointMatrix,
   validateViewElementLimits,
+  validateAttributeContracts,
 };