Social DNA: Making Social Interaction Patterns Explicit

// Define what a "post" means in this space
const postClass = {
  properties: {
    content: "string",
    author: "did",
    timestamp: "datetime"
  },
  actions: {
    like: "any agent can like a post once",
    comment: "any agent can comment on a post",
    edit: "only the author can edit their post"
  }
}
 
// Define what "trending" means in this space
const trendingRule = {
  condition: "post has more than 5 likes in last 24 hours",
  action: "mark post as trending"
}

expression://xyz123

Base Expression: expression://xyz123
                       │
    ┌───────────────┬──┴──┬───────────────┐
    │               │     │               │
  state          author  title         comments
    │               │     │               │
  "done"        did:123  "Hi"     [expr1, expr2]

// A Todo class looks for state and assignments
class Todo {
  state: string;    // Looks for todo://state links
  assignee: string; // Looks for todo://assigned-to links
}
 
// A Post class looks for social interactions
class Post {
  likes: string[];     // Looks for social://like links
  comments: string[];  // Looks for social://comment links
}
 
// Both can exist simultaneously on the same base expression
const todo = await perspective.getSubjectProxy<Todo>(baseExpr, "Todo");
const post = await perspective.getSubjectProxy<Post>(baseExpr, "Post");

import { Ad4mModel, Model, Property, HasMany } from '@coasys/ad4m';
 
@Model({ name: "Todo" })
class Todo extends Ad4mModel {
  @Property({ through: "todo://state", initial: "todo://ready" })
  state: string = "";
 
  @Property({ through: "todo://has_title" })
  title?: string;
 
  @HasMany({ through: "todo://comment" })
  comments: string[] = [];
}
 
// Register the class with a perspective (once at app startup)
await Todo.register(perspective);
 
// Use it with full type safety and ActiveRecord patterns
const todo = new Todo(perspective);
todo.state = "todo://doing";
await todo.save();
 
// Query with the fluent API
const todos = await Todo.findAll(perspective);
const doneTodos = await Todo.query(perspective)
  .where({ state: "todo://done" })
  .get();

import { SHACLShape } from '@coasys/ad4m';
 
// Create a shape programmatically
const shape = new SHACLShape('recipe://Recipe');
shape.addProperty({
  path: 'recipe://name',
  datatype: 'xsd:string',
  maxCount: 1,
  minCount: 1,
});
shape.addProperty({
  path: 'recipe://ingredient',
  datatype: 'xsd:string',
  // No maxCount = collection
});
 
// Store in perspective
await perspective.addShacl('Recipe', shape);
 
// Retrieve
const retrieved = await perspective.getShacl('Recipe');
 
// List all shapes
const allShapes = await perspective.getAllShacl();

// Add a subject class definition (SHACL) to a perspective
await Todo.register(perspective);
 
// Or add SHACL directly
await perspective.addShacl("Todo", shape);
 
// List all available subject classes
const classes = await perspective.subjectClasses();
// Returns: ["Todo"]
 
// Create a new subject instance
await perspective.createSubject("Todo", "expression://123");
 
// Check if an expression is an instance of a class
const isTodo = await perspective.isSubjectInstance("expression://123", "Todo");
 
// Get subject data
const todoData = await perspective.getSubjectData("Todo", "expression://123");
 
// Remove a subject (runs destructor if defined)
await perspective.removeSubject("Todo", "expression://123");
 
// Get all instances of a class
const allTodos = await perspective.getAllSubjectInstances("Todo");
 
// Get a proxy object
const todo = await perspective.getSubjectProxy("expression://123", "Todo");

import { SHACLFlow } from "@coasys/ad4m";
 
const deliveryFlow = new SHACLFlow("Delivery", "delivery://");
 
deliveryFlow.inputTypes = ["Task"];
deliveryFlow.interpretationHint =
  "Advance a Task through delivery: Identified → Scoped → InProgress → Review → Done.";
 
deliveryFlow.addState({ name: "Identified", value: 0, interpretationHint: "The Task has been named but not yet scoped." });
deliveryFlow.addState({ name: "Scoped",     value: 1, interpretationHint: "The Task has an acceptance criterion." });
deliveryFlow.addState({ name: "InProgress", value: 2, interpretationHint: "Someone is actively working on it." });
deliveryFlow.addState({ name: "Review",     value: 3, interpretationHint: "The Task is ready for peer review." });
deliveryFlow.addState({ name: "Done",       value: 4, interpretationHint: "The Task is accepted and complete." });
 
