/*
 * id.entity.core - The Irreducible Constitution, Core v2.2
 *
 * Models Core v2.2 (6 articles, 19 clauses) as typed data: the Entity, its
 * Constituents, their Capacities, and the six bracketed answers as typed
 * choices - abstract concepts with concrete variants, never free strings.
 *
 * Source of truth: vault universal-constitution/v2.2-reduction.md (2026-09-13).
 * Capacity scopes, cardinality and disclosure absorbed from
 * RegistryChain/RegistrarChain-ZodSchema (constituent-type.ts, enums.ts).
 *
 * provenance:
 *   source: universal-constitution/v2.2-reduction.md@2026-09-13
 *   licence: Apache-2.0
 */
concerto version "^3.0.0"
namespace id.entity.core@2.2.0

// ---------------------------------------------------------------------------
// Shared vocabulary (absorbed from RegistrarChain-ZodSchema)
// ---------------------------------------------------------------------------

/**
 * What a recorded capacity operates on.
 * Absorbed verbatim from ZodSchema CapacityScopeSchema.
 */
enum CapacityScope {
  o ON_ENTITY
  o ON_TREASURY
  o ON_CONSTITUTION
  o ON_CONSTITUENTS
  o ON_ATTESTATIONS
}

/**
 * What kind of subject a Constituent is.
 * Absorbed from ZodSchema SubjectKindSchema.
 */
enum SubjectKind {
  o NATURAL
  o LEGAL
  o WALLET
  o AGENT
  o ANONYMOUS
}

/**
 * Absorbed from ZodSchema DisclosureLevelSchema.
 */
enum DisclosureLevel {
  o PUBLIC
  o REGISTRAR_ONLY
  o ANONYMOUS
}

/**
 * An EVM address. Shared scalar - one regex, used wherever an address
 * field appears (constituents, token contracts, operators of record).
 */
scalar EthAddress extends String regex=/^0x[0-9a-fA-F]{40}$/

/**
 * How many of something is allowed. max absent means unlimited
 * (ZodSchema models this as max: number | "unlimited").
 */
concept Cardinality {
  o Integer min range=[0,]
  o Integer max range=[1,] optional
}

/**
 * A recorded capacity held by a Constituent (clause 2.1: "each holding only
 * the capacities recorded beside their name"). Shape absorbed from
 * ZodSchema CapacitySchema.
 */
concept Capacity {
  o String name
  o CapacityScope scope
  o Boolean requiresQuorum default=false
  o Boolean delegatable default=false
  o String description optional
}

/**
 * A person named in the register (Article II). The register controls over
 * any other document, and over any key (2.1).
 */
concept Constituent {
  o String name
  o SubjectKind subjectKind
  o String[] roles optional
  o Capacity[] capacities
  o EthAddress address optional
  o DisclosureLevel disclosure default="PUBLIC"
}

// ---------------------------------------------------------------------------
// The six bracketed answers as typed choices.
// Each is an abstract concept with concrete variants. A Custom* escape
// variant exists only where external reality may genuinely outrun the
// variants; none of the eight known entity types needs one.
// ---------------------------------------------------------------------------

/**
 * Voting basis for fraction thresholds (who or what is counted).
 */
enum VotingBasis {
  o ALL_CONSTITUENTS
  o CONSTITUENTS_VOTING
  o CONSTITUENTS_PRESENT
  o UNITS
}

/**
 * A fraction threshold, kept as exact integers (2/3, not 0.6667).
 * moreThan=true means strictly more than the fraction (a majority);
 * moreThan=false means at least the fraction (a two-thirds quorum).
 */
concept FractionThreshold {
  o Integer numerator range=[1,]
  o Integer denominator range=[1,]
  o VotingBasis basis
  o Boolean moreThan default=false
}

// --- 2.5 death or incapacity ---

/**
 * Clause 2.5: "On the death or incapacity of a [Constituent], [rule]."
 */
abstract concept DeathIncapacityRule {
}

/** The Entity is dissolved (marriage). */
concept EntityDissolvedOnDeath extends DeathIncapacityRule {
}

/**
 * Capacities lapse; the interest passes to the successor in title, who
 * holds it without capacity until admitted (company, startup, quota).
 */
concept InterestPassesToSuccessor extends DeathIncapacityRule {
  o Boolean successorHoldsWithoutCapacityUntilAdmitted default=true
}

/**
 * Membership simply lapses (association, dao); for a polity, citizenship
 * lapses and any office is vacated (officesVacated=true).
 */
