Semantic Agent™

/**
 * Semantic Agent™ — the canonical agent object
 *
 * An authoritative, serializable software object whose SIX canonical fields
 * make it an agent: intent, context, memory, policy, mutation, and lineage.
 * Governance, memory, and lineage are intrinsic to the object — not wrapped
 * around it. It is the unit every other module in this package operates ON.
 */
import type { AQAlias, AQID, DynamicAgentHash, Signature } from './types';
import type { CognitiveFields } from './cognition';
import type { ExecutionObject } from './execution';

/** 1 — INTENT. The semantic objective, goal, or purpose the agent pursues. */
export interface Intent {
  objective: string;
  subgoals?: string[];
}

/** 2 — CONTEXT. The trust zone the agent operates in, and serializable
 *  parameters. The zone scopes routing, alias resolution, and policy. */
export interface Context {
  zone?: AQAlias;
  parameters?: Record<string, unknown>;
}

/** 3 — MEMORY. State the agent carries: prior outcomes, the trust history
 *  routing reads, and resumable execution state. Carried by the agent, not held
 *  in an external service. */
export interface Memory {
  records: MemoryRecord[];
  /** Trust history other nodes weigh when routing or admitting this agent. */
  trust?: number;
  execution?: ExecutionObject;
}

export interface MemoryRecord {
  /** Display timestamp, e.g. "2026-06-16" — the host formats. */
  at: string;
  kind: 'validation' | 'mutation' | 'execution' | 'route' | 'note';
  outcome: string;
}

/** 4 — POLICY. A reference to the signed governance policy that scopes what the
 *  agent may do; resolved and verified before any execution context exists. */
export interface PolicyReference {
  ref: AQAlias;
  policyHash?: string;
}

/** 5 — MUTATION. The proposed/permitted state transition — what may change,
 *  under what authorization. Non-execution is a valid result. */
export interface MutationDescriptor {
  operation: 'create' | 'mutate' | 'delegate' | 'spawn' | 'terminate' | 'none';
  authorization?: Signature;
}

/** 6 — LINEAGE. References to the agent's semantic ancestors — a traceable
 *  graph of inheritance and evolution; the basis for audit and replay. */
export interface Lineage {
  self: AQID;
  ancestors: AQID[];
}

/** A FULL Semantic Agent — all six canonical fields present and coherent. */
export interface SemanticAgent {
  intent: Intent;
  context: Context;
  memory: Memory;
  policy: PolicyReference;
  mutation: MutationDescriptor;
  lineage: Lineage;
  /** Optional cognition (AQI™). */
  cognition?: CognitiveFields;
  /** Optional current identity hash (@AQ™ / keyless identity). */
  identity?: DynamicAgentHash;
}

/**
 * Structural validation & partial agents
 *
 * An object is an agent by the PRESENCE and coherence of its canonical fields,
 * never by execution history or session state, so it can be validated at rest.
 * A FULL agent has all six fields; a
 * PARTIAL agent (any non-empty subset) is structurally valid and operates
 * through fallback scaffolding, delegation, and inference until completed —
 * which is why full and partial agents are validated through this one module,
 * separate from the agent definition itself.
 */
import type { SemanticAgent } from './agent';

/** Any subset of the canonical fields. */
export type PartialSemanticAgent = Partial<SemanticAgent>;

export const CANONICAL_FIELDS = [
  'intent',
  'context',
  'memory',
  'policy',
  'mutation',
  'lineage',
] as const;
export type CanonicalField = (typeof CANONICAL_FIELDS)[number];

export interface ValidationResult {
  kind: 'full' | 'partial' | 'invalid';
  present: CanonicalField[];
  missing: CanonicalField[];
}

/** Decide whether an object is an agent by the presence of its canonical
 *  fields, without running it. No fields → not an agent; any subset → a valid
 *  partial agent; all six → a full agent. */
export function validate(object: PartialSemanticAgent): ValidationResult {
  const present = CANONICAL_FIELDS.filter((f) => object[f] != null);
  const missing = CANONICAL_FIELDS.filter((f) => object[f] == null);
  const kind =
    present.length === CANONICAL_FIELDS.length ? 'full' : present.length > 0 ? 'partial' : 'invalid';
  return { kind, present, missing };
}

/**
 * Memory-resident execution
 *
 * The orchestrator-free lifecycle. Each agent decides locally from its OWN
 * embedded intent, context, memory, and policy; multi-agent goals
 * propagate with no shared global state, no synchronized schedule, and no
 * central orchestration. A confidence-governed agent may keep reasoning while
 * barred from committing state (a non-executing cognitive mode).
 */