deliveryFlow.addTransition({ actionName: "Scope",     fromState: "Identified", toState: "Scoped",     actions: [] });
deliveryFlow.addTransition({ actionName: "Start",     fromState: "Scoped",     toState: "InProgress", actions: [] });
deliveryFlow.addTransition({ actionName: "Submit",    fromState: "InProgress", toState: "Review",     actions: [] });
deliveryFlow.addTransition({ actionName: "Accept",    fromState: "Review",     toState: "Done",       actions: [] });
 
// Optional: require n distinct DIDs to co-sign a proposal before it fires.
deliveryFlow.consensusRule = { n: 2 };

import { FlowInstance } from "@coasys/ad4m";
 
// Which flows accept this expression as input? Returns flow names whose
// `inputTypes` match the expression's registered subject classes, plus any
// flow declaring no `inputTypes` or the "any" wildcard.
const availableFlows = await perspective.availableFlows("task://sprint-3/T-42");
// Returns: ["Delivery"]
 
// Mint a fresh FlowInstance in the flow's initial state (states[0] — the
// lowest-valued state). Takes the flow *name*; the shape is loaded for you.
const instance = await FlowInstance.start(
  perspective,
  "Delivery",
  "task://sprint-3/T-42",
);
 
// Read every active FlowInstance for a flow. The filter also accepts
// `{ flowName?, subject? }` — pass `subject` to ask "what is running on
// this expression?".
const instances = await FlowInstance.findAll(perspective, "Delivery");
 
// Where is it now? `currentState` resolves to the FlowState on the shape,
// so the interpretationHint the LLM sees is right there.
console.log(instance.currentStateName);            // "Identified"
console.log(instance.currentState.interpretationHint);
 
// Which actions are legal from here? Empty on a terminal state.
for (const t of instance.availableTransitions) {
  console.log(t.actionName, "→", t.toState);       // "Scope" → "Scoped"
}
 
// Proposals standing against this instance.
const proposals = await instance.proposals();

// Recommended: type-safe helper takes the SHACLFlow instance directly.
await perspective.addFlow("Delivery", deliveryFlow);
 
const flows = await perspective.sdnaFlows();
console.log(flows); // Should include "Delivery"

// Find all todos in "done" state
const doneTodos = await perspective.querySparql(`
  SELECT ?todo WHERE {
    ?link a rdf:Statement ;
          rdf:subject ?todo ;
          rdf:predicate <todo://state> ;
          rdf:object <todo://done> .
  }
`);
 
// Find all posts by Alice
const alicePosts = await perspective.querySparql(`
  SELECT ?target WHERE {
    ?link a rdf:Statement ;
          rdf:subject <user://alice> ;
          rdf:predicate <authored> ;
          rdf:object ?target .
  }
`);
 
// Aggregation - count by type
const stats = await perspective.querySparql(`
  SELECT ?predicate (COUNT(?link) AS ?total) WHERE {
    ?link a rdf:Statement ;
          rdf:predicate ?predicate .
  }
  GROUP BY ?predicate
`);

// Basic graph predicates
triple(Subject, Predicate, Object).      // Access raw triples
link(Subject, Predicate, Object, Timestamp, Author).  // Access links with metadata
 
// Graph traversal
reachable(A, B).  // True if B can be reached from A through any predicates

// Recommended: Use Model Classes (auto-generates SHACL)
await Todo.register(perspective);
 
// Or add SHACL shapes directly
const shape = new SHACLShape('todo://Todo');
shape.addProperty({ path: 'todo://state', datatype: 'xsd:string', maxCount: 1, minCount: 1 });
await perspective.addShacl('Todo', shape);
 
// Add a flow definition
await perspective.addSdna("Todo", flowDefinition, "flow");

// Option 1: Use Ad4mModel (recommended — queries execute server-side via SPARQL)
const activeTodos = await Todo.findAll(perspective, {
  where: { state: "active" }
});
 
// Option 2: Direct SPARQL query
const todos = await perspective.querySparql(`
  SELECT ?todo WHERE {
    ?link a rdf:Statement ;
          rdf:subject ?todo ;
          rdf:predicate <todo://state> ;
          rdf:object <active> .
  }
`);
 
// Option 3: Prolog (for backward compatibility)
const todos = await perspective.infer(
  'instance(Todo, "Todo"), property_getter("Todo", Todo, "state", "active")'
);