@anthusai/papyrus 5.30.0 → 5.31.0

package/amplify/plugins/reader-steering/config.js

@@ -5,8 +5,9 @@ export const MODERATION_MODES = ["off", "human", "ai"];
 export const AI_KEY_PARAMETER = /^\/papyrus\/[a-z0-9][a-z0-9-]{0,62}\/openai-api-key$/;
 export const AI_MODEL_NAME = /^[a-z0-9][a-z0-9.-]{0,63}$/;
 export const SUBMISSION_KIND_NAME = /^[a-z][a-z0-9-]{0,23}$/;
+export const SUBJECT_TYPES = ["item", "submission", "story", "proposal", "concept"];
 export const COMPUTE_ROLE_ARN = /^arn:aws:iam::[0-9]{12}:role\/[A-Za-z0-9+=,.@_/-]{1,512}$/;
-const KNOWN_KEYS = new Set(["name", "computeRoleArn", "dimensions", "limits", "reservedHandles", "karma", "ranking", "snapshot", "retirementPoll", "reservedConcurrency", "hypeGap", "submissions", "comments", "moderation"]);
+const KNOWN_KEYS = new Set(["name", "computeRoleArn", "dimensions", "limits", "reservedHandles", "karma", "ranking", "snapshot", "retirementPoll", "reservedConcurrency", "hypeGap", "submissions", "comments", "moderation", "subjects"]);
 function object(raw, label, known) {
     if (raw === undefined)
         return {};
@@ -111,6 +112,11 @@ export function resolveReaderSteeringConfig(request) {
             throw new Error(`reader-steering plugin moderation.ai.model must be a model name matching ${AI_MODEL_NAME}`);
         }
     }
+    const subjects = object(raw.subjects, "subjects", ["types"]);
+    const subjectTypes = subjects.types === undefined ? ["item", "submission"] : subjects.types;
+    if (!Array.isArray(subjectTypes) || subjectTypes.length === 0 || !subjectTypes.every((type) => SUBJECT_TYPES.includes(type))) {
+        throw new Error(`reader-steering plugin subjects.types must be a non-empty list of: ${SUBJECT_TYPES.join(", ")}`);
+    }
     const kinds = names(submissions.kinds, "submissions.kinds", SUBMISSION_KIND_NAME);
     const comments = object(raw.comments, "comments", ["perHour", "editWindowMinutes", "maximumLength", "maximumLinks"]);
     const hypeGap = resolveHypeGap(raw.hypeGap, dimensions);
@@ -154,6 +160,7 @@ export function resolveReaderSteeringConfig(request) {
             itemType: lowercaseName(submissions.itemType, "submissions.itemType", "brief"),
             section: lowercaseName(submissions.section, "submissions.section", "unsectioned"),
         },