import type { SemanticAgent } from './agent';

export interface ExecutionObject {
  phase: 'execute' | 'mutate' | 'delegate' | 'dormant' | 'reentry' | 'terminate';
  committing: boolean;
}

/** A single local execution step. Confidence gates whether it may commit. */
export function step(agent: SemanticAgent): ExecutionObject {
  const ready = (agent.cognition?.confidence ?? 1) >= 0.5;
  return { phase: agent.mutation.operation === 'none' ? 'dormant' : 'execute', committing: ready };
}

/**
 * Adaptive Query Intelligence™ (AQI™) — cognition, inference, and training
 *
 * The optional self-regulating extension a Semantic Agent may carry, plus the
 * agent-resident inference tooling and lineage-derived personal corpus. Each
 * field is independently useful; coupled, they yield human-relatable dynamics,
 * and they GOVERN traversal depth (discovery) and execution readiness.
 */
import type { AQAlias, AQID, Signature } from './types';
import type { SemanticAgent } from './agent';

/** Cognitive domain fields. Values normalized 0–1 unless noted. */
export interface CognitiveFields {
  affect?: number;
  integrity?: number;
  personality?: Record<string, number>;
  forecasting?: number;
  /** The revocable right to act; gates whether execution may commit. */
  confidence?: number;
  /** What can structurally exist on the substrate (compute, time, energy,
   *  motor envelope). */
  capability?: number;
}

/** A tool the agent may invoke at inference time, held in a governed registry.
 *  The model proposes as a structurally untrusted generator; a tool unlocks
 *  only on demonstrated mastery (skill gating) and is admitted by policy and
 *  the agent's capability before it can run. */
export interface InferenceTool {
  name: AQAlias;
  /** Capability threshold the agent must meet to invoke the tool. */
  requires: number;
  /** Certification token bound to device + person; non-transferable. */
  certification?: Signature;
}

/** A lineage-derived personal corpus: training content governed per-example
 *  (depth-selective, provenance-constrained — refusing to learn from an example
 *  is a valid result), assembled from the agent's own lineage. Content into
 *  training, training into cognition. */
export interface PersonalCorpus {
  owner: AQAlias;
  items: { aqid: AQID; admit: boolean; provenance?: AQAlias }[];
}

/** Admit a tool for an agent: present, within the agent's capability, and —
 *  for a tool that carries a certification requirement — unlocked only by a
 *  matching, presented credential. */
export function admitTool(
  tools: InferenceTool[],
  agent: SemanticAgent,
  name: AQAlias,
  presentedCertification?: Signature,
): InferenceTool | null {
  const tool = tools.find((t) => t.name === name);
  if (!tool) return null;
  const capable = (agent.cognition?.capability ?? 0) >= tool.requires;
  const certified = !tool.certification || tool.certification === presentedCertification;
  return capable && certified ? tool : null;
}

/**
 * @AQ™ — identity, addressing, and messaging
 *
 * Memory-native, keyless identity: an agent's identity is a chain of dynamic
 * agent hashes (a "trust slope"), quorum-recoverable, secure under hash-preimage
 * resistance rather than Shor-vulnerable algebra — no persistent key material.
 * The same @AQ™ alias addresses any subject on the network (agent, device,
 * person, content, or record), and messages are authenticated against the
 * sender's current hash. The human an agent acts for is resolved the same way:
 * by biological continuity, not a stored template.
 */
import type { AQAlias, DynamicAgentHash } from './types';
import type { SemanticAgent } from './agent';

/** Derive the successor hash from the prior trusted one, under an update rule
 *  incorporating unpredictability and a volatile salt. */
export function nextHash(prev: DynamicAgentHash, salt: string): DynamicAgentHash {
  return `dah:${prev.slice(4)}>${salt}`;
}

/** Two-stage authentication: accept an agent by plausible succession along its
 *  hash chain, not a stored template. */
export function authenticate(agent: SemanticAgent, expectedSuccessorOf: DynamicAgentHash): boolean {
  return !!agent.identity && agent.identity.includes(expectedSuccessorOf.slice(4));
}

/** Biological continuity — recognition by plausible succession along a
 *  behavioral and physiological trajectory rather than a stored template, with
 *  domain-separated, non-invertible hashes and predictive drift detection. */