concept MembershipLapses extends DeathIncapacityRule {
  o Boolean officesVacated default=false
}

/** Escape hatch - use only when no typed variant fits; justify in provenance. */
concept CustomDeathIncapacityRule extends DeathIncapacityRule {
  o String text
}

// --- 3.1 act rule ---

/**
 * Clause 3.1: "The Entity is bound toward third parties when [act rule]
 * acts in its name."
 */
abstract concept ActRule {
}

/** Any Constituent - optionally only those holding a named capacity. */
concept AnyConstituentActs extends ActRule {
  o String requiredCapacity optional
}

/** All Constituents acting together. */
concept AllConstituentsAct extends ActRule {
}

/** A named role or organ - "the Council, within the powers delegated to it". */
concept RoleActs extends ActRule {
  o String role
  o String withinDelegatedPowers optional
}

/** A fraction of Constituents (or units) acting together binds the Entity. */
concept FractionActs extends ActRule {
  o FractionThreshold threshold
}

/** Any one of the listed rules suffices - "any Manager, or a majority of the Members". */
concept AnyOfActRules extends ActRule {
  o ActRule[] rules
}

/** N of M signers (multisig-shaped). */
concept ThresholdActs extends ActRule {
  o Integer count range=[1,]
  o Integer of range=[1,] optional
}

/**
 * A dual-scope rule: one rule for ordinary affairs, a stricter rule for
 * named extraordinary matters. Marriage: "either Spouse in the ordinary
 * affairs of the household, both together in any disposition of common
 * property."
 */
concept ScopedActRule extends ActRule {
  o ActRule ordinary
  o ActRule extraordinary
  o String extraordinaryMatters
}

/** Escape hatch - use only when no typed variant fits; justify in provenance. */
concept CustomActRule extends ActRule {
  o String text
}

// --- generic decision rules ---

/**
 * A generic approval rule: who must approve for a decision to take
 * effect. Extensions reference this wherever they need an approval body
 * (E1 distributions and transfer consent, E3 admission and expulsion,
 * E7 elections). The clause-3.2 AmendmentRule specialises it below.
 */
abstract concept DecisionRule {
}

/** Every Constituent must approve. */
concept AllConstituentsDecide extends DecisionRule {
}

/**
 * A fraction threshold approves - majority of units, two-thirds of
 * citizens voting, two-thirds of members present.
 */
concept FractionDecides extends DecisionRule {
  o FractionThreshold threshold
}

/** A named role or organ approves (boards, councils). */
concept RoleDecides extends DecisionRule {
  o String role
}

/** N of M approvers (multisig-shaped). */
concept ThresholdDecides extends DecisionRule {
  o Integer count range=[1,]
  o Integer of range=[1,] optional
}

/** Escape hatch - use only when no typed variant fits; justify in provenance. */
concept CustomDecisionRule extends DecisionRule {
  o String text
}

// --- 3.2 amendment rule ---

/**
 * Clause 3.2: "This Constitution, and anything recorded under it, changes
 * when [amendment rule] approves the change." The clause-3.2-specific
 * specialisation of DecisionRule - only these variants may sit in the
 * Constitution's amendmentRule slot.
 */
abstract concept AmendmentRule extends DecisionRule {
}

/** Every Constituent must approve (marriage: both Spouses). */
concept AllConstituentsAmend extends AmendmentRule {
}

/**
 * A fraction threshold approves - majority of units, two-thirds of
 * citizens voting, two-thirds of members present.
 */
concept FractionAmends extends AmendmentRule {
  o FractionThreshold threshold
}

/** A named role or organ approves (rare; boards, councils). */
concept RoleAmends extends AmendmentRule {
  o String role
}

/** Escape hatch - use only when no typed variant fits; justify in provenance. */
concept CustomAmendmentRule extends AmendmentRule {
  o String text
}

// --- 3.3 interpreter ---

/**
 * Clause 3.3: "A question about the meaning or application of this
 * Constitution is decided by [interpreter]."
 */
abstract concept Interpreter {
}

/** The Constituents themselves, under the rule in 3.2. */
concept ConstituentsInterpret extends Interpreter {
}

/** An arbitrator appointed under stated rules. */
concept ArbitratorInterprets extends Interpreter {
  o String appointmentRules optional
}

/** A named court or forum - "the family court of the place of celebration". */
concept CourtInterprets extends Interpreter {
  o String forum
}