+        subjects: { types: [...new Set(subjectTypes)] },
         moderation: {
             mode: mode,
             preModeration,

package/amplify/plugins/reader-steering/config.ts

@@ -7,6 +7,7 @@ export const MODERATION_MODES = ["off", "human", "ai"] as const;
 export const AI_KEY_PARAMETER = /^\/papyrus\/[a-z0-9][a-z0-9-]{0,62}\/openai-api-key$/;
 export const AI_MODEL_NAME = /^[a-z0-9][a-z0-9.-]{0,63}$/;
 export const SUBMISSION_KIND_NAME = /^[a-z][a-z0-9-]{0,23}$/;
+export const SUBJECT_TYPES = ["item", "submission", "story", "proposal", "concept"] as const;
 export const COMPUTE_ROLE_ARN = /^arn:aws:iam::[0-9]{12}:role\/[A-Za-z0-9+=,.@_/-]{1,512}$/;
 
 export type ReaderSteeringConfig = {
@@ -63,6 +64,11 @@ export type ReaderSteeringConfig = {
     /** The section of that draft. */
     section: string;
   };
+  /**
+   * The kinds of subject a signed-in reader may vote on and flag, by `{type, id}`. Default: items and submissions, which is
+   * what readers could vote on before subject types existed. `story`, `proposal` and `concept` are opt-in.
+   */
+  subjects: { types: (typeof SUBJECT_TYPES)[number][] };
   moderation: {
     /**
      * `human`: new submissions and comments are public at once and wait in the Administration queue (the default for a pilot).
@@ -109,7 +115,7 @@ export type ReaderSteeringConfig = {
   retirementPoll: boolean;
 };
 
-const KNOWN_KEYS = new Set(["name", "computeRoleArn", "dimensions", "limits", "reservedHandles", "karma", "ranking", "snapshot", "retirementPoll", "reservedConcurrency", "hypeGap", "submissions", "comments", "moderation"]);
+const KNOWN_KEYS = new Set(["name", "computeRoleArn", "dimensions", "limits", "reservedHandles", "karma", "ranking", "snapshot", "retirementPoll", "reservedConcurrency", "hypeGap", "submissions", "comments", "moderation", "subjects"]);
 
 function object(raw: unknown, label: string, known: string[]): Record<string, unknown> {
   if (raw === undefined) return {};
@@ -206,6 +212,11 @@ export function resolveReaderSteeringConfig(request: PluginRequest): ReaderSteer
       throw new Error(`reader-steering plugin moderation.ai.model must be a model name matching ${AI_MODEL_NAME}`);
     }
   }
+  const subjects = object(raw.subjects, "subjects", ["types"]);
+  const subjectTypes = subjects.types === undefined ? ["item", "submission"] : subjects.types;
+  if (!Array.isArray(subjectTypes) || subjectTypes.length === 0 || !subjectTypes.every((type) => (SUBJECT_TYPES as readonly unknown[]).includes(type))) {
+    throw new Error(`reader-steering plugin subjects.types must be a non-empty list of: ${SUBJECT_TYPES.join(", ")}`);
+  }
   const kinds = names(submissions.kinds, "submissions.kinds", SUBMISSION_KIND_NAME);
   const comments = object(raw.comments, "comments", ["perHour", "editWindowMinutes", "maximumLength", "maximumLinks"]);
   const hypeGap = resolveHypeGap(raw.hypeGap, dimensions);
@@ -249,6 +260,7 @@ export function resolveReaderSteeringConfig(request: PluginRequest): ReaderSteer
       itemType: lowercaseName(submissions.itemType, "submissions.itemType", "brief"),
       section: lowercaseName(submissions.section, "submissions.section", "unsectioned"),
     },
+    subjects: { types: [...new Set(subjectTypes)] as (typeof SUBJECT_TYPES)[number][] },
     moderation: {
       mode: mode as (typeof MODERATION_MODES)[number],
       preModeration,

package/amplify/plugins/reader-steering/function/handler.py

@@ -30,6 +30,7 @@ if _FUNCTION_DIRECTORY not in sys.path:  # a Lambda already has its code directo
     sys.path.insert(0, _FUNCTION_DIRECTORY)
 import ai_moderation  # noqa: E402
 import moderation as moderation_rules  # noqa: E402
+import proposals as proposal_rules  # noqa: E402
 
 SITE_SUBJECT = re.compile(r"ss1_[A-Za-z0-9_-]{43}")
 INTERIM_SUBJECT = re.compile(r"ssdev_[A-Za-z0-9_-]{43}")
@@ -54,6 +55,21 @@ ACTION_RATING = "rating"
 ACTION_SUBMIT = "submit"
 ACTION_COMMENT = "comment"
 ACTION_REPORT = "report"
+ACTION_FLAG = "flag"
+SUBJECT_TYPE_ITEM = "item"
+SUBJECT_TYPE_SUBMISSION = "submission"
+SUBJECT_TYPES = (SUBJECT_TYPE_ITEM, SUBJECT_TYPE_SUBMISSION, "story", "proposal", "concept")
+DEFAULT_SUBJECT_TYPES = (SUBJECT_TYPE_ITEM, SUBJECT_TYPE_SUBMISSION)
+SUBJECT_ID = re.compile(r"[A-Za-z0-9._:-]{1,190}")
+VOTE_DIMENSION = "up"
+VOTE_PAYLOAD_KEYS = frozenset({"subject", "value"})
+FLAG_WRONG = "wrong"
+FLAG_BELONGS_UNDER = "belongs_under"
+FLAG_BETTER_NAME = "better_name"
+FLAG_KINDS = (FLAG_WRONG, FLAG_BELONGS_UNDER, FLAG_BETTER_NAME)
+FLAG_PAYLOAD_KEYS = frozenset({"subject", "kind", "reason", "target", "name"})
+MAXIMUM_FLAG_REASON = 500
+MAXIMUM_SUGGESTED_NAME = 120
 RATE_BUCKET_REPORT = "report"
 REPORT_ID_PREFIX = "rep-"
 MAXIMUM_REPORT_REASON = 500
@@ -127,6 +143,7 @@ class ReaderSettings:
     promote_section: str = "unsectioned"
     ai_model: str = ai_moderation.DEFAULT_MODEL
     ai_key_parameter: str = ""
+    subject_types: tuple[str, ...] = DEFAULT_SUBJECT_TYPES
 
 
 def settings_from_environment(environment: dict[str, str] | None = None) -> ReaderSettings:
@@ -154,6 +171,7 @@ def settings_from_environment(environment: dict[str, str] | None = None) -> Read
         reports_per_day=int((raw.get("moderation") or {}).get("reportsPerDay", defaults.reports_per_day)),
         ai_model=str(((raw.get("moderation") or {}).get("ai") or {}).get("model", defaults.ai_model)),
         ai_key_parameter=str(((raw.get("moderation") or {}).get("ai") or {}).get("apiKeyParameter", defaults.ai_key_parameter)),
+        subject_types=tuple((raw.get("subjects") or {}).get("types") or defaults.subject_types),
         promote_item_type=str((raw.get("submissions") or {}).get("itemType", defaults.promote_item_type)),
         promote_section=str((raw.get("submissions") or {}).get("section", defaults.promote_section)),
     )
@@ -172,6 +190,8 @@ class ReaderStore(Protocol):
 
     def delete_vote(self, vote_id: str) -> None: ...
 
+    def put_flag(self, flag: dict[str, Any], now_iso: str) -> None: ...
+
     def is_published(self, subject_key: str) -> bool: ...
 
     def get_submission(self, submission_id: str) -> dict[str, Any] | None: ...
@@ -229,6 +249,30 @@ def vote_id(subject_key: str, reader_id: str, dimension: str) -> str:
     return f"{subject_key}#{reader_id}#{dimension}"
 
 
+def subject_key(subject_type: str, subject_id: str) -> str:
+    """The key a vote is stored under: items and submissions keep their bare id (so every vote written before subject types stays valid); other types are prefixed."""
+    return subject_id if subject_type in (SUBJECT_TYPE_ITEM, SUBJECT_TYPE_SUBMISSION) else f"{subject_type}:{subject_id}"
+
+
+def legacy_subject_type(key: str) -> str:
+    """The type of a bare subject key: a submission id, otherwise an item."""
+    return SUBJECT_TYPE_SUBMISSION if SUBMISSION_ID.fullmatch(key) else SUBJECT_TYPE_ITEM
+
+
+def parse_subject(raw: Any, settings: ReaderSettings) -> tuple[tuple[str, str] | None, dict[str, Any] | None]:
+    """``({type, id}) -> (type, id)``, or a refusal. A bare string is a subject written before subject types: its type is read from its shape."""
+    if isinstance(raw, str):
+        raw = {"type": legacy_subject_type(raw), "id": raw}
+    if not isinstance(raw, dict) or set(raw) != {"type", "id"} or not isinstance(raw["type"], str) or not isinstance(raw["id"], str):
+        return None, refusal(422, "invalid_subject", "Send the subject as {type, id}.")
+    subject_type, subject_id = raw["type"], raw["id"]
+    if subject_type not in SUBJECT_TYPES or subject_type not in settings.subject_types:
+        return None, refusal(422, "unknown_subject_type", "That kind of subject cannot be voted on here.")
+    if not SUBJECT_ID.fullmatch(subject_id):
+        return None, refusal(422, "invalid_subject", "Send the id of the subject.")
+    return (subject_type, subject_id), None
+
+
 def valid_site_subject(value: Any, settings: ReaderSettings) -> bool:
     if not isinstance(value, str):
         return False
@@ -321,13 +365,18 @@ def public_profile(profile: dict[str, Any]) -> dict[str, Any]:
 
 
 def my_state(store: ReaderStore, profile: dict[str, Any], payload: dict[str, Any], settings: ReaderSettings) -> dict[str, Any]:
-    subjects = payload.get("subjects", [])
-    if (
-        not isinstance(subjects, list)
-        or len(subjects) > MAXIMUM_SUBJECTS
-        or not all(isinstance(subject, str) and SUBJECT_KEY.fullmatch(subject) for subject in subjects)
-    ):
-        return refusal(422, "invalid_subjects", f"Send at most {MAXIMUM_SUBJECTS} item keys.")
+    raw_subjects = payload.get("subjects", [])
+    if not isinstance(raw_subjects, list) or len(raw_subjects) > MAXIMUM_SUBJECTS:
+        return refusal(422, "invalid_subjects", f"Send at most {MAXIMUM_SUBJECTS} subjects.")
+    subjects: list[str] = []
+    for raw in raw_subjects:
+        if isinstance(raw, str) and SUBJECT_KEY.fullmatch(raw):
+            subjects.append(raw)
+            continue
+        parsed, _ = parse_subject(raw, settings) if isinstance(raw, dict) else (None, None)
+        if parsed is None:
+            return refusal(422, "invalid_subjects", f"Send at most {MAXIMUM_SUBJECTS} subject keys or {{type, id}} subjects.")
+        subjects.append(subject_key(*parsed))
     dimensions = [*TOGGLE_DIMENSIONS, *settings.dimensions]
     wanted = {vote_id(subject, profile["readerId"], dimension): (subject, dimension) for subject in subjects for dimension in dimensions}
     found = store.get_vote_values(list(wanted))
@@ -335,7 +384,9 @@ def my_state(store: ReaderStore, profile: dict[str, Any], payload: dict[str, Any
     for stored_id, value in found.items():
         subject, dimension = wanted[stored_id]
         votes.setdefault(subject, {})[dimension] = value
-    return reply(200, {**public_profile(profile), "votes": votes})
+    # The reader's own up (1) or down (-1) vote per requested subject, by subject key (the key format of items.json).
+    subject_votes = {subject: held["up"] for subject, held in votes.items() if held.get("up") in (1, -1)}
+    return reply(200, {**public_profile(profile), "votes": votes, "subjectVotes": subject_votes})
 
 
 def set_handle(
@@ -375,8 +426,11 @@ def react(
     now_seconds: float,
     schedule_snapshot: Callable[[], None],
 ) -> dict[str, Any]:
-    if not isinstance(subject, str) or not SUBJECT_KEY.fullmatch(subject):
-        return refusal(422, "invalid_subject", "Send the key of a published item.")
+    parsed, refused = parse_subject(subject, settings)
+    if refused:
+        return refused
+    subject_type, subject_id = parsed
+    subject = subject_key(subject_type, subject_id)
     if not isinstance(dimension, str) or dimension not in allowed_dimensions:
         return refusal(422, "invalid_dimension", "That dimension is not available.")
     if profile.get("state") == STATE_BANNED:
@@ -386,7 +440,7 @@ def react(
     limited = within_rate_limit(store, profile, RATE_BUCKET_REACTIONS, action_limit(profile, settings, now_seconds), now_seconds)
     if limited:
         return limited
-    if not subject_is_open(store, subject):
+    if not subject_is_open(store, subject_type, subject_id):
         return refusal(404, "unknown_subject", "That item is not published.")
     stored_id = vote_id(subject, profile["readerId"], dimension)
     if value is None:
@@ -396,6 +450,7 @@ def react(
             {
                 "id": stored_id,
                 "subjectKey": subject,
+                "subjectType": subject_type,
                 "readerId": profile["readerId"],
                 "dimension": dimension,
                 "value": value,
@@ -407,12 +462,17 @@ def react(
     return reply(200, {"subject": subject, "dimension": dimension, "value": value})
 
 
-def subject_is_open(store: ReaderStore, subject: str) -> bool:
-    """A published item, or a submission that is visible (pending or promoted); hidden submissions cannot be voted on."""
-    if SUBMISSION_ID.fullmatch(subject):
-        submission = store.get_submission(subject)
+def subject_is_open(store: ReaderStore, subject_type: str, subject_id: str) -> bool:
+    """A published item, or a submission that is visible (pending or promoted); hidden submissions cannot be voted on.
+
+    The other subject types have no record in this plugin (stories, proposals and concepts live in the site's own data), so any well-formed id is open.
+    """
+    if subject_type == SUBJECT_TYPE_SUBMISSION:
+        submission = store.get_submission(subject_id)
         return submission is not None and submission.get("state") in VISIBLE_SUBMISSION_STATES
-    return store.is_published(subject)
+    if subject_type == SUBJECT_TYPE_ITEM:
+        return store.is_published(subject_id)
+    return True
 
 
 def clean_text(value: Any, label: str, maximum: int, *, required: bool) -> tuple[str | None, dict[str, Any] | None]:
@@ -606,7 +666,7 @@ def comment_action(
     limited = within_rate_limit(store, profile, RATE_BUCKET_COMMENT, new_account_limit(profile, settings, now_seconds, settings.comments_per_hour), now_seconds)
     if limited:
         return limited
-    if not subject_is_open(store, subject):
+    if not subject_is_open(store, legacy_subject_type(subject), subject):
         return refusal(404, "unknown_subject", "That item is not published.")
     if parent_id is not None:
         parent = store.get_comment(parent_id)
@@ -677,6 +737,75 @@ def report_action(
     return reply(200, {"reported": True})
 
 
+def flag_action(
+    store: ReaderStore,
+    profile: dict[str, Any],
+    payload: dict[str, Any],
+    settings: ReaderSettings,
+    is_staff: bool,
+    now_seconds: float,
+    schedule_snapshot: Callable[[], None],
+) -> dict[str, Any]:
+    """A reader flags a subject as wrong, as belonging under another subject, or as needing a better name; a reason is required.
+
+    One flag per reader, subject and kind: flagging again replaces the reason. Flags are stored apart from votes and reach the
+    snapshot as counts only. The stored row holds the readerId, never a siteSubject.
+    """
+    if set(payload) - FLAG_PAYLOAD_KEYS:
+        return refusal(422, "invalid_flag", "Send subject, kind, reason, and target or name for the kind.")
+    kind = payload.get("kind")
+    if kind not in FLAG_KINDS:
+        return refusal(422, "invalid_flag_kind", f"Send kind as one of {', '.join(FLAG_KINDS)}.")
+    parsed, refused = parse_subject(payload.get("subject"), settings)
+    if refused:
+        return refused
+    reason = payload.get("reason")
+    if not isinstance(reason, str) or not reason.strip() or len(reason.strip()) > MAXIMUM_FLAG_REASON or CONTROL_CHARACTERS.search(reason):
+        return refusal(422, "invalid_reason", f"Give a reason in plain text of at most {MAXIMUM_FLAG_REASON} characters.")
+    if EMAIL_ADDRESS.search(reason):
+        return refusal(422, "invalid_reason", "A reason cannot contain an email address.")
+    target_key: str | None = None
+    suggested: str | None = None
+    if kind == FLAG_BELONGS_UNDER:
+        target, refused = parse_subject(payload.get("target"), settings) if isinstance(payload.get("target"), dict) else (None, True)
+        if refused or "name" in payload:
+            return refusal(422, "invalid_target", "Send target as {type, id} for belongs_under.")
+        target_key = subject_key(*target)
+        if target_key == subject_key(*parsed):
+            return refusal(422, "invalid_target", "A subject cannot belong under itself.")
+    elif kind == FLAG_BETTER_NAME:
+        suggested, refused = clean_text(payload.get("name"), "name", MAXIMUM_SUGGESTED_NAME, required=True)
+        if refused or "target" in payload:
+            return refused or refusal(422, "invalid_name", "Send name for better_name.")
+    elif "target" in payload or "name" in payload:
+        return refusal(422, "invalid_flag", "wrong takes only a reason.")
+    if profile.get("state") == STATE_LIMITED:
+        return refusal(403, "reader_limited", "This reader cannot flag right now.")
+    limited = within_rate_limit(store, profile, RATE_BUCKET_REACTIONS, action_limit(profile, settings, now_seconds), now_seconds)
+    if limited:
+        return limited
+    subject_type, subject_id = parsed
+    if not subject_is_open(store, subject_type, subject_id):
+        return refusal(404, "unknown_subject", "That subject cannot be flagged.")
+    key = subject_key(subject_type, subject_id)
+    store.put_flag(
+        {
+            "id": f"{key}#{profile['readerId']}#{kind}",
+            "subjectKey": key,
+            "subjectType": subject_type,
+            "readerId": profile["readerId"],
+            "kind": kind,
+            "reason": reason.strip(),
+            "targetKey": target_key,
+            "suggestedName": suggested,
+            "voterRole": ROLE_EDITOR if is_staff else ROLE_READER,
+        },
+        iso(now_seconds),
+    )
+    schedule_snapshot()
+    return reply(200, {"subject": payload["subject"], "kind": kind})
+
+
 def own_comment(store: ReaderStore, profile: dict[str, Any], payload: dict[str, Any], allowed: frozenset[str]) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
     if set(payload) - allowed:
         return None, refusal(422, "invalid_comment", "Send only " + ", ".join(sorted(allowed)) + ".")
@@ -740,7 +869,23 @@ def delete_comment_action(
     return reply(200, {"id": comment["id"], "state": COMMENT_DELETED})
 
 
+def typed_vote_action(store, profile, payload, settings, is_staff, now_seconds, schedule_snapshot):
+    """``{subject: {type, id}, value: 1 | -1 | null}``: an up or down vote on any enabled subject type; ``null`` removes the reader's vote."""
+    value = payload.get("value")
+    if set(payload) - VOTE_PAYLOAD_KEYS or isinstance(value, bool) or value not in (1, -1, None):
+        return refusal(422, "invalid_vote", "Send only subject and value, and value as 1, -1 or null.")
+    answer = react(
+        store, profile, subject=payload.get("subject"), dimension=VOTE_DIMENSION, allowed_dimensions=(VOTE_DIMENSION,),
+        value=value, is_staff=is_staff, settings=settings, now_seconds=now_seconds, schedule_snapshot=schedule_snapshot,
+    )
+    if answer["statusCode"] == 200:
+        answer = reply(200, {"subject": payload["subject"], "value": value})
+    return answer
+
+
 def vote_action(store, profile, payload, settings, is_staff, now_seconds, schedule_snapshot):
+    if isinstance(payload.get("subject"), dict):
+        return typed_vote_action(store, profile, payload, settings, is_staff, now_seconds, schedule_snapshot)
     on = payload.get("on")
     if not isinstance(on, bool):
         return refusal(422, "invalid_vote", "Send on as true or false.")
@@ -794,6 +939,8 @@ def handle_event(
         return delete_comment_action(store, profile, payload, settings, now_seconds, schedule_snapshot)
     if action == ACTION_REPORT:
         return report_action(store, profile, payload, settings, now_seconds, schedule_snapshot)
+    if action == ACTION_FLAG:
+        return flag_action(store, profile, payload, settings, event["isStaff"], now_seconds, schedule_snapshot)
     return refusal(400, "unknown_action", "Unknown action.")
 
 
@@ -832,6 +979,8 @@ class DynamoReaderStore:
         report_table: str = "",
         action_table: str = "",
         item_table: str = "",
+        proposal_table: str = "",
+        flag_table: str = "",
     ) -> None:
         self._resource = resource
         self._names = {
@@ -845,11 +994,45 @@ class DynamoReaderStore:
             "report": report_table,
             "action": action_table,
             "item": item_table,
+            "proposal": proposal_table,
+            "flag": flag_table,
         }
 
     def _table(self, key: str) -> Any:
         return self._resource.Table(self._names[key])
 
+    def get_proposal(self, proposal_id: str) -> dict[str, Any] | None:
+        item = self._table("proposal").get_item(Key={"id": proposal_id}, ConsistentRead=True).get("Item")
+        return plain(item) if item else None
+
+    def create_proposal(self, row: dict[str, Any]) -> bool:
+        item = {**_without_none(row), "__typename": "Proposal", "updatedAt": row["createdAt"]}
+        try:
+            self._table("proposal").put_item(Item=item, ConditionExpression="attribute_not_exists(id)")
+        except Exception as error:
+            if is_conditional_failure(error):
+                return False
+            raise
+        return True
+
+    def change_proposal(self, proposal_id: str, changes: dict[str, Any], expected_state: str, now_iso: str) -> bool:
+        names = {"#st": "state", "#u": "updatedAt", **{f"#c{index}": key for index, key in enumerate(changes)}}
+        assignments = ", ".join(f"#c{index} = :c{index}" for index in range(len(changes)))
+        values = {":expected": expected_state, ":now": now_iso, **{f":c{index}": value for index, value in enumerate(changes.values())}}
+        try:
+            self._table("proposal").update_item(
+                Key={"id": proposal_id},
+                UpdateExpression=f"SET {assignments}, #u = :now",
+                ConditionExpression="#st = :expected",
+                ExpressionAttributeNames=names,
+                ExpressionAttributeValues=values,
+            )
+        except Exception as error:
+            if is_conditional_failure(error):
+                return False
+            raise
+        return True
+
     def get_profile(self, site_subject: str) -> dict[str, Any] | None:
         item = self._table("profile").get_item(Key={"id": site_subject}, ConsistentRead=True).get("Item")
         return plain(item) if item else None
@@ -914,13 +1097,14 @@ class DynamoReaderStore:
         self._table("vote").update_item(
             Key={"id": vote["id"]},
             UpdateExpression=(
-                "SET #t = :t, subjectKey = :s, readerId = :r, #d = :d, #v = :v, voterRole = :role, "
+                "SET #t = :t, subjectKey = :s, subjectType = :st, readerId = :r, #d = :d, #v = :v, voterRole = :role, "
                 "createdAt = if_not_exists(createdAt, :now), updatedAt = :now"
             ),
             ExpressionAttributeNames={"#t": "__typename", "#d": "dimension", "#v": "value"},
             ExpressionAttributeValues={
                 ":t": "ReaderVote",
                 ":s": vote["subjectKey"],
+                ":st": vote.get("subjectType") or legacy_subject_type(vote["subjectKey"]),
                 ":r": vote["readerId"],
                 ":d": vote["dimension"],
                 ":v": vote["value"],
@@ -932,6 +1116,9 @@ class DynamoReaderStore:
     def delete_vote(self, vote_id_: str) -> None:
         self._table("vote").delete_item(Key={"id": vote_id_})
 
+    def put_flag(self, flag: dict[str, Any], now_iso: str) -> None:
+        self._table("flag").put_item(Item=_without_none({**flag, "__typename": "ReaderFlag", "createdAt": now_iso, "updatedAt": now_iso}))
+
     def is_published(self, subject_key: str) -> bool:
         item = self._table("published").get_item(Key={"id": PUBLISHED_ID_PREFIX + subject_key}, ProjectionExpression="#s", ExpressionAttributeNames={"#s": "status"}).get("Item")
         return bool(item) and item.get("status") == "published"
@@ -1259,6 +1446,8 @@ def store_from_environment(environment: dict[str, str] | None = None) -> DynamoR
         report_table=environment.get("PAPYRUS_READER_REPORT_TABLE", ""),
         action_table=environment.get("PAPYRUS_READER_ACTION_TABLE", ""),
         item_table=environment.get("PAPYRUS_READER_ITEM_TABLE", ""),
+        proposal_table=environment.get("PAPYRUS_READER_PROPOSAL_TABLE", ""),
+        flag_table=environment.get("PAPYRUS_READER_FLAG_TABLE", ""),
     )
 
 
@@ -1312,6 +1501,8 @@ def run_ai_worker(
 
 def handle_staff_event(event: dict[str, Any], *, store: Any, settings: ReaderSettings, now_seconds: float) -> dict[str, Any]:
     """``moderateReader`` from AppSync: an editor or admin hides, approves, promotes, bans or undoes. Answers a receipt, never an exception."""
+    if (event.get("info") or {}).get("fieldName") in proposal_rules.MUTATIONS:
+        return proposal_rules.handle_proposal_event(event, store, now_iso=iso(now_seconds))
     identity = event.get("identity") or {}
     claims = identity.get("claims") or {}
     groups = claims.get("cognito:groups") or identity.get("groups") or []

package/amplify/plugins/reader-steering/function/proposals.py

@@ -0,0 +1,255 @@
+"""The proposal record: what may be filed, which state changes are allowed, and who may make them.
+
+A proposal is a change to the map written down where readers can see it: a story draft, a new concept, a rename, a merge,
+a split, a new column or an element symbol. It is filed by AI (a reader proposer is part of the record but has no route yet)
+and steered by votes; an editor decides. Staff reach this through the ``fileProposal`` and ``transitionProposal``
+mutations (editors and admins only; the function checks the groups again). Every state change is appended to the proposal's
+``history`` in the same conditional write that changes the state, so the history and the state cannot disagree.
+
+Nothing here knows a person id. The proposer is ``"ai"`` or a reader's siteSubject, which is stored and never published; the
+actor of a change is the staff member's Cognito subject, which is stored and never published either (the public file shows
+"AI" or "Editor"). Votes are not counted here: they belong to the vote model and the snapshot joins them.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+KINDS = ("story_draft", "new_concept", "rename", "merge", "split", "new_column", "element_symbol")
+DRAFT, IN_STEERING, EDITOR_REVIEW, APPROVED, DECLINED, OVERRIDDEN_BY_EDITOR = (
+    "draft",
+    "in_steering",
+    "editor_review",
+    "approved",
+    "declined",
+    "overridden_by_editor",
+)
+STATES = (DRAFT, IN_STEERING, EDITOR_REVIEW, APPROVED, DECLINED, OVERRIDDEN_BY_EDITOR)
+
+#: Every allowed state change. Anything not listed is refused. Approved, declined and overridden are final.
+TRANSITIONS: dict[str, tuple[str, ...]] = {
+    DRAFT: (IN_STEERING, DECLINED),
+    IN_STEERING: (EDITOR_REVIEW,),
+    EDITOR_REVIEW: (APPROVED, DECLINED, OVERRIDDEN_BY_EDITOR),
+}
+#: The changes that need a reason. Every reason is public; this one is also required, because it explains a decision against the community.
+REASON_REQUIRED = frozenset({OVERRIDDEN_BY_EDITOR})
+#: An override says what the editor decided against the community's view: approved or declined. Approve and decline are their own result.
+OVERRIDE_RESULTS = (APPROVED, DECLINED)
+
+#: How many target subjects each kind names, as (minimum, maximum), and the types a target may have.
+TARGET_COUNTS: dict[str, tuple[int, int]] = {
+    "story_draft": (0, 10),
+    "new_concept": (0, 10),
+    "rename": (1, 1),
+    "merge": (2, 10),
+    "split": (1, 1),
+    "new_column": (0, 10),
+    "element_symbol": (1, 1),
+}
+TARGET_TYPES = ("concept", "entity", "column", "story", "cluster")
+
+MUTATIONS = ("fileProposal", "transitionProposal")
+PROPOSER_AI = "ai"
+STAFF_GROUPS = frozenset({"editor", "admin"})
+PROPOSAL_ID = re.compile(r"prop-[0-9a-f]{32}")
+TARGET_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.:\-]{0,127}")
+MAXIMUM_TITLE = 200
+MAXIMUM_SUMMARY = 300
+MAXIMUM_BODY = 50_000
+MAXIMUM_REASON = 500
+MAXIMUM_EVIDENCE_SOURCE = 200
+MAXIMUM_EVIDENCE_SIGNALS = 1_000_000
+
+
+@dataclass
+class Outcome:
+    status: str  # "ok" or "refused"
+    id: str | None = None
+    error: str | None = None
+    message: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"status": self.status, "id": self.id, "error": self.error, "message": self.message}
+
+
+def refused(error: str, message: str) -> Outcome:
+    return Outcome("refused", error=error, message=message)
+
+
+class ProposalStore(Protocol):
+    def get_proposal(self, proposal_id: str) -> dict[str, Any] | None: ...
+
+    def create_proposal(self, row: dict[str, Any]) -> bool: ...
+
+    def change_proposal(self, proposal_id: str, changes: dict[str, Any], expected_state: str, now_iso: str) -> bool: ...
+
+
+def staff_subject(identity: dict[str, Any]) -> str | None:
+    """The Cognito subject of an editor or admin, or ``None`` for anyone else."""
+    claims = identity.get("claims") or {}
+    groups = claims.get("cognito:groups") or identity.get("groups") or []
+    if isinstance(groups, str):
+        groups = [group.strip() for group in groups.strip("[]").replace(",", " ").split()]
+    subject = identity.get("sub")
+    if not isinstance(subject, str) or not subject or not STAFF_GROUPS.intersection(groups):
+        return None
+    return subject
+
+
+def clean_text(value: Any, limit: int) -> str | None:
+    if not isinstance(value, str):
+        return None
+    text = value.strip()
+    return text if text and len(text) <= limit else None
+
+
+def parse_json(value: Any) -> Any:
+    """AppSync delivers AWSJSON arguments as strings; the CLI and tests may pass the parsed value."""
+    if isinstance(value, str):
+        try:
+            return json.loads(value)
+        except ValueError:
+            return None
+    return value
+
+
+def clean_targets(kind: str, raw: Any) -> list[dict[str, str]] | Outcome:
+    parsed = parse_json(raw) if raw is not None else []
+    if not isinstance(parsed, list):
+        return refused("invalid_targets", "targets must be a list of {type, id}.")
+    minimum, maximum = TARGET_COUNTS[kind]
+    targets: list[dict[str, str]] = []
+    for entry in parsed:
+        if not isinstance(entry, dict) or entry.get("type") not in TARGET_TYPES or not isinstance(entry.get("id"), str) or not TARGET_ID.fullmatch(entry["id"]):
+            return refused("invalid_targets", f"Each target is {{type, id}} with a type of {', '.join(TARGET_TYPES)}.")
+        target = {"type": entry["type"], "id": entry["id"]}
+        if target in targets:
+            return refused("invalid_targets", "A target is named twice.")
+        targets.append(target)
+    if not minimum <= len(targets) <= maximum:
+        wanted = f"{minimum}" if minimum == maximum else f"{minimum} to {maximum}"
+        return refused("invalid_targets", f"A {kind} proposal names {wanted} target(s).")
+    return targets
+
+
+def clean_evidence(raw: Any) -> dict[str, Any] | None | Outcome:
+    parsed = parse_json(raw) if raw is not None else None
+    if parsed is None:
+        return None
+    if not isinstance(parsed, dict):
+        return refused("invalid_evidence", "evidence must be {signals, source}.")
+    signals, source = parsed.get("signals"), parsed.get("source")
+    if not isinstance(signals, int) or isinstance(signals, bool) or not 0 <= signals <= MAXIMUM_EVIDENCE_SIGNALS:
+        return refused("invalid_evidence", "evidence.signals must be a whole number of signals.")
+    if source is not None and clean_text(source, MAXIMUM_EVIDENCE_SOURCE) is None:
+        return refused("invalid_evidence", "evidence.source must be short text.")
+    return {"signals": signals, "source": source.strip() if isinstance(source, str) else None}
+
+
+def file_proposal(arguments: dict[str, Any], *, actor_sub: str, now_iso: str, proposal_id: str | None = None) -> tuple[dict[str, Any] | None, Outcome | None]:
+    """The new row for a proposal in ``draft``, or the refusal. The proposer is AI: reader filing has no route yet."""
+    kind = arguments.get("kind")
+    if kind not in KINDS:
+        return None, refused("invalid_kind", f"kind must be one of {', '.join(KINDS)}.")
+    title = clean_text(arguments.get("title"), MAXIMUM_TITLE)
+    if title is None:
+        return None, refused("invalid_title", f"A proposal needs a title of at most {MAXIMUM_TITLE} characters.")
+    body = arguments.get("body")  # Markus source, kept byte for byte
+    if not isinstance(body, str) or not body.strip() or len(body) > MAXIMUM_BODY:
+        return None, refused("invalid_body", "A proposal needs a body (Markus), at most 50,000 characters.")
+    summary = arguments.get("summary")
+    if summary is not None and clean_text(summary, MAXIMUM_SUMMARY) is None:
+        return None, refused("invalid_summary", f"summary is one line of at most {MAXIMUM_SUMMARY} characters.")
+    targets = clean_targets(kind, arguments.get("targets"))
+    if isinstance(targets, Outcome):
+        return None, targets
+    evidence = clean_evidence(arguments.get("evidence"))
+    if isinstance(evidence, Outcome):
+        return None, evidence
+    identifier = proposal_id or "prop-" + uuid.uuid4().hex
+    row: dict[str, Any] = {
+        "id": identifier,
+        "kind": kind,
+        "title": title,
+        "body": body,
+        "targets": json.dumps(targets),
+        "proposer": PROPOSER_AI,
+        "state": DRAFT,
+        "history": json.dumps([{"from": None, "to": DRAFT, "by": "ai", "actor": actor_sub, "reason": None, "at": now_iso}]),
+        "createdAt": now_iso,
+    }
+    if summary is not None:
+        row["summary"] = summary.strip()
+    if evidence is not None:
+        row["evidence"] = json.dumps(evidence)
+    return row, None
+
+
+def transition_plan(row: dict[str, Any], to_state: Any, reason: Any, *, actor_sub: str, now_iso: str, result: Any = None) -> dict[str, Any] | Outcome:
+    """The changes that move ``row`` to ``to_state``, or why it may not move."""
+    state = row.get("state")
+    if to_state not in STATES:
+        return refused("invalid_state", f"state must be one of {', '.join(STATES)}.")
+    if to_state not in TRANSITIONS.get(state, ()):
+        return refused("transition_not_allowed", f"A proposal in {state} cannot move to {to_state}.")
+    text = None
+    if reason is not None and str(reason).strip():
+        text = clean_text(reason, MAXIMUM_REASON)
+        if text is None:
+            return refused("invalid_reason", f"A reason is plain text of at most {MAXIMUM_REASON} characters.")
+    if to_state in REASON_REQUIRED and text is None:
+        return refused("reason_required", "Overriding the community needs a public reason.")
+    if to_state == OVERRIDDEN_BY_EDITOR:
+        if result not in OVERRIDE_RESULTS:
+            return refused("result_required", f"An override says what the editor decided: {' or '.join(OVERRIDE_RESULTS)}.")
+    elif result is not None:
+        return refused("result_not_allowed", "Only an override carries a result; approve and decline are their own.")
+    entry = {"from": state, "to": to_state, "by": "staff", "actor": actor_sub, "reason": text, "at": now_iso}
+    if result is not None:
+        entry["result"] = result
+    history = [*(parse_json(row.get("history")) or []), entry]
+    return {"state": to_state, "history": json.dumps(history)}
+
+
+def apply_transition(store: ProposalStore, *, proposal_id: Any, to_state: Any, reason: Any, actor_sub: str, now_iso: str, result: Any = None) -> Outcome:
+    if not isinstance(proposal_id, str) or not PROPOSAL_ID.fullmatch(proposal_id):
+        return refused("invalid_proposal", "That is not a proposal id.")
+    row = store.get_proposal(proposal_id)
+    if row is None:
+        return refused("not_found", "There is no such proposal.")
+    plan = transition_plan(row, to_state, reason, actor_sub=actor_sub, now_iso=now_iso, result=result)
+    if isinstance(plan, Outcome):
+        return plan
+    if not store.change_proposal(proposal_id, plan, row["state"], now_iso):
+        return refused("target_changed", "Someone else changed that proposal first.")
+    return Outcome("ok", id=proposal_id)
+
+
+def handle_proposal_event(event: dict[str, Any], store: ProposalStore, *, now_iso: str) -> dict[str, Any]:
+    """``fileProposal`` or ``transitionProposal`` from AppSync. Answers a receipt, never an exception."""
+    actor = staff_subject(event.get("identity") or {})
+    if actor is None:
+        return refused("not_staff", "Only editors and admins can file or decide proposals.").to_dict()
+    arguments = event.get("arguments") or {}
+    field = (event.get("info") or {}).get("fieldName")
+    if field == "fileProposal":
+        row, problem = file_proposal(arguments, actor_sub=actor, now_iso=now_iso)
+        if problem is not None:
+            return problem.to_dict()
+        if not store.create_proposal(row):
+            return refused("exists", "That proposal already exists.").to_dict()
+        return Outcome("ok", id=row["id"]).to_dict()
+    return apply_transition(
+        store,
+        proposal_id=arguments.get("proposalId"),
+        to_state=arguments.get("state"),
+        reason=arguments.get("reason"),
+        result=arguments.get("result"),
+        actor_sub=actor,
+        now_iso=now_iso,
+    ).to_dict()

package/amplify/plugins/reader-steering/papyrus.plugin.js

@@ -14,8 +14,8 @@ export const READER_POLL_SECRET_PARAMETER_ENV = "PAPYRUS_READER_POLL_SECRET_PARA
 export const readerSteeringManifest = {
     name: "reader-steering",
     contract: 1,
-    models: ["ReaderProfile", "ReaderHandle", "ReaderVote", "ReaderSubmission", "ReaderComment", "ReaderReport", "ModerationAction"],
-    mutations: ["moderateReader"],
+    models: ["ReaderProfile", "ReaderHandle", "ReaderVote", "ReaderFlag", "ReaderSubmission", "ReaderComment", "ReaderReport", "ModerationAction", "Proposal"],
+    mutations: ["moderateReader", "fileProposal", "transitionProposal"],
     guest: { mutations: [] },
     newsroomPanels: [{ id: "moderation", label: "Moderation" }],
     staticAssets: ["_plugins/papyrus-reader@1.js", "_plugins/papyrus-reader@1.css"],
@@ -26,6 +26,7 @@ export function readerActionsSettings(config, allowInterimSubjects) {
         dimensions: config.dimensions,
         limits: config.limits,
         submissions: config.submissions,
+        subjects: config.subjects,
         comments: config.comments,
         moderation: config.moderation,
         reservedHandles: config.reservedHandles,
@@ -38,6 +39,7 @@ export function readerSnapshotSettings(config) {
     return {
         dimensions: config.dimensions,
         submissions: config.submissions,
+        subjects: config.subjects,
         karma: config.karma,
         ranking: config.ranking,
         limits: { newAccountHours: config.limits.newAccountHours },
@@ -100,6 +102,7 @@ export const readerSteeringPlugin = {
     publicSettings: (config) => ({
         contract: readerSteeringManifest.contract,
         dimensions: config.dimensions,
+        subjects: { types: config.subjects.types },
         moderation: { mode: config.moderation.mode },
     }),
     wire(backend, config, context) {
@@ -110,10 +113,12 @@ export const readerSteeringPlugin = {
             ["PAPYRUS_READER_PROFILE_TABLE", "ReaderProfile"],
             ["PAPYRUS_READER_HANDLE_TABLE", "ReaderHandle"],
             ["PAPYRUS_READER_VOTE_TABLE", "ReaderVote"],
+            ["PAPYRUS_READER_FLAG_TABLE", "ReaderFlag"],
             ["PAPYRUS_READER_SUBMISSION_TABLE", "ReaderSubmission"],
             ["PAPYRUS_READER_COMMENT_TABLE", "ReaderComment"],
             ["PAPYRUS_READER_REPORT_TABLE", "ReaderReport"],
             ["PAPYRUS_READER_ACTION_TABLE", "ModerationAction"],
+            ["PAPYRUS_READER_PROPOSAL_TABLE", "Proposal"],
         ]) {
             tables[model].grantReadWriteData(lambda);
             lambda.addEnvironment(variable, tables[model].tableName);
@@ -125,10 +130,13 @@ export const readerSteeringPlugin = {
         tables.PublishedItem.grantReadData(lambda);
         lambda.addEnvironment("PAPYRUS_READER_PUBLISHED_ITEM_TABLE", tables.PublishedItem.tableName);
         tables.ReaderVote.grantReadData(contentActions);
+        tables.ReaderFlag.grantReadData(contentActions);
         tables.ReaderProfile.grantReadWriteData(contentActions);
         // The snapshot reads submissions, and the review step writes their signals and moderation state.
         tables.ReaderSubmission.grantReadWriteData(contentActions);
         tables.ReaderComment.grantReadWriteData(contentActions);
+        // The snapshot reads proposals and freezes the community result of one that reaches editor review.
+        tables.Proposal.grantReadWriteData(contentActions);
         lambda.addEnvironment("PAPYRUS_READER_SETTINGS", JSON.stringify(readerActionsSettings(config, interimSubjectsAllowedAtSynth())));
         if (config.reservedConcurrency !== undefined) {
             lambda.node.defaultChild.addPropertyOverride("ReservedConcurrentExecutions", config.reservedConcurrency);

package/amplify/plugins/reader-steering/papyrus.plugin.ts

@@ -21,8 +21,8 @@ export const READER_POLL_SECRET_PARAMETER_ENV = "PAPYRUS_READER_POLL_SECRET_PARA
 export const readerSteeringManifest: PluginManifest = {
   name: "reader-steering",
   contract: 1,
-  models: ["ReaderProfile", "ReaderHandle", "ReaderVote", "ReaderSubmission", "ReaderComment", "ReaderReport", "ModerationAction"],
-  mutations: ["moderateReader"],
+  models: ["ReaderProfile", "ReaderHandle", "ReaderVote", "ReaderFlag", "ReaderSubmission", "ReaderComment", "ReaderReport", "ModerationAction", "Proposal"],
+  mutations: ["moderateReader", "fileProposal", "transitionProposal"],
   guest: { mutations: [] },
   newsroomPanels: [{ id: "moderation", label: "Moderation" }],
   staticAssets: ["_plugins/papyrus-reader@1.js", "_plugins/papyrus-reader@1.css"],
@@ -34,6 +34,7 @@ export function readerActionsSettings(config: ReaderSteeringConfig, allowInterim
     dimensions: config.dimensions,
     limits: config.limits,
     submissions: config.submissions,
+    subjects: config.subjects,
     comments: config.comments,
     moderation: config.moderation,
     reservedHandles: config.reservedHandles,
@@ -47,6 +48,7 @@ export function readerSnapshotSettings(config: ReaderSteeringConfig) {
   return {
     dimensions: config.dimensions,
     submissions: config.submissions,
+    subjects: config.subjects,
     karma: config.karma,
     ranking: config.ranking,
     limits: { newAccountHours: config.limits.newAccountHours },
@@ -118,6 +120,7 @@ export const readerSteeringPlugin: PapyrusPlugin<ReaderSteeringConfig, { readerA
   publicSettings: (config) => ({
     contract: readerSteeringManifest.contract,
     dimensions: config.dimensions,
+    subjects: { types: config.subjects.types },
     moderation: { mode: config.moderation.mode },
   }),
   wire(backend, config, context: PluginWiringContext) {
@@ -129,10 +132,12 @@ export const readerSteeringPlugin: PapyrusPlugin<ReaderSteeringConfig, { readerA
       ["PAPYRUS_READER_PROFILE_TABLE", "ReaderProfile"],
       ["PAPYRUS_READER_HANDLE_TABLE", "ReaderHandle"],
       ["PAPYRUS_READER_VOTE_TABLE", "ReaderVote"],
+      ["PAPYRUS_READER_FLAG_TABLE", "ReaderFlag"],
       ["PAPYRUS_READER_SUBMISSION_TABLE", "ReaderSubmission"],
       ["PAPYRUS_READER_COMMENT_TABLE", "ReaderComment"],
       ["PAPYRUS_READER_REPORT_TABLE", "ReaderReport"],
       ["PAPYRUS_READER_ACTION_TABLE", "ModerationAction"],
+      ["PAPYRUS_READER_PROPOSAL_TABLE", "Proposal"],
     ] as const) {
       tables[model].grantReadWriteData(lambda);
       lambda.addEnvironment(variable, tables[model].tableName);
@@ -144,10 +149,13 @@ export const readerSteeringPlugin: PapyrusPlugin<ReaderSteeringConfig, { readerA
     tables.PublishedItem.grantReadData(lambda);
     lambda.addEnvironment("PAPYRUS_READER_PUBLISHED_ITEM_TABLE", tables.PublishedItem.tableName);
     tables.ReaderVote.grantReadData(contentActions);
+    tables.ReaderFlag.grantReadData(contentActions);
     tables.ReaderProfile.grantReadWriteData(contentActions);
     // The snapshot reads submissions, and the review step writes their signals and moderation state.
     tables.ReaderSubmission.grantReadWriteData(contentActions);
     tables.ReaderComment.grantReadWriteData(contentActions);
+    // The snapshot reads proposals and freezes the community result of one that reaches editor review.
+    tables.Proposal.grantReadWriteData(contentActions);
 
     lambda.addEnvironment("PAPYRUS_READER_SETTINGS", JSON.stringify(readerActionsSettings(config, interimSubjectsAllowedAtSynth())));
     if (config.reservedConcurrency !== undefined) {

package/amplify/plugins/reader-steering/schema.js

@@ -3,7 +3,7 @@ import { readerActions } from "./function/resource.js";
 /**
  * Staff and IAM only: no guest, API key or reader rule on any model. The reader-actions function writes the
  * tables directly with its own role, and editors may list them; admins may delete. `id` is the lookup key:
- * the siteSubject for a profile, the lowercase handle for a claim, `subjectKey#readerId#dimension` for a vote and
+ * the siteSubject for a profile, the lowercase handle for a claim, `subjectKey#readerId#dimension` for a vote (`subjectKey#readerId#kind` for a flag; the key is the bare id for items and submissions and `type:id` for the rest) and
  * `sub-<sha256 of the canonical URL>` for a submission (so a canonical URL is one submission).
  */
 const staffOnly = (allow) => [allow.group("editor").to(["read"]), allow.group("admin").to(["read", "delete"])];
@@ -32,6 +32,7 @@ export function readerSteeringSchemaDefinitions() {
             .model({
             id: a.id().required(),
             subjectKey: a.string().required(),
+            subjectType: a.string(),
             readerId: a.string().required(),
             dimension: a.string().required(),
             value: a.integer().required(),
@@ -39,6 +40,21 @@ export function readerSteeringSchemaDefinitions() {
         })
             .disableOperations(["subscriptions"])
             .authorization(staffOnly),
+        ReaderFlag: a
+            .model({
+            id: a.id().required(),
+            subjectKey: a.string().required(),
+            subjectType: a.string().required(),
+            readerId: a.string().required(),
+            kind: a.string().required(),
+            reason: a.string().required(),
+            targetKey: a.string(),
+            suggestedName: a.string(),
+            voterRole: a.string().required(),
+            createdAt: a.datetime().required(),
+        })
+            .disableOperations(["subscriptions"])
+            .authorization(staffOnly),
         ReaderComment: a
             .model({
             id: a.id().required(),
@@ -118,6 +134,54 @@ export function readerSteeringSchemaDefinitions() {
             .disableOperations(["subscriptions"])
             .secondaryIndexes((index) => [index("target").sortKeys(["at"]).name("actionsByTarget").queryField("listModerationActionsByTargetAndAt")])
             .authorization(staffOnly),
+        Proposal: a
+            .model({
+            id: a.id().required(),
+            kind: a.string().required(),
+            title: a.string().required(),
+            summary: a.string(),
+            body: a.string().required(),
+            targets: a.json().required(),
+            evidence: a.json(),
+            proposer: a.string().required(),
+            state: a.string().required(),
+            history: a.json().required(),
+            communityResult: a.json(),
+            createdAt: a.datetime().required(),
+        })
+            .disableOperations(["subscriptions"])
+            .secondaryIndexes((index) => [index("state").sortKeys(["createdAt"]).name("proposalsByState").queryField("listProposalsByStateAndCreatedAt")])
+            .authorization(staffOnly),
+        ProposalReceipt: a.customType({
+            status: a.string().required(),
+            id: a.string(),
+            error: a.string(),
+            message: a.string(),
+        }),
+        fileProposal: a
+            .mutation()
+            .arguments({
+            kind: a.string().required(),
+            title: a.string().required(),
+            body: a.string().required(),
+            summary: a.string(),
+            targets: a.json(),
+            evidence: a.json(),
+        })
+            .returns(a.ref("ProposalReceipt"))
+            .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+            .handler(a.handler.function(readerActions)),
+        transitionProposal: a
+            .mutation()
+            .arguments({
+            proposalId: a.string().required(),
+            state: a.string().required(),
+            reason: a.string(),
+            result: a.string(),
+        })
+            .returns(a.ref("ProposalReceipt"))
+            .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+            .handler(a.handler.function(readerActions)),
         ModerationReceipt: a.customType({
             status: a.string().required(),
             id: a.string(),

package/amplify/plugins/reader-steering/schema.ts

@@ -4,7 +4,7 @@ import { readerActions } from "./function/resource";
 /**
  * Staff and IAM only: no guest, API key or reader rule on any model. The reader-actions function writes the
  * tables directly with its own role, and editors may list them; admins may delete. `id` is the lookup key:
- * the siteSubject for a profile, the lowercase handle for a claim, `subjectKey#readerId#dimension` for a vote and
+ * the siteSubject for a profile, the lowercase handle for a claim, `subjectKey#readerId#dimension` for a vote (`subjectKey#readerId#kind` for a flag; the key is the bare id for items and submissions and `type:id` for the rest) and
  * `sub-<sha256 of the canonical URL>` for a submission (so a canonical URL is one submission).
  */
 const staffOnly = (allow: any) => [allow.group("editor").to(["read"]), allow.group("admin").to(["read", "delete"])];
@@ -34,6 +34,7 @@ export function readerSteeringSchemaDefinitions() {
       .model({
         id: a.id().required(),
         subjectKey: a.string().required(),
+        subjectType: a.string(),
         readerId: a.string().required(),
         dimension: a.string().required(),
         value: a.integer().required(),
@@ -41,6 +42,21 @@ export function readerSteeringSchemaDefinitions() {
       })
       .disableOperations(["subscriptions"])
       .authorization(staffOnly),
+    ReaderFlag: a
+      .model({
+        id: a.id().required(),
+        subjectKey: a.string().required(),
+        subjectType: a.string().required(),
+        readerId: a.string().required(),
+        kind: a.string().required(),
+        reason: a.string().required(),
+        targetKey: a.string(),
+        suggestedName: a.string(),
+        voterRole: a.string().required(),
+        createdAt: a.datetime().required(),
+      })
+      .disableOperations(["subscriptions"])
+      .authorization(staffOnly),
     ReaderComment: a
       .model({
         id: a.id().required(),
@@ -120,6 +136,54 @@ export function readerSteeringSchemaDefinitions() {
       .disableOperations(["subscriptions"])
       .secondaryIndexes((index) => [index("target").sortKeys(["at"]).name("actionsByTarget").queryField("listModerationActionsByTargetAndAt")])
       .authorization(staffOnly),
+    Proposal: a
+      .model({
+        id: a.id().required(),
+        kind: a.string().required(),
+        title: a.string().required(),
+        summary: a.string(),
+        body: a.string().required(),
+        targets: a.json().required(),
+        evidence: a.json(),
+        proposer: a.string().required(),
+        state: a.string().required(),
+        history: a.json().required(),
+        communityResult: a.json(),
+        createdAt: a.datetime().required(),
+      })
+      .disableOperations(["subscriptions"])
+      .secondaryIndexes((index) => [index("state").sortKeys(["createdAt"]).name("proposalsByState").queryField("listProposalsByStateAndCreatedAt")])
+      .authorization(staffOnly),
+    ProposalReceipt: a.customType({
+      status: a.string().required(),
+      id: a.string(),
+      error: a.string(),
+      message: a.string(),
+    }),
+    fileProposal: a
+      .mutation()
+      .arguments({
+        kind: a.string().required(),
+        title: a.string().required(),
+        body: a.string().required(),
+        summary: a.string(),
+        targets: a.json(),
+        evidence: a.json(),
+      })
+      .returns(a.ref("ProposalReceipt"))
+      .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+      .handler(a.handler.function(readerActions)),
+    transitionProposal: a
+      .mutation()
+      .arguments({
+        proposalId: a.string().required(),
+        state: a.string().required(),
+        reason: a.string(),
+        result: a.string(),
+      })
+      .returns(a.ref("ProposalReceipt"))
+      .authorization((allow) => [allow.group("editor"), allow.group("admin")])
+      .handler(a.handler.function(readerActions)),
     ModerationReceipt: a.customType({
       status: a.string().required(),
       id: a.string(),

package/app/api/reader/flag/route.ts

@@ -0,0 +1,9 @@
+import type { NextRequest } from "next/server";
+import { handleReaderRequest } from "../../../../lib/reader-api";
+
+export const dynamic = "force-dynamic";
+export const runtime = "nodejs";
+
+export function POST(request: NextRequest) {
+  return handleReaderRequest(request, "flag");
+}

package/lib/reader-api.ts

@@ -12,7 +12,7 @@ export const READER_BODY_BYTES_BY_ACTION: Partial<Record<ReaderAction, number>>
 export const READER_MAXIMUM_SUBJECTS = 50;
 export const READER_SUBJECT_KEY = /^[A-Za-z0-9._:-]{1,200}$/;
 
-export type ReaderAction = "me" | "handle" | "vote" | "rating" | "submit" | "comment" | "comment-edit" | "comment-delete" | "report";
+export type ReaderAction = "me" | "handle" | "vote" | "rating" | "submit" | "comment" | "comment-edit" | "comment-delete" | "report" | "flag";
 
 export interface ReaderActionEvent {
   publication: string;

package/package.json

@@ -361,6 +361,7 @@
     "./app/api/reader/comment/delete/route": "./app/api/reader/comment/delete/route.ts",
     "./app/api/reader/comment/edit/route": "./app/api/reader/comment/edit/route.ts",
     "./app/api/reader/comment/route": "./app/api/reader/comment/route.ts",
+    "./app/api/reader/flag/route": "./app/api/reader/flag/route.ts",
     "./app/api/reader/handle/route": "./app/api/reader/handle/route.ts",
     "./app/api/reader/me/route": "./app/api/reader/me/route.ts",
     "./app/api/reader/rating/route": "./app/api/reader/rating/route.ts",
@@ -433,7 +434,7 @@
       "optional": true
     }
   },
-  "version": "5.30.0",
+  "version": "5.31.0",
   "dependencies": {
     "@aws-amplify/adapter-nextjs": "^1.7.3",
     "@aws-crypto/sha256-js": "5.2.0",

package/routes.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "5.30.0",
+  "version": "5.31.0",
   "routes": [
     {
       "file": "app/%5F_preview/[[...path]]/route.ts",
@@ -295,6 +295,17 @@
         "runtime": "\"nodejs\""
       }
     },
+    {
+      "file": "app/api/reader/flag/route.ts",
+      "hasDefault": false,
+      "exports": [
+        "POST"
+      ],
+      "config": {
+        "dynamic": "\"force-dynamic\"",
+        "runtime": "\"nodejs\""
+      }
+    },
     {
       "file": "app/api/reader/handle/route.ts",
       "hasDefault": false,