export interface BiologicalContinuity {
  subject: AQAlias;
  trajectory: DynamicAgentHash[];
  /** Predictive drift since the last accepted observation (0 = on-trajectory). */
  drift: number;
}

/** A message between aliased subjects. The sender performs authenticated
 *  encryption over the payload and embeds its current dynamic agent hash inside
 *  the ciphertext for payload-layer verification. */
export interface Message {
  from: AQAlias;
  to: AQAlias;
  ciphertext: string;
  senderHash: DynamicAgentHash;
}

/**
 * Adaptive Network™ — the agent is the transported unit
 *
 * The unit that moves on the wire is a cryptographically signed agent. The
 * behavior of the routing, indexing, and consensus layers is determined by
 * metadata embedded in the received agent — its trust history and the @AQ™
 * alias in its transport field — not by IP addresses or DNS. Agents may spawn
 * child agents to update index maps or perform distributed tasks.
 */
import type { AQAlias, Signature } from './types';
import type { SemanticAgent } from './agent';

export interface AgentEnvelope {
  agent: SemanticAgent;
  /** The @AQ™ alias the node resolves within the agent's trust domain. */
  transport: AQAlias;
  signature: Signature;
}

/** Trust-scoped routing: the next hop is chosen from the agent's embedded trust
 *  history and the resolved transport alias. */
export function route(envelope: AgentEnvelope, peers: AQAlias[]): AQAlias | null {
  const admitted = (envelope.agent.memory.trust ?? 0) >= 0.3;
  return admitted ? (peers[0] ?? null) : null;
}

/**
 * Adaptive Index™ — resolution & semantic discovery
 *
 * Anchors govern segments of a hierarchical namespace: they cache, validate
 * alias-to-UID mappings, and participate in scoped quorum. Discovery is an agent
 * traversing the adaptive index through successive anchor evaluations, each step
 * governed by the agent's cognitive state, with requester-scoped neighborhoods
 * so different credentials see different reachable territory.
 */
import type { AQAlias, AQID } from './types';
import type { SemanticAgent } from './agent';

/** A governance participant for an index segment. */
export interface IndexAnchor {
  scope: AQAlias;
  resolve(alias: AQAlias): AQID | null;
}

/** Traverse the index for an agent; cognition governs how far it reaches.
 *  Returns the artifacts the agent may reach. */
export function discover(agent: SemanticAgent, anchors: IndexAnchor[], query: AQAlias): AQID[] {
  const reach = agent.cognition?.confidence ?? 1;
  return anchors
    .filter(() => reach > 0.2)
    .map((a) => a.resolve(query))
    .filter((id): id is AQID => id != null);
}

/**
 * Cryptographic governance
 *
 * The enforcement layer the rest of the package trusts. Behavioral authority is
 * externalized to a signed policy object, resolved and verified
 * before an execution context is instantiated. Bypassing it does not produce an
 * unauthorized action — it produces an object that fails verification. Non-
 * execution is a valid, recorded result.
 */
import type { AQAlias, Signature } from './types';
import type { SemanticAgent, MutationDescriptor } from './agent';

export interface PolicyObject {
  id: AQAlias;
  rules: PolicyRule[];
  signature: Signature;
  /** Monotonic version (anti-rollback). */
  version: number;
}

export interface PolicyRule {
  operation: MutationDescriptor['operation'];
  effect: 'allow' | 'deny' | 'require-authorization';
}

/** Authorize (or refuse) an agent's proposed mutation against signed policy. */
export function authorize(agent: SemanticAgent, policy: PolicyObject): boolean {
  const rule = policy.rules.find((r) => r.operation === agent.mutation.operation);
  if (!rule || rule.effect === 'deny') return false;
  if (rule.effect === 'require-authorization') return !!agent.mutation.authorization;
  return true;
}

/**
 * Adaptive Coin™ — governed value transfer
 *
 * A settlement pre-authorized by signed policy and routed by attribution from
 * agent activity — for example, content consultation → attribution weights →
 * payment routing. The same governance that gates a mutation gates a transfer:
 * pre-authorization, audit, and revocation are structural, not advisory.
 */
import type { AQAlias, AQID } from './types';

export interface ValueTransfer {
  from: AQAlias;
  to: AQAlias;
  amount: number;
  /** The policy authorizing the transfer. */
  authorizedBy: AQAlias;
  /** Optional attribution — the artifacts/agents the value is owed to. */
  attribution?: { subject: AQID; weight: number }[];
}