/** A tribunal constituted under a named Extension. */
concept ExtensionTribunalInterprets extends Interpreter {
  o String extensionId regex=/^E[1-9][0-9]*$/
}

/**
 * A tiered interpreter: first limb decides; failing agreement the
 * fallback decides (ACME: the Members by majority, failing agreement the
 * arbitrator recorded in the register).
 */
concept TieredInterpreter extends Interpreter {
  o Interpreter first
  o Interpreter fallback
}

/** Escape hatch - use only when no typed variant fits; justify in provenance. */
concept CustomInterpreter extends Interpreter {
  o String text
}

// --- 4.2 answerability ---

/**
 * Clause 4.2: "For the obligations of the Entity, [answerability rule]."
 */
abstract concept AnswerabilityRule {
}

/** The Constituents are not personally answerable. */
concept NotPersonallyAnswerable extends AnswerabilityRule {
}

/**
 * Each Constituent answers only to the extent of what they have
 * contributed or agreed to contribute (quota companies; association
 * subscriptions due - name the limit in limitDescription).
 */
concept LimitedToContribution extends AnswerabilityRule {
  o String limitDescription optional
}

/** The Constituents answer jointly and severally. */
concept JointAndSeveral extends AnswerabilityRule {
}

/** A named role answers (an agent's Operator of Record). */
concept RoleAnswers extends AnswerabilityRule {
  o String role
}

/** The Constituents answer as the regime in a named Extension provides. */
concept PerExtensionRegime extends AnswerabilityRule {
  o String extensionId regex=/^E[1-9][0-9]*$/
}

/** Escape hatch - use only when no typed variant fits; justify in provenance. */
concept CustomAnswerabilityRule extends AnswerabilityRule {
  o String text
}

// --- 6.1 term ---

/**
 * Clause 6.1: "The Entity exists [term], and is dissolved when that term
 * ends or when an amendment declares it ended."
 */
abstract concept Term {
}

/** The Entity exists perpetually, until dissolved by amendment. */
concept PerpetualTerm extends Term {
}

/** The Entity exists until a fixed end date. */
concept FixedEndDateTerm extends Term {
  o DateTime endsOn
}

/** The Entity exists for a fixed number of years from adoption. */
concept FixedYearsTerm extends Term {
  o Integer years range=[1,]
}

/** The Entity exists until a stated event occurs. */
concept UntilEventTerm extends Term {
  o String event
}

/** Escape hatch - use only when no typed variant fits; justify in provenance. */
concept CustomTerm extends Term {
  o String text
}

// ---------------------------------------------------------------------------
// Extensions attach point (clause 6.2) and Adoption
// ---------------------------------------------------------------------------

/**
 * Clause 6.2: "Terms specific to this Entity may be attached as numbered
 * Extensions, adopted and amended as this Constitution is."
 * Concrete Extension types live in their own namespaces
 * (id.entity.ext.e1 .. e7) and extend this concept - that is how one
 * composed model spans a company and a marriage without forking.
 */
abstract concept Extension {
  o String extensionId regex=/^E[1-9][0-9]*$/
  o String title optional
}

/**
 * The Adoption block: "Adopted by the [Constituents] on [date], and
 * recorded under [IDENTIFIER]. The Registry Rules in force at adoption
 * are accepted by this adoption."
 */
concept Adoption {
  o DateTime adoptedOn
  o String registryRulesVersion optional
  o String recordHash optional
  o String announcementReference optional
}

// ---------------------------------------------------------------------------
// The Constitution
// ---------------------------------------------------------------------------

/**
 * One entity's Constitution under Core v2.2: the Preamble variables, the
 * six typed answers, the roll of Constituents, and the adopted Extensions.
 */
@template
concept Constitution identified by identifier {
  // Preamble and Article I - Identity
  o String entityName
  o String identifier
  o String register
  o String purpose

  // The swap-table noun
  o String constituentNoun
  o String constituentNounPlural

  // Article II - Constituents
  o Cardinality constituentCardinality
  o Constituent[] constituents

  // The six bracketed answers - typed choices, not strings
  o DeathIncapacityRule deathIncapacityRule // 2.5
  o ActRule actRule                         // 3.1
  o AmendmentRule amendmentRule             // 3.2
  o Interpreter interpreter                 // 3.3
  o AnswerabilityRule answerabilityRule     // 4.2
  o Term term                               // 6.1

  // Article VI 6.2 - adopted Extensions (typed, per-extension namespaces)
  o Extension[] extensions

  // Adoption block
  o Adoption adoption
}