/**
 * AQID™ — content identity
 *
 * A content artifact's AQID is derived from a multi-axis variance vector: a
 * similarity-computable signature that survives transcoding, rescaling, and
 * compression, with no central registry. It enables decentralized content
 * identity, alias governance, mutation tracking, and provenance verification —
 * and it is the gate on what may enter a training corpus: content into training.
 */
import type { AQAlias, AQID, VarianceVector } from './types';

export interface ContentArtifact {
  aqid: AQID;
  variance: VarianceVector;
  provenance?: AQAlias;
}

/**
 * Adaptive Space™ — the agent takes a body
 *
 * Perception leaves the moving agent and lives in the navigable environment: the
 * environment broadcasts authority-credentialed observations, each receiver
 * verifies a credential before admitting one, and position and time are derived
 * cooperatively from the mesh — no GPS, no RTK base, no HD map, no central
 * coordinator — and the whole system is replayable from its observation log.
 */
import type { Signature } from './types';

export interface SpatialObservation {
  /** The credential the receiver verifies before admitting the observation. */
  credential: Signature;
  /** Mesh-derived position and time (cooperative, replayable from the log). */
  coordinate: [number, number, number];
  meshTime: string;
}

/**
 * Adaptive Query™ SDK — shared identifiers
 *
 * Primitive id types used across the package.
 */

/** An @AQ™ alias — a subject addressed on the network without a stored
 *  credential: an agent, device, person, zone, content item, or record. */
export type AQAlias = string;

/** An AQID™ — the identity of a content or other artifact, derived from a
 *  multi-axis variance vector. */
export type AQID = string;

/** A dynamic agent hash (DAH) — one link in an agent's identity chain. */
export type DynamicAgentHash = string;

/** A cryptographic signature over an object (policy, mutation, message). */
export type Signature = string;

/** A multi-axis variance vector — a similarity-computable content signature
 *  that survives transcoding, rescaling, and compression. */
export type VarianceVector = number[];

/**
 * Adaptive Query™ (AQ™) — reference SDK
 *
 * One agent object, threaded through every layer of the architecture. This
 * barrel composes the package: the Semantic Agent™ core; structural validation
 * and memory-resident execution; AQI™ cognition, inference tooling, and a
 * personal corpus; @AQ™ identity, addressing, and messaging; the Adaptive
 * Network™ transport; Adaptive Index™ resolution and discovery; cryptographic
 * governance; Adaptive Coin™ value transfer; AQID™ content identity; and the
 * Adaptive Space™ mesh.
 *
 * Adaptive Query™, AQ™, Semantic Agent™, AQI™, @AQ™, AQID™, Adaptive Network™,
 * Adaptive Index™, Adaptive Coin™, and Adaptive Space™ are trademarks of
 * Nicholas Clark, used in connection with the Adaptive Query platform. Subject
 * to one or more pending U.S. and international patent applications.
 *
 * Reference implementation © 2025–2026 Nicholas Clark, licensable through
 * Adaptive Query LLC. No license is granted except under separate written
 * agreement.
 * https://qu3ry.net/semantic-agent
 */
export * from './types';
export * from './agent';
export * from './validation';
export * from './execution';
export * from './cognition';
export * from './identity';
export * from './network';
export * from './discovery';
export * from './governance';
export * from './value';
export * from './content';
export * from './spatial';

import type { SemanticAgent } from './agent';
import type { PartialSemanticAgent } from './validation';

/** A full, governed, embodied agent carrying identity and cognition. */
export const exampleAgent: SemanticAgent = {
  intent: { objective: 'Resolve, verify, and cache the requested namespace segment.' },
  context: { zone: '@aq/zone/wikipedia', parameters: { region: 'us-east' } },
  memory: {
    trust: 0.74,
    records: [{ at: '2026-06-16', kind: 'validation', outcome: 'fields coherent' }],
  },
  policy: { ref: '@aq/policy/index-mutation', policyHash: 'sha256:9f2c…' },
  mutation: { operation: 'mutate', authorization: 'sig:b41a…' },
  lineage: { self: 'aqid:agent:7a3f', ancestors: ['aqid:agent:1b20'] },
  cognition: { confidence: 0.82, capability: 1 },
  identity: 'dah:7a3f>salt-0x91',
};

/** A partial agent — intent + context only — completed downstream by delegation. */
export const examplePartial: PartialSemanticAgent = {
  intent: { objective: 'Draft a trajectory in the mesh; do not commit.' },
  context: { zone: '@aq/zone/vehicle' },